10.0.0 Preview 1

[commonsensesoftware]

This is a major release that includes new, publicly visible API changes as well as a rollup of bug fixes. This is an initial preview release that is primarily focused on improving OpenAPI integration. Additional features will come in the next preview. The wiki has not be fully updated - yet, but that will also occur in the near future.

These are preview features and changes. Please report issues if you find them. Feel free to start a discussion about the changes in the forthcoming official release.

Features

All Platforms

• Support for the deprecation response header as defined by RFC 9745 (Support for the "Deprecation" Response Header (RFC 9745) #1128)

ASP.NET Core

• Integration with the Microsoft.AspNetCore.OpenApi library
  • These features in the new Asp.Versioning.OpenApi library
  • OpenAPI documents are now generated per API version
  • Sunset and deprecation policies are automatically included with standard (English) text, but can be customized
  • Sunset and deprecation policies links are included in OpenAPI documents via the x-api-versioning extension
  • The versioned HttpClient can now read and report on sunset and deprecation policies
  • All example projects have been updated to use Scalar

Example

The following provides an example of a bare minimum setup:

var builder = WebApplication.CreateBuilder( args );
var services = builder.Services;

services.AddApiVersioning()
        .AddApiExplorer()
        .AddOpenApi();

var app = builder.Build();
var hello = app.NewVersionedApi( "HelloWorld" );
var v1 = hello.MapGroup( "/hello-world" ).HasApiVersion( 1.0 );
var v2 = hello.MapGroup( "/hello-world" ).HasApiVersion( 2.0 );

v1.MapGet( "/", ( ApiVersion version ) => $"Hello world from v{version}" );
v2.MapGet( "/", ( ApiVersion version ) => $"Hello world from v{version}" );

if ( app.Environment.IsDevelopment() )
{
    app.MapOpenApi().WithDocumentPerVersion();
}

app.Run();

The key differences from what you may be currently doing:

1. The calls to services.AddOpenApi( "v1" ) and so on are no longer used or needed
2. app.MapOpenApi() has a supplemental .WithDocumentPerVersion() extension that enables multiple OpenAPI documents

In the same way that you can configure sunset policies, you can now specify deprecation policies:

services.AddApiVersioning()
        .AddApiExplorer( options =>
         {
			options.Policies.Deprecate( 0.9 )
			                .Effective( DateTimeOffset.Now )
			                .Link( "policy.html" )
			                    .Title( "Deprecation Policy" )
			                    .Type( "text/html" );
         })
        .AddOpenApi();

Fixes

ASP.NET Core

API Explorer

• Include Description property when cloning (Library breaks endpoint response metadata #1160)

Breaking Changes

Breaking changes are always something to be taken seriously and should occur as infrequently as possible. When they do occur, they should occur at a clear, major version boundary. Breaking changes in the project will align to the .NET platform Long-Term Support (LTS) strategy. .NET 10 is a LTS version so now is the version to introduce these changes.

.NET 10 and C# 14 introduce extension members, which finally affords defining API Versioning extensions the way they were intended. More specifically, there are a number of extension properties that could not be written as such in the past. Extension properties enable more succinct code and express the intent where an extension method was the only option in the past. These make up the majority of the breaking changes, but unless you are an API Versioning extender or perform deep customization, you'll likely not notice any changes.

All Platforms

The introduction of deprecation polices highlighted the opportunity to genericize policy management and there is no longer a need for the sunset policy specific implementations. The function names and signatures remain the same, but the following types have been replaced:

• ISunsetPolicyManager → IPolicyManager<SunsetPolicy>
• ISunsetPolicyBuilderExtensions → IPolicyBuilderExtensions
• ISunsetPolicyManagerExtensions → IPolicyManagerExtensions

ASP.NET Web API

The following extension methods are now extension properties.

• HttpRequestMessage
  • GetApiVersioningOptions() → ApiVersioningOptions { get; }
  • GetApiVersioningProperties() → ApiVersioningProperties { get; }
  • GetRequestedApiVersion() → RequestedApiVersion { get; }
• HttpActionDescriptor
  • GetApiVersionMetadata(), SetApiVersionMetadata() → ApiVersionMetadata { get; set; }
• HttpConfiguration
  • GetApiVersioningOptions() → ApiVersioningOptions { get; }
• HttpControllerDescriptor
  • GetApiVersionModel(), SetApiVersionModel() → ApiVersionModel { get; set; }

API Explorer

The following extension methods are now extension properties.

• ApiDescription
  • GetApiVersion() → ApiVersion { get; }
  • IsDeprecated() → IsDeprecated { get; }
  • GetGroupName() → GroupName { get; }
  • GetUniqueID() → UniqueID { get; }

OData

The following extension methods are now extension properties.

• IEdmModel
  • GetApiVersion() → ApiVersion { get; }
  • IsAdHoc() → IsAdHoc { get; }

OData API Explorer

The following extension methods are now extension properties.

• ApiDescription
  • EdmModel() → EdmModel { get; }
  • EntitySet() → EntitySet { get; }
  • EntityType() → EntityType { get; }
  • Operation() → Operation { get; }
  • RoutePrefix() → RoutePrefix { get; }

ASP.NET Core

The following extension methods are now extension properties.

• HttpContext
  • ApiVersioningFeature() → ApiVersioningFeature { get; }
  • GetRequestedApiVersion() → RequestedApiVersion { get; }

MVC (Core)

The following types and members have been removed:

• DefaultApiVersionGroupDescriptionProvider, which was internally identical to GroupedApiVersionDescriptionProvider
• Obsolete constructor public EndpointApiVersionMetadataCollationProvider( EndpointDataSource endpointDataSource )
• Removed IServiceCollectionExtensions.EnableApiVersionBinding; it's now supported without explicit registration

The following extension methods are now extension properties.

• ActionDescriptor
  • GetApiVersionMetadata() → ApiVersionMetadata { get; }
• ControllerModel
  • GetApiVersionModel() → ApiVersionModel { get; }

API Explorer

The following extension methods are now extension properties.

• ApiDescription
  • GetApiVersion(), SetApiVersion() → ApiVersion { get; set; }
  • IsDeprecated() → IsDeprecated { get; }
  • GetSunsetPolicy(), SetSunsetPolicy() → SunsetPolicy { get; set; }

OData

The following extension methods are now extension properties.

• IEdmModel
  • GetApiVersion() → ApiVersion { get; }
  • IsAdHoc() → IsAdHoc { get; }

Versioned HTTP Client

The following extension methods are now extension properties.

• HttpResponseMessage
  • ReadSunsetPolicy() → SunsetPolicy { get; }

Contributors

• Huge thanks to @MGessinger who implemented most of the new deprecation header support (Support Deprecation header #1151)

---

This discussion was created from the release 10.0.0 Preview 1.