ServiceFoundry.ContractEvolution 0.1.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package ServiceFoundry.ContractEvolution --version 0.1.0
                    


                    

                
NuGet\Install-Package ServiceFoundry.ContractEvolution -Version 0.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="ServiceFoundry.ContractEvolution" Version="0.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ServiceFoundry.ContractEvolution" Version="0.1.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="ServiceFoundry.ContractEvolution" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add ServiceFoundry.ContractEvolution --version 0.1.0
                    


                    

                
#r "nuget: ServiceFoundry.ContractEvolution, 0.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package ServiceFoundry.ContractEvolution@0.1.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=ServiceFoundry.ContractEvolution&version=0.1.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=ServiceFoundry.ContractEvolution&version=0.1.0
                    


                            Install as a Cake Tool

ServiceFoundry.ContractEvolution

Versioned contract evolution for .NET — register API or message contract versions, resolve multi-hop upgrade paths, assess compatibility, and catch unsafe maps before compile time with the included Roslyn analyzer.

Packages

Package Purpose
ServiceFoundry.ContractEvolution Core registry, engine, and upgrade DSL
ServiceFoundry.ContractEvolution.AspNetCore Request version reading and body upgrade middleware
ServiceFoundry.ContractEvolution.Testing Assertion helpers for unit and integration tests
ServiceFoundry.ContractEvolution.Reporting Text and JSON report writers
ServiceFoundry.ContractEvolution.Analyzers Roslyn analyzer (SFCE001)

Install

dotnet add package ServiceFoundry.ContractEvolution
dotnet add package ServiceFoundry.ContractEvolution.Analyzers  # analyzer, development-only

Getting started

// 1. Register contract versions and their upgrade maps
builder.Services.AddContractEvolution(evolution =>
{
    evolution.ForContract<OrderContract>(contract =>
    {
        contract.Version<OrderV1>("v1");
        contract.Latest<OrderV2>("v2");

        contract.Map<OrderV1, OrderV2>("v1", "v2", map =>
        {
            // Same-named properties are copied automatically.
            // Provide explicit rules for additions, renames, and computed values.
            map.Default(o => o.Currency, "USD");
        });
    });
});

// 2. Upgrade at runtime
var result = engine.Upgrade<OrderContract, OrderV2>(incomingPayload, sourceVersion: "v1");
var upgraded = result.Value;  // OrderV2 with Currency = "USD"

The MissingTargetBindingAnalyzer (SFCE001) will warn at build time if Currency above were omitted from the map entirely.

Runtime behaviour when no path exists

If ResolvePlan or Upgrade is called for a source/target pair with no registered upgrade path, a ContractEvolutionValidationException is thrown containing the list of diagnostics. If the registration itself is invalid (e.g. a cycle or an ambiguous path), the exception is thrown at Build() time, before the app starts.

Features

  • Typed DSL: Version, Latest, Map, Copy, Rename, Default, Compute
  • Multi-hop BFS path resolution
  • Compatibility assessment: Compatible, Upgradeable, Breaking
  • Graph validation at Build() time (cycles, ambiguous paths, missing bindings)
  • Text and JSON report writers via ContractEvolution.Reporting
  • SFCE001 Roslyn analyzer — warns on unmapped target properties at compile time
  • ASP.NET Core request-body upgrade hook

See samples/ContractEvolution/README.md for additional examples.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on ServiceFoundry.ContractEvolution:

Package Downloads
ServiceFoundry.ContractEvolution.Reporting

Report writers for ServiceFoundry.ContractEvolution — generate human-readable text or structured JSON reports of your registered contract families, versions, and upgrade paths.
ServiceFoundry.ContractEvolution.Testing

Test helpers for ServiceFoundry.ContractEvolution — assertion extensions for upgrade plans, compatibility results, and contract registration validation in unit and integration tests.
ServiceFoundry.ContractEvolution.AspNetCore

ASP.NET Core integration for ServiceFoundry.ContractEvolution — request version reading, automatic request-body upgrade middleware, and endpoint metadata helpers for versioned API surfaces.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0 132 5/23/2026