Validate ApiVersioningOptions.DefaultApiVersion != ApiVersion.Neutral. Resolves #1011

Author: commonsensesoftware

src/AspNet/WebApi/src/Asp.Versioning.WebApi/SR.Designer.cs

@@ -150,6 +150,14 @@
   <data name="DirectRoute_AmbiguousController" xml:space="preserve">
     <value>Multiple controller types were found that match the URL. This can happen if attribute routes on multiple controllers match the requested URL.{1}{1}The request has found the following matching controller types: {0}</value>
   </data>
+  <data name="InvalidDefaultApiVersion" xml:space="preserve">
+    <value>{0}.{1} is an invalid value for {2}.{3}. Did you mean to apply {4} via attribute or convention instead?</value>
+    <comment>0 = ApiVersion
+1 = Neutral
+2 = ApiVersioningOptions
+3 = DefaultApiVersion
+4 = IApiVersionNeutral</comment>
+  </data>
   <data name="NoControllerSelected" xml:space="preserve">
     <value>A controller was not selected for request URI '{0}' and API version '{1}'.</value>
   </data>

src/AspNet/WebApi/src/Asp.Versioning.WebApi/SR.resx

@@ -5,6 +5,7 @@ namespace System.Web.Http;
 using Asp.Versioning;
 using Asp.Versioning.Controllers;
 using Asp.Versioning.Dispatcher;
+using System.Globalization;
 using System.Web.Http.Controllers;
 using System.Web.Http.Dispatcher;
 using static Asp.Versioning.ApiVersionParameterLocation;
@@ -65,6 +66,7 @@ public static void AddApiVersioning( this HttpConfiguration configuration, Actio
         var options = new ApiVersioningOptions();
 
         setupAction( options );
+        ValidateApiVersioningOptions( options );
         configuration.AddApiVersioning( options );
     }
 
@@ -97,6 +99,30 @@ private static void AddApiVersioning( this HttpConfiguration configuration, ApiV
         SunsetPolicyManager.Default = new SunsetPolicyManager( options );
     }
 
+    // ApiVersion.Neutral does not have the same meaning as IApiVersionNeutral. setting
+    // ApiVersioningOptions.DefaultApiVersion this value will not make all APIs version-neutral
+    // and will likely lead to many unexpected side effects. this is a best-effort, one-time
+    // validation check to help prevent people from going off the rails. if someone bypasses
+    // this validation by removing the check or updating the value later, then caveat emptor.
+    //
+    // REF: https://github.com/dotnet/aspnet-api-versioning/issues/1011
+    private static void ValidateApiVersioningOptions( ApiVersioningOptions options )
+    {
+        if ( options.DefaultApiVersion == ApiVersion.Neutral )
+        {
+            var message = string.Format(
+                CultureInfo.CurrentCulture,
+                SR.InvalidDefaultApiVersion,
+                nameof( ApiVersion ),
+                nameof( ApiVersion.Neutral ),
+                nameof( ApiVersioningOptions ),
+                nameof( ApiVersioningOptions.DefaultApiVersion ),
+                nameof( IApiVersionNeutral ) );
+
+            throw new InvalidOperationException( message );
+        }
+    }
+
     internal static IReportApiVersions GetApiVersionReporter( this HttpConfiguration configuration )
     {
         var options = configuration.GetApiVersioningOptions();

src/AspNet/WebApi/src/Asp.Versioning.WebApi/System.Web.Http/HttpConfigurationExtensions.cs

@@ -37,4 +37,17 @@ public void add_api_versioning_should_report_api_versions_when_option_is_enabled
         configuration.Services.GetActionSelector().Should().BeOfType<ApiVersionActionSelector>();
         configuration.Filters.Single().Instance.Should().BeOfType<ReportApiVersionsAttribute>();
     }
+
+    [Fact]
+    public void add_api_versioning_should_not_allow_default_neutral_api_version()
+    {
+        // arrange
+        var configuration = new HttpConfiguration();
+
+        // act
+        Action options = () => configuration.AddApiVersioning( options => options.DefaultApiVersion = ApiVersion.Neutral );
+
+        // assert
+        options.Should().Throw<InvalidOperationException>();
+    }
 }

src/AspNet/WebApi/test/Asp.Versioning.WebApi.Tests/System.Web.Http/HttpConfigurationExtensionsTest.cs

@@ -85,11 +85,12 @@ private static void AddApiVersioningServices( IServiceCollection services )
         }
 
         services.TryAddSingleton<IApiVersionParser, ApiVersionParser>();
