Initial refactoring to support type interleaving and action-level API versions

Author: Chris Martinez

samples/webapi/SwaggerODataWebApiSample/Startup.cs

@@ -51,7 +51,7 @@ public void Configuration( IAppBuilder builder )
             };
             var models = modelBuilder.GetEdmModels();
 
-            // TODO: while you can use both, you should choose only ONE of the following; comment, uncomment, or remove as necessary
+            // INFO: while you can use both, you should choose only ONE of the following; comment, uncomment, or remove as necessary
 
             // WHEN VERSIONING BY: query string, header, or media type
             configuration.MapVersionedODataRoutes( "odata", routePrefix, models, ConfigureContainer );

src/Common/AdvertiseApiVersionsAttribute.cs

@@ -18,11 +18,13 @@ namespace Microsoft.AspNetCore.Mvc
     /// </summary>
     /// <remarks>Advertised service API versions indicate the existence of other versioned services, but the implementation of those
     /// services are implemented elsewhere.</remarks>
-    [AttributeUsage( Class, AllowMultiple = true, Inherited = false )]
+    [AttributeUsage( Class | Method, AllowMultiple = true, Inherited = false )]
     [SuppressMessage( "Microsoft.Design", "CA1019:DefineAccessorsForAttributeArguments", Justification = "An accessor property is provided, but the values are typed; not strings." )]
     [SuppressMessage( "Microsoft.Performance", "CA1813:AvoidUnsealedAttributes", Justification = "Allows extensibility." )]
-    public partial class AdvertiseApiVersionsAttribute : ApiVersionsBaseAttribute, IApiVersionProvider
+    public class AdvertiseApiVersionsAttribute : ApiVersionsBaseAttribute, IApiVersionProvider
     {
+        ApiVersionProviderOptions options = ApiVersionProviderOptions.Advertised;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="AdvertiseApiVersionsAttribute"/> class.
         /// </summary>
@@ -49,15 +51,29 @@ public AdvertiseApiVersionsAttribute( string version ) : base( version ) { }
         public AdvertiseApiVersionsAttribute( params string[] versions ) : base( versions ) { }
 
 #pragma warning disable CA1033 // Interface methods should be callable by child types
-        bool IApiVersionProvider.AdvertiseOnly => true;
+        ApiVersionProviderOptions IApiVersionProvider.Options => options;
 #pragma warning restore CA1033 // Interface methods should be callable by child types
 
         /// <summary>
         /// Gets or sets a value indicating whether the specified set of API versions are deprecated.
         /// </summary>
         /// <value>True if the specified set of API versions are deprecated; otherwise, false.
         /// The default value is <c>false</c>.</value>
-        public bool Deprecated { get; set; }
+        public bool Deprecated
+        {
+            get => ( options & ApiVersionProviderOptions.Deprecated ) == ApiVersionProviderOptions.Deprecated;
+            set
+            {
+                if ( value )
+                {
+                    options |= ApiVersionProviderOptions.Deprecated;
+                }
+                else
+                {
+                    options &= ~ApiVersionProviderOptions.Deprecated;
+                }
+            }
+        }
 
         /// <summary>
         /// Returns a hash code for the current instance.

src/Common/ApiVersionAttribute.cs

@@ -16,11 +16,13 @@ namespace Microsoft.AspNetCore.Mvc
     /// <summary>
     /// Represents the metadata that describes the <see cref="ApiVersion">API versions</see> associated with a service.
     /// </summary>
-    [AttributeUsage( Class, AllowMultiple = true, Inherited = false )]
+    [AttributeUsage( Class | Method, AllowMultiple = true, Inherited = false )]
     [SuppressMessage( "Microsoft.Design", "CA1019:DefineAccessorsForAttributeArguments", Justification = "An accessor property is provided, but the values are typed; not strings." )]
     [SuppressMessage( "Microsoft.Performance", "CA1813:AvoidUnsealedAttributes", Justification = "Allows extensibility." )]
-    public partial class ApiVersionAttribute : ApiVersionsBaseAttribute, IApiVersionProvider
+    public class ApiVersionAttribute : ApiVersionsBaseAttribute, IApiVersionProvider
     {
+        ApiVersionProviderOptions options = ApiVersionProviderOptions.None;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="ApiVersionAttribute"/> class.
         /// </summary>
@@ -34,15 +36,29 @@ protected ApiVersionAttribute( ApiVersion version ) : base( version ) { }
         public ApiVersionAttribute( string version ) : base( version ) { }
 
 #pragma warning disable CA1033 // Interface methods should be callable by child types
-        bool IApiVersionProvider.AdvertiseOnly => false;
+        ApiVersionProviderOptions IApiVersionProvider.Options => options;
 #pragma warning restore CA1033 // Interface methods should be callable by child types
 
         /// <summary>
         /// Gets or sets a value indicating whether the specified set of API versions are deprecated.
         /// </summary>
         /// <value>True if the specified set of API versions are deprecated; otherwise, false.
         /// The default value is <c>false</c>.</value>
-        public bool Deprecated { get; set; }
+        public bool Deprecated
+        {
+            get => ( options & ApiVersionProviderOptions.Deprecated ) == ApiVersionProviderOptions.Deprecated;
+            set
+            {
+                if ( value )
+                {
+                    options |= ApiVersionProviderOptions.Deprecated;
+                }
+                else
+                {
+                    options &= ~ApiVersionProviderOptions.Deprecated;
+                }
+            }
+        }
 
         /// <summary>
         /// Returns a hash code for the current instance.

src/Common/ApiVersionNeutralAttribute.cs

@@ -15,7 +15,7 @@ namespace Microsoft.AspNetCore.Mvc
     /// <summary>
     /// Represents the metadata to indicate a service is API version neutral.
     /// </summary>
-    [AttributeUsage( Class, AllowMultiple = false, Inherited = true )]
+    [AttributeUsage( Class | Method, AllowMultiple = false, Inherited = true )]
     public sealed class ApiVersionNeutralAttribute : Attribute, IApiVersionNeutral
     {
     }

src/Common/CollectionExtensions.cs

@@ -76,5 +76,26 @@ internal static string EnsureZeroOrOneApiVersions( this ICollection<string> apiV
 
             throw new AmbiguousApiVersionException( message, apiVersions.OrderBy( v => v ) );
         }
+
+        internal static void UnionWith<T>( this ICollection<T> collection, IEnumerable<T> other )
+        {
+            Contract.Requires( collection != null );
+            Contract.Requires( other != null );
+
+            if ( collection is ISet<T> set )
+            {
+                set.UnionWith( other );
+            }
+            else
+            {
+                foreach ( var item in other )
+                {
+                    if ( !collection.Contains( item ) )
+                    {
+                        collection.Add( item );
+                    }
+                }
+            }
+        }
     }
 }

