Release list

10.2.0 Latest

Latest

commonsensesoftware released this 06 Aug 04:51

v10.2.0

b064555

This release includes some big new features but is fully backward compatible with 10.0.0. The new features include versioned model member filtering, Roslyn analyzers, gRPC preview support, and a number of servicing patches since the previous release.

Fixes

All Platforms

Parsing an API version whose status ends in '.' no longer succeeds silently
Very large padding values in a format string no longer cause a stack overflow
Incorrect lower and upper bounds when matching API version ranges
Parsing a positive integer no longer allows whitespace or a leading '-'

ASP.NET Core

Routes are no longer incorrectly evicted from the route table (#1138)
Fixed routing of unversioned endpoints
Fixed extracting an API version that includes a status when versioning by URL segment (#1187)
A user-registered IProblemDetailsWriter is preserved by AddApiVersioning() (#1191)

ASP.NET Core OpenAPI

Support for more XML comment tags (#1205)
Fixed the error message reported for an unmapped JSON property
Fixed descriptions applied to filtered members

Features

All Platforms

New ApiVersionRange type for matching a set of API versions using the same interval notation as a package version
- 1.0 → x ≥ 1.0
- [1.0] → x == 1.0
- (1.0,) → x > 1.0
- (,1.0] → x ≤ 1.0
- [1.0,2.0) → 1.0 ≤ x < 2.0
- Multiple rules are combined as a logical or; ApiVersionRange.Any and ApiVersionRange.Empty are provided for
  the degenerate cases
- A range matches API versions; it does not define them. API versions must still be explicitly declared
New VisibleInApiVersionAttribute indicates the range of API versions a data member is visible in; for example,
[VisibleInApiVersion("2.0")]
New IAnnotation<TKey, TValue> abstraction for associating out-of-band metadata with a member
[StringSyntax] is now applied to API version inputs so the IDE and analyzers understand them; the recognized
syntaxes are ApiVersion, ApiVersionRange, and ApiVersionFormat

Analyzers

API Versioning now ships Roslyn analyzers. There is no new package to install — the core rules are packed into Asp.Versioning.Abstractions and the API rules are packed into Asp.Versioning.Http, so any application that already references API Versioning picks them up transitively.

There is an initial set of 31 rules. You can find all of the rule information in the new diagnostics wiki topic.

Notes:

Every rule has a helpLinkUri that resolves to its documentation page
Individual rules can be configured through .editorconfig as usual
All analyzers can be turned off with a single MSBuild property:
```
<PropertyGroup>
  <EnableApiVersioningAnalyzers>false</EnableApiVersioningAnalyzers>
</PropertyGroup>
```
ExcludeAssets="analyzers" on a PackageReference will not work because the package is also reached through
the dependencies of other packages and NuGet combines the assets from every path

ASP.NET Web API (Classic) is not currently supported. If there is demand, I will consider the support, but I presume
little new development is happening on the older platform.

ASP.NET Core

Data members can now be versioned independently of the endpoint that returns them. Annotate a property with [VisibleInApiVersion] and the member is omitted from responses for API versions outside the range:

public class Person
{
    public int Id { get; set; }

    public string FirstName { get; set; }

    [VisibleInApiVersion( "2.0" )]
    public Address? HomeAddress { get; set; }

    [VisibleInApiVersion( "[1.0,2.0)" )]
    public string? LegacyEmail { get; set; }
}

Works for both Minimal APIs and MVC (Core)
Filtering members is currently only support for the JSON media type
Filtering applies on the way in as well as the way out, which closes the corresponding over-posting gap
AddApiVersioning() now registers IHttpContextAccessor so the requested API version is available during
serialization
[VisibleInApiVersion] is part of the core abstractions and can be used in your model libraries without any
dependency on ASP.NET

ASP.NET Core API Explorer

The API explorer describes only the model members visible in the API version being explored via the new
VersionedModelMetadata, VersionedModelMetadataProvider, and DelegatingModelMetadata types
Only models that are actually explored are filtered for visibility

ASP.NET Core OpenAPI

Generated schemas reflect per-version member visibility, so the documented shape of a model matches what the API
actually returns for that version
Significantly expanded XML comment support:
- <remarks> now takes precedence over <description>
- <b> and <i> are converted to and retained as Markdown
- <a href="..."/> is converted to and retained as a hyperlink
- <paramref name="..."/> is rendered as inline code
- <list>, <item>, <term>, <description>, <value>, and <example> are supported
- <inheritdoc/> is resolved for summaries
- Multi-line code fences from <code> blocks are properly closed

ASP.NET Core with gRPC (Preview)

Two new packages add API Versioning to gRPC services: Asp.Versioning.Grpc and Asp.Versioning.Grpc.ApiExplorer. This is a new set of features that will run in preview to give gRPC service authors a chance to try things out and report any issues or gaps.

The following is a basic example showing all of the parts coming together.

services.AddApiVersioning()
        .AddGrpc()
        .AddGrpcApiExplorer()
        .AddOpenApi();

var people = app.NewVersionedApi( "People" );

people.MapGrpcService<PeopleService>()
      .HasApiVersion( 1.0 )
      .HasApiVersion( 2.0 )
      .HasApiVersion( 3.0 );

Services are versioned with the same conventions used everywhere else — a single implementation can support several
API versions, or implementations can be split across versions

Message fields are annotated with the API versions they belong to using the new asp/api/annotations.proto:

import "asp/api/annotations.proto";

message Person {
    int32 id = 1;
    string first_name = 2;
    string last_name = 3;
    Address home_address = 4 [(asp.api.version) = "2.0"];
    string phone = 5 [(asp.api.version) = "3.0"];
}

The option is repeated, so a field split across disjoint ranges repeats the option
A field with no annotation is included in every API version

A server interceptor filters fields out of requests and responses — including streaming in both directions — so a
client on 1.0 can neither see nor post a field that was introduced in 3.0
JSON transcoded gRPC services are described by the API explorer and appear in the OpenAPI document with the API
version route segment and well-known protobuf types mapped to their correct schemas

The gRPC OpenAPI Example demonstrates an end-to-end working solution.

Breaking Changes

All Platforms

The analyzers are on by default. They ship inside Asp.Versioning.Abstractions and Asp.Versioning.Http, which
means upgrading turns them on for every project that references API versioning — directly or transitively. AV0012,
AV0018, and AV0019 default to error severity, so an existing application that trips one of them will fail to build
until the underlying problem is fixed, the rule is downgraded in .editorconfig, or
<EnableApiVersioningAnalyzers>false</EnableApiVersioningAnalyzers> is set. Before these rules existed, an
application should have either encountered runtime exceptions or not functioned as expected. These rules are catching
mistakes early rather than imposing specific dogma about how your application must be defined.

ASP.NET Core

AddApiVersioning() now calls AddHttpContextAccessor(). This is additive and should be transparent, but it does mean
IHttpContextAccessor is registered in applications that previously did not have it

Documentation

The wiki has served the community well for many years, but it had gotten tired and it was due for some much needed love and updates. I've reworked the wiki into a new GitHub Pages site using mdBook.

The wiki has been ported to GitHub Pages and is now published at dotnet.github.io/aspnet-api-versioning with search, per-page tables of contents, and side-by-side content for each supported flavor of ASP.NET
README badges and links throughout the repository now point at the new site
The old wiki pages still exist so that old links are not broken
- All future links should link to the new content

Why change?

There was little-to-no control over wiki page names, which makes it difficult for SEO
The wiki HTML support is much more limited that GitHub Pages
- Theming is also supported
The wiki was considerable in size, but you couldn't search it; now you can
The project started with ASP.NET Web API (Classic) a decade ago, but ASP.NET Core is now the de facto platform
- ASP.NET Core and Web API (Classic) have been split apart
- There will be overlap in search, but everything else is cleanly separated
Errors and updates. There has never been a good wa...

Assets 3

10.0.0

commonsensesoftware released this 21 Apr 18:39

v10.0.0

c97a8bd

The official release for 10.0 is here! In addition to the changes in the preview releases, there are a few additional changes.

Features

All Platforms

ApiVersionAttribute, MapToVersionAttribute, and AdvertiseApiVersionsAttribute all now have a constructor which can support the date format without being a string; for example, [ApiVersion(2026, 04, 01)]

ASP.NET Core OpenAPI

XmlCommentsTransformer is now resolved via DI, which allows it to be re-registered with a user-defined file path
Public types and members are now virtual for developer extensibility

Fixes

ASP.NET Core OpenAPI

Fix comparison between entry and calling assembly (#1175)
Ensure keyed services are registered with a lowercase key (#1176)
Fix nested key service resolution (#1177)
Implement IKeyedServiceProvider when injecting ApiVersion (#1178)

Breaking Changes

ASP.NET Core OpenAPI

OpenAPI documents use "enum": ["1.0"] instead of "default": "1.0"
- This has a similar effect, but removes the free-form input when the value is bounded
- When optional, the enum value can still be deleted/removed
- Some UIs, such as Scalar, still provide a way to provide an enumerated value that isn't in the list

Release Notes

Asp.Versioning.OData is being released as rc.1 because Microsoft.AspNetCore.OData is only at preview.2
Asp.Versioning.OpenAPI is being released as rc.1 pending the outcome of dotnet/aspnetcore#66408
- If the package can be released without requiring the explicit use of Reflection, that is the preference
- No additional changes are planned unless bugs are reported

Feedback

Thanks to the contributors on this release whether it was code contributions or test driving the previews. Special thanks to @sander1095 for being a strong advocate and helping to bring even more visibility to the project.

Contributors

sander1095

Assets 3

3 Join discussion

10.0.0 Preview 2 Pre-release

Pre-release

commonsensesoftware released this 12 Mar 13:55

v10.0.0-preview.2

f54eb43

This release is a quick iteration which contains minor fixes based on feedback from Preview 1.

Trying out previews is always a big ask. The OpenAPI extensions are net new, so I really am looking for some community support to flush out any edge cases I may have been missed before releasing officially. All other libraries are stable.

Aside from whatever the community may report, there are only two final things I'm considering for the final release:

gRPC versioning support, which I'm waiting on grpc/grpc-dotnet#2690 and grpc/grpc-dotnet#2693
Coordination with Microsoft to open up types in Microsoft.AspNetCore.OpenAPI so I don't have to resort to Reflection for integration

If these are not able to be completed within the next few weeks, then I will officially release the stable libraries. The gRPC support will then come in a future, likely minor version, release. The OpenAPI extensions may stay in preview as AOT will likely be broken.

Features

All Platforms

Support _ prefix character when extracting API versions from a .NET namespace (#1172)
Generate software bill of materials (SBOM) (#1100)

Fixes

ASP.NET Core with OpenAPI

Build-time OpenAPI documents have empty paths (#1165, #1168)
Missing XML Comments (#1169)
Support <example> tags (#1170)

Breaking Changes

The OpenAPI extensions for API Versioning (e.g. x-api-versioning) will now use a nested links property rather than a simple array. This allows the schema to be open for possible future enhancements.

Preview 1

{
    "x-api-versioning":
    [
        {
            "title": "Version Policy",
            "type": "text/html",
            "rel": "info",
            "url": "http://my.api.com/policies/versioning.html"
        }
    ]
}

Preview 2+

{
    "x-api-versioning":
    {
        "links":
        [
            {
                "title": "Version Policy",
                "type": "text/html",
                "rel": "info",
                "url": "http://my.api.com/policies/versioning.html"
            }
        ]
    }
}

Contributors

Thanks to @sander1095 for reporting and fixing the OpenAPI document generation in Minimal APIs (#1165)
Thanks to @xavierjohn for adding enhanced support to allow namespaces that start with _ (#1172)

Contributors

xavierjohn and sander1095

Assets 3

10.0.0 Preview 1 Pre-release

Pre-release

commonsensesoftware released this 16 Feb 07:45

v10.0.0-preview.1

e6a074a

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 (#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:

The calls to services.AddOpenApi( "v1" ) and so on are no longer used or needed
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 (#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