Skip to content

6.0.0 Preview 1

Pre-release
Pre-release
Compare
Choose a tag to compare
@commonsensesoftware commonsensesoftware released this 07 Apr 06:11
· 252 commits to main since this release
v6.0.0-preview.1
fe0a4ba

This is the first preview release, which includes support for .NET 6.0. Be sure to follow the announcement for more background and the roadmap for in-depth review of the release.

The wiki has not been updated, but it's a work in progress. While the wiki has been useful and informative, it is reaching the limits of what is possible. Consideration is being made to lift the current wiki into a fully-fledged documentation website. All of the examples have been updated and include new examples such as Minimal APIs. This is currently the best place to start and review how things have changed.

Features

  • Sunset Policies (RFC 8594)
  • Web Linking (RFC 8288)
  • API version-aware HTTP clients
    • ex: services.AddHttpClient("test").AddApiVersion(1.0)
    • If the server reports API versions, the use of deprecated API versions and their sunset polices are passed to ILogger

ASP.NET Core

  • Support .NET 6.0 (LTS)
  • Support Minimal APIs
  • Support OData 8.0 (finally! 🎉)

Enhancements

All Platforms

  • Performance (ex: more Span<T>, no Regex, fewer allocations, etc)
  • ApiVersion and related attributes now allows double (ex: new ApiVersion(1.0), [ApiVersion(1.0)])
  • ApiVersion.Status now allows . (ex: 2.0-beta.1, 2022-04-01-preview.1)
  • ApiVersion.Parse is supplanted by IApiVersionParser via ApiVersionParser.Default
    • This now makes end-to-end customization of ApiVersion possible (ex: you can add, parse, and format a patch or revision version component if you really want it)
  • All errors now use Problem Details (RFC 7807)
  • 404, 405, and 415 are now properly returned in accordance with configured versioning methods without requiring additional configuration or customization
  • Namespace-to-API Version parsing has been lifted out into NamespaceParser
    • You can extend/customize the behavior or simply use NamespaceParser.Default for the same old out-of-the-box implementation

.NET 6.0

  • ApiVersion supports ISpanFormattable

ASP.NET Web API

  • .NET Framework 4.5 is still supported, but .NET Framework 4.7.2 is added as a target for performance benefits when supported
  • UrlHelper.WithoutApiVersion() extension (useful when generating links from versioned to version-neutral routes)

ASP.NET Core

  • IUrlHelper.WithoutApiVersion() extension (useful when generating links from versioned to version-neutral endpoints)

Fixes

All of the open issues that could be fixed, have been fixed in this release. These will listed in the forthcoming 5.1 release, but it includes 65+ issues. I will accept reported issues and backport them to 5.1 if they are applicable.

Breaking Changes

This release is essentially a reset and rewrite so many things will be broken from 5.x. The most obvious issues will be new packages. Here is the mapping of old packages to new packages:

Old Package ID New Package ID
Asp.Versioning.Abstractions
Microsoft.AspNet.OData.Versioning Asp.Versioning.WebApi.OData
Microsoft.AspNet.OData.Versioning.ApiExplorer Asp.Versioning.WebApi.OData.ApiExplorer
Microsoft.AspNet.WebApi.Versioning Asp.Versioning.WebApi
Microsoft.AspNet.WebApi.Versioning.ApiExplorer Asp.Versioning.WebApi.ApiExplorer
Asp.Versioning.Http
Asp.Versioning.Http.Client
Microsoft.AspNetCore.Mvc.Versioning Asp.Versioning.Mvc
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer Asp.Versioning.Mvc.ApiExplorer
Microsoft.AspNetCore.OData.Versioning Asp.Versioning.OData
Microsoft.AspNetCore.OData.Versioning.ApiExplorer Asp.Versioning.OData.ApiExplorer

The second obvious big change will be different namespaces. All previous Microsoft.* namespaces are now Asp.Versioning.*. If you are a library author that targets multiple platforms, this should make things easier going forward; it certainly made it easier in the project itself. Extension methods continue to use the same namespace as the type they correspond to.

Significant individual changes:

  • IApiVersionReader.Read now returns IReadOnlyList<string> instead of string?
    • Solves the problem of multiple values for a single key (ex: query string or header)
    • Simplifies reader composition (which naturally may have multiple values)
    • Makes reading duplicate values non-exceptional, which is also valuable in error reporting
  • IReportApiVersions.Report now accepts the entire response instead of just headers
  • IErrorResponseProvider no longer exists; it is supplanted by IProblemDetailsFactory and Problem Details (RFC 7807)
  • The following old extension methods were moved to the new ApiVersionMetadata type:
    • GetApiVersionModel(ApiVersionMapping) → GetApiVersionMetadata()
    • GetApiVersionModel() → ApiVersionMetadata.Map(ApiVersionMapping.Explicit)
    • MappingTo(ApiVersion) → ApiVersionMetadata.MappingTo(ApiVersion)
    • IsMappedTo(ApiVersion) → ApiVersionMetadata.IsMappedTo(ApiVersion)

Routing behavior has changed to more accurately return 404, 405, or 415 when appropriate. 400 is still returned in known, invalid requests such as an unspecified API version when required.

For ASP.NET Core, the setup is now a fluent interface of chained configuration options:

services.AddApiVersioning()     // Core API Versioning services with support for Minimal APIs
        .AddMvc()               // API versioning extensions for MVC Core
        .AddApiExplorer()       // API version-aware API Explorer extensions
        .AddOData()             // API versioning extensions for OData
        .AddODataApiExplorer(); // API version-aware API Explorer extensions for OData

Future Release

The following are features and enhancements still under consideration before the final release:

Feedback

I want to hear your feedback. What do you like? What do you not like? I want to give the community a chance to play with the latest bits and provide any final thoughts before committing to the final release. Now would be the time for any other name changes or other significant refactoring that could cause additional disruption going forward.

Administrative

TL;DR

  • This project is now officially part of the .NET Foundation (🎉)
  • Code signing still isn't setup, which will hold up the official release, including the 5.x patches
Assets 2
Loading
44 Join discussion