src/Common/Common.projitems

@@ -22,33 +22,33 @@
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\AmbiguousApiVersionException.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionFormatProvider.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersioningOptions.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionMapping.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionModel.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionModelDebugView.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionModelExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionParameterLocation.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionProviderOptions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionReader.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ApiVersionsBaseAttribute.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Versioning\AttributeExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\ConstantApiVersionSelector.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilderBase.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilderCollection.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilderCollection{T}.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilderBase.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilder.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilder{T}.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilderExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionApiVersionConventionBuilderTExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ActionConventionBuilderExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ApiVersionConventionBuilder.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ControllerApiVersionConventionBuilderBase.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ApiVersionConventionBuilderBase.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ControllerApiVersionConventionBuilder.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ControllerApiVersionConventionBuilder{T}.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ControllerApiVersionConventionBuilderExtensions.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ControllerApiVersionConventionBuilderTExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\ExpressionExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\IActionConventionBuilder.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\IActionConventionBuilder{T}.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\IApiVersionConventionBuilderExtensions.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\IApiVersionConvention{T}.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\IControllerConventionBuilder.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\IApiVersionConventionBuilder.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\Conventions\VersionByNamespaceConvention.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\CurrentImplementationApiVersionSelector.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Versioning\DefaultApiVersionReporter.cs" />

src/Common/MapToApiVersionAttribute.cs

@@ -16,10 +16,13 @@ namespace Microsoft.AspNetCore.Mvc
     /// <summary>
     /// Represents the metadata that describes the <see cref="ApiVersion">API version</see>-specific implementation of a service.
     /// </summary>
+#if !WEBAPI
+    [CLSCompliant( false )]
+#endif
     [AttributeUsage( Method, AllowMultiple = true, Inherited = false )]
     [SuppressMessage( "Microsoft.Design", "CA1019:DefineAccessorsForAttributeArguments", Justification = "An accessor property is provided, but the values are typed; not strings." )]
     [SuppressMessage( "Microsoft.Performance", "CA1813:AvoidUnsealedAttributes", Justification = "Allows extensibility." )]
-    public partial class MapToApiVersionAttribute : ApiVersionsBaseAttribute, IApiVersionProvider
+    public class MapToApiVersionAttribute : ApiVersionsBaseAttribute, IApiVersionProvider
     {
         /// <summary>
         /// Initializes a new instance of the <see cref="MapToApiVersionAttribute"/> class.
@@ -34,9 +37,7 @@ protected MapToApiVersionAttribute( ApiVersion version ) : base( version ) { }
         public MapToApiVersionAttribute( string version ) : base( version ) { }
 
 #pragma warning disable CA1033 // Interface methods should be callable by child types
-        bool IApiVersionProvider.AdvertiseOnly => false;
-
-        bool IApiVersionProvider.Deprecated => false;
+        ApiVersionProviderOptions IApiVersionProvider.Options => ApiVersionProviderOptions.Mapped;
 #pragma warning restore CA1033 // Interface methods should be callable by child types
     }
 }

src/Common/Versioning/ApiVersionMapping.cs

@@ -0,0 +1,29 @@
+#if WEBAPI
+namespace Microsoft.Web.Http.Versioning
+#else
+namespace Microsoft.AspNetCore.Mvc.Versioning
+#endif
+{
+    using System;
+
+    /// <summary>
+    /// Represents the possible types of API version mappings.
+    /// </summary>
+    public enum ApiVersionMapping
+    {
+        /// <summary>
+        /// Indicates no mapping.
+        /// </summary>
+        None,
+
+        /// <summary>
+        /// Indicates an explicit mapping.
+        /// </summary>
+        Explicit,
+
+        /// <summary>
+        /// Indicates an implicit mapping.
+        /// </summary>
+        Implicit,
+    }
+}