Support API Version Using Namespace Convention

[commonsensesoftware]

Overview

It's a common scenario to use a namespace in the implementation of services as versioning boundary. By configuring API versioning to use this convention, any controller placed in a convention-based API version namespace will automatically have that API version applied.

Design

In order for the feature to work, the namespace name must still conform to the API version format so that it can be parsed. The language-neutral format in BNF will be:

'v' | 'V' : [<year> '-' <month> '-' <day>] : [<major[.minor]>] : [<status>]

Examples

• Contoso.Api.v1.Controllers → 1.0
• Contoso.Api.v1_1.Controllers → 1.1
• Contoso.Api.v0_9_Beta.Controllers → 0.9-Beta
• Contoso.Api.v20180401.Controllers → 2018-04-01
• Contoso.Api.v2018_04_01.Controllers → 2018-04-01
• Contoso.Api.v2018_04_01_Beta.Controllers → 2018-04-01-Beta
• Contoso.Api.v2018_04_01_1_0_Beta.Controllers → 2018-04-01.1.0-Beta

By default, API versions will be considered supported. If the controller is decorated with the ObsoleteAttribute, then the API version inferred from the containing namespace will be considered deprecated.

Tooling Integration

Compilers such as Visual C# and Visual Basic use folders to automatically define namespace hierarchies. Tools such Visual Studio will attempt to convert invalid namespace names to their safe equivalents. Unfortunately, the . character is considered a namespace delimiter. This character should be changed to _ so that newly added files have the correct format. In addition, Visual Studio will add a leading _ if the folder name starts with a number. Since a leading character will be required, the format will require that the first character must be v or V.

Additional Considerations

The design should consider other types of conventions. This might be an extension of the existing convention features.

[dave-sampson13]

Hi @commonsensesoftware, is there an ETA for version 3.0 (pre-release or release)? Keen to use this enhancement in our projects.

[commonsensesoftware]

Things have progressed nicely. I might be able to squeeze out a beta by end of week for folks to start trying out. I'm testing out the routing changes to see how it affects other middleware. It's a rather slow and manual process. =/

To give those following this a sense of how this enhancement will work, you'll now be able to create and define your own conventions (a la the new IControllerConvention interface) in addition to the standard conventions. In this release, the only new convention will be the version by namespace convention. The setup will look like:

options => options.Conventions.Add( new VersionByNamespaceConvention() );

[surenderssm]

This was awesome, Thank you @commonsensesoftware !!