-        services.Add( Singleton( sp => sp.GetRequiredService<IOptions<ApiVersioningOptions>>().Value.ApiVersionReader ) );
-        services.Add( Singleton( sp => (IApiVersionParameterSource) sp.GetRequiredService<IOptions<ApiVersioningOptions>>().Value.ApiVersionReader ) );
-        services.Add( Singleton( sp => sp.GetRequiredService<IOptions<ApiVersioningOptions>>().Value.ApiVersionSelector ) );
+        services.AddSingleton( sp => sp.GetRequiredService<IOptions<ApiVersioningOptions>>().Value.ApiVersionReader );
+        services.AddSingleton( sp => (IApiVersionParameterSource) sp.GetRequiredService<IOptions<ApiVersioningOptions>>().Value.ApiVersionReader );
+        services.AddSingleton( sp => sp.GetRequiredService<IOptions<ApiVersioningOptions>>().Value.ApiVersionSelector );
         services.TryAddSingleton<IReportApiVersions, DefaultApiVersionReporter>();
         services.TryAddSingleton<ISunsetPolicyManager, SunsetPolicyManager>();
+        services.TryAddEnumerable( Transient<IValidateOptions<ApiVersioningOptions>, ValidateApiVersioningOptions>() );
         services.TryAddEnumerable( Transient<IPostConfigureOptions<RouteOptions>, ApiVersioningRouteOptionsSetup>() );
         services.TryAddEnumerable( Singleton<MatcherPolicy, ApiVersionMatcherPolicy>() );
         services.TryAddEnumerable( Singleton<IApiVersionMetadataCollationProvider, EndpointApiVersionMetadataCollationProvider>() );

src/AspNetCore/WebApi/src/Asp.Versioning.Http/DependencyInjection/IServiceCollectionExtensions.cs

@@ -129,6 +129,14 @@
   <data name="ConventionAddedAfterEndpointBuilt" xml:space="preserve">
     <value>Conventions cannot be added after building the endpoint.</value>
   </data>
+  <data name="InvalidDefaultApiVersion" xml:space="preserve">
+    <value>{0}.{1} is an invalid value for {2}.{3}. Did you mean to apply {4} via attribute or convention instead?</value>
+    <comment>0 = ApiVersion
+1 = Neutral
+2 = ApiVersioningOptions
+3 = DefaultApiVersion
+4 = IApiVersionNeutral</comment>
+  </data>
   <data name="MultipleVersionSets" xml:space="preserve">
     <value>An endpoint cannot apply multiple API version sets.</value>
   </data>

src/AspNetCore/WebApi/src/Asp.Versioning.Http/SR.Designer.cs

@@ -0,0 +1,41 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning;
+
+using Microsoft.Extensions.Options;
+using System.Globalization;
+
+// ApiVersion.Neutral does not have the same meaning as IApiVersionNeutral. setting
+// ApiVersioningOptions.DefaultApiVersion this value will not make all APIs version-neutral
+// and will likely lead to many unexpected side effects. this is a best-effort, one-time
+// validation check to help prevent people from going off the rails. if someone bypasses
+// this validation by removing the check or updating the value later, then caveat emptor.
+//
+// REF: https://github.com/dotnet/aspnet-api-versioning/issues/1011
+#pragma warning disable CA1812 // Avoid uninstantiated internal classes
+internal sealed class ValidateApiVersioningOptions : IValidateOptions<ApiVersioningOptions>
+#pragma warning restore CA1812 // Avoid uninstantiated internal classes
+{
+    public ValidateOptionsResult Validate( string? name, ApiVersioningOptions options )
+    {
+        if ( name is not null && name != Options.DefaultName )
+        {
+            return ValidateOptionsResult.Skip;
+        }
+
+        if ( options.DefaultApiVersion == ApiVersion.Neutral )
+        {
+            var message = string.Format(
+                CultureInfo.CurrentCulture,
+                SR.InvalidDefaultApiVersion,
+                nameof( ApiVersion ),
+                nameof( ApiVersion.Neutral ),
+                nameof( ApiVersioningOptions ),
+                nameof( ApiVersioningOptions.DefaultApiVersion ),
+                nameof( IApiVersionNeutral ) );
+            return ValidateOptionsResult.Fail( message );
+        }
+
+        return ValidateOptionsResult.Success;
+    }
+}

src/AspNetCore/WebApi/src/Asp.Versioning.Http/SR.resx

@@ -0,0 +1,26 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Microsoft.Extensions.DependencyInjection;
+
+using Asp.Versioning;
+using Microsoft.Extensions.Options;
+
+public class IServiceCollectionExtensionsTest
+{
+    [Fact]
+    public void add_api_versioning_should_not_allow_default_neutral_api_version()
+    {
+        // arrange
+        var services = new ServiceCollection();
+
+        services.AddApiVersioning( options => options.DefaultApiVersion = ApiVersion.Neutral );
+
+        var provider = services.BuildServiceProvider();
+
+        // act
+        Func<ApiVersioningOptions> options = () => provider.GetRequiredService<IOptions<ApiVersioningOptions>>().Value;
+
+        // assert
+        options.Should().Throw<OptionsValidationException>();
+    }
+}