DCoding.Data.DVault.Privacy 10.45.0

DVault

DVault is a focused .NET library family for Data Vault 2.x-oriented persistence on Entity Framework Core. It keeps the public surface close to EF Core: model metadata, generated DVault tables, explicit save/read services, provider-specific optimizations, analyzers, and source generators where they make EF usage safer or easier.

Contents

• Installation
• Quickstart
• Package Compatibility
• Documentation Map
• Current v0.45.0 Limitations
• Layout
• Local Validation
• License

Installation

Install the provider-neutral DVault package from NuGet and add the provider package that matches the database used by the application. The blocks below list the full coordinated package family so each needed package can be copied from one aligned line. Use exactly one package line for a consumer project: 8.45.0 for net8.0 and EF Core 8, or 10.45.0 for net10.0 and EF Core 10. Do not mix package lines, and do not use a consumer-facing 0.45.0 package version from the v0.45.0 release label. This documentation baseline does not by itself confirm package publication.

For net8.0 projects on EF Core 8, use the 8.45.0 package line:

dotnet add package DCoding.Data.DVault --version 8.45.0
dotnet add package DCoding.Data.DVault.Db2 --version 8.45.0
dotnet add package DCoding.Data.DVault.Sqlite --version 8.45.0
dotnet add package DCoding.Data.DVault.Postgres --version 8.45.0
dotnet add package DCoding.Data.DVault.MySql --version 8.45.0
dotnet add package DCoding.Data.DVault.Oracle --version 8.45.0
dotnet add package DCoding.Data.DVault.SqlServer --version 8.45.0
dotnet add package DCoding.Data.DVault.Privacy --version 8.45.0

For net10.0 projects on EF Core 10, use the 10.45.0 package line:

dotnet add package DCoding.Data.DVault --version 10.45.0
dotnet add package DCoding.Data.DVault.Db2 --version 10.45.0
dotnet add package DCoding.Data.DVault.Sqlite --version 10.45.0
dotnet add package DCoding.Data.DVault.Postgres --version 10.45.0
dotnet add package DCoding.Data.DVault.MySql --version 10.45.0
dotnet add package DCoding.Data.DVault.Oracle --version 10.45.0
dotnet add package DCoding.Data.DVault.SqlServer --version 10.45.0
dotnet add package DCoding.Data.DVault.Privacy --version 10.45.0

Install DCoding.Data.DVault.Privacy only when the application explicitly opts into the privacy extension seam. The package is a provider-neutral proof for registration, options, and alias-driven encrypted payload conversion; it does not make an application compliant, enable automatic encryption or redaction, or use provider-native encryption features.

Add the analyzer package only to projects that own DVault declarations, compile-time generated row mappings, or generated typed read helpers, and keep it local with PrivateAssets="all". Build projects that reference DCoding.Data.DVault.Analyzers with a .NET 10 SDK host, including net8.0 projects using the 8.45.0 package line. The current analyzer package carries one net10.0 analyzer asset for both coordinated package lines; this repository does not validate pure .NET 8 SDK analyzer consumption.

<ItemGroup>
  <PackageReference Include="DCoding.Data.DVault.Analyzers" Version="8.45.0" PrivateAssets="all" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="DCoding.Data.DVault.Analyzers" Version="10.45.0" PrivateAssets="all" />
</ItemGroup>

Applications still need their normal Entity Framework Core provider package, such as IBM.EntityFrameworkCore, Microsoft.EntityFrameworkCore.Sqlite, Npgsql.EntityFrameworkCore.PostgreSQL, Microsoft.EntityFrameworkCore.SqlServer, Oracle.EntityFrameworkCore, or a MySQL EF Core provider.

Quickstart

Use AddDVault(options => options.UseBinaryFirstProfile()) plus the provider extension package that matches the configured EF Core provider. For direct Code-First model projection, call ApplyDataVaultMetadataWithBinaryFirstProfile(...) when declaring the fluent model for a new binary-first schema. The existing UseDataVaultBinaryFirstProfile() plus ApplyDataVaultMetadata(...) setup remains supported. DVault persistence stays explicit: generated hub, link, and satellite rows are written through IDataVaultSaveService; ordinary EF entity tracking remains under the application's control.

The binary-first profile is the recommended physical storage profile for new projects. Existing databases and configurations are not migrated automatically; HexString-compatible setups remain valid until the application owner intentionally plans and executes a separate reviewed migration, reset, or data-move change. Use the Hash-Key Storage Migration Guide and its dvault.hash-key-storage-migration.v1 dry-run manifest before changing persisted hash-key storage. Logical and public hash-key values remain lowercase hexadecimal strings even when new projects choose binary physical storage.

using DCoding.Data.DVault;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

services.AddDVault(options => options.UseBinaryFirstProfile());
services.AddDVaultSqlite();

services.AddDbContext<SalesVaultContext>(options =>
    options.UseSqlite("Data Source=sales-vault.db"));

Declare Data Vault metadata in OnModelCreating with Code-First metadata, or provide a reviewed DataVaultMetadataModel / DataVaultMetadataRegistry when metadata should be shared across schema projection, saves, reads, diagnostics, and generated helper surfaces.

public sealed class SalesVaultContext(DbContextOptions<SalesVaultContext> options) : DbContext(options) {
  protected override void OnModelCreating(ModelBuilder modelBuilder) {
    modelBuilder.ApplyDataVaultMetadataWithBinaryFirstProfile(vault => {
      vault.Hub<Customer>(hub => {
        hub.BusinessKey(customer => customer.CustomerId);
        hub.Satellite("Profile", satellite => {
          satellite.Payload(customer => customer.Name);
          satellite.Payload(customer => customer.Status);
        });
      });

      vault.Hub<Order>(hub => hub.BusinessKey(order => order.OrderId));

      vault.Link("CustomerOrder", link => {
        link.Participant<Customer>();
        link.Participant<Order>();
      });
    });
  }
}

Callers own load timestamps, record sources, ordering, transactions, and the moment a DVault write happens.

var saveService = serviceProvider.GetRequiredService<IDataVaultSaveService>();

await saveService.SaveAsync(
    context,
    new DataVaultSaveRequest(
        DateTimeOffset.UtcNow,
        "crm-import",
        [
            new(new DataVaultHubMetadata("Customer", ["CustomerId"]), [new("CustomerId", "C-100")]),
        ],
        []),
    cancellationToken);

Provider packages can add optimized strategies behind the same public service contract. The shared surface also includes chunked/async saves, latest/as-of satellite reads, PIT and bridge maintenance/read services, diagnostics and explain metadata, support-bundle export, model-first governance, Roslyn analyzers, and opt-in typed read-model generation.

For runnable examples, the optional privacy proof, and fuller workflows, see Getting Started, examples/README.md, and the current DVault v0.45.0 Release Notes.

Package Compatibility

The current coordinated package baseline is documented in Package Compatibility and DVault v0.45.0 Release Notes. DVault has nine packable packages, two visible consumer package lines, target-specific dependency pins, a local analyzer package boundary, and an optional privacy proof package.

In short:

• 8.45.0 targets net8.0 and the EF Core 8 dependency line.
• 10.45.0 targets net10.0 and the EF Core 10 dependency line.
• v0.45.0 is a repository release tag and release-note label, not a NuGet package version.
• DCoding.Data.DVault.Analyzers remains a local PrivateAssets="all" analyzer reference and currently requires a .NET 10 SDK build host for both package lines.
• DCoding.Data.DVault.Privacy remains optional and opt-in; it provides registration and alias-driven encrypted payload conversion seams only, not compliance, automatic privacy execution, or provider-native encryption.
• Hash-key storage guidance now routes new projects to binary-first setup and existing persisted HexString setups to the migration guide and dry-run manifest path.

Documentation Map

Current v0.45.0 Limitations

• DVault is an EF Core library family, not a platform, scheduler, ingestion service, CLI, or provider provisioning tool.
• Package publication remains a manual release operation; this repository records package creation and verification, not NuGet publication.
• The analyzer package is validated against the .NET 10 SDK build-host baseline for both coordinated package lines; pure .NET 8 SDK analyzer consumption is not a current compatibility claim.
• Stored procedures and provider-specific SQL artifacts are not default write paths. Any artifact lane is explicit, design-time, review-owned, and outside normal persistence.
• Binary hash-key storage is opt-in physical storage for new schemas. Existing persisted HexString storage changes require a reviewed migration, reset, or data-move plan; public hash-key values remain lowercase hexadecimal strings.
• DB2 live-schema reading is available as external opt-in evidence through IBM.EntityFrameworkCore; DB2 databases, credentials, lifecycle cleanup, and CI isolation remain consumer-owned.
• Live PostgreSQL, SQL Server, Oracle, MySQL, and DB2 integration tests are opt-in behind local DVAULT_TEST_* connection strings. Default validation does not require external databases or containers.

Layout

• DVault.slnx: root build and test solution.
• src/DCoding.Data.DVault/: provider-neutral runtime package.
• src/DCoding.Data.DVault.*: provider extension packages for DB2, SQLite, PostgreSQL, SQL Server, Oracle, and MySQL, plus the optional privacy proof and analyzer/source-generator packages.
• tests/DCoding.Data.DVault.Tests/: unit, integration, public API, package-verifier, and provider test projects.
• examples/: runnable SQLite and PostgreSQL quickstarts.
• benchmarks/: local benchmark projects.
• docs/: release notes, architecture, planning, quality, validation, and adoption documentation.

Local Validation

Run the repository validation lane from a .NET 10 SDK checkout:

dotnet build DVault.slnx --nologo
dotnet test DVault.slnx --nologo
bash tools/pack-release-packages.sh
bash tools/verify-packages.sh
bash tools/check-format.sh

bash tools/pack-release-packages.sh creates the two coordinated package lines under artifacts/packages/: nine 8.45.0 packages with net8.0 assets and EF Core 8 dependency groups, and nine 10.45.0 packages with net10.0 assets and EF Core 10 dependency groups. bash tools/verify-packages.sh inspects those artifacts, expects exactly eighteen DVault .nupkg files plus sixteen matching symbol packages for the runtime, provider, and privacy packages, checks README, XML documentation, analyzer assets, declared NuGet metadata, and confirms each provider and privacy package depends on the packed DCoding.Data.DVault version from the same package line.

For provider-specific filters, environment variables, benchmark commands, and package-verification details, see Local Validation.

License

DVault uses the Apache License 2.0. See LICENSE.