Add deprecation policy to ApIVersionPolicyBuilder

Author: Matthias Gessinger

src/Abstractions/src/Asp.Versioning.Abstractions/IApiVersioningPolicyBuilder.cs

@@ -23,4 +23,14 @@ public interface IApiVersioningPolicyBuilder
     /// <exception cref="ArgumentException">The <paramref name="name"/> and <paramref name="apiVersion"/>
     /// parameters are both <c>null</c>.</exception>
     ISunsetPolicyBuilder Sunset( string? name, ApiVersion? apiVersion );
+
+    /// <summary>
+    /// Creates and returns a new deprecation policy builder.
+    /// </summary>
+    /// <param name="name">The optional name of the API the policy is for.</param>
+    /// <param name="apiVersion">The optional <see cref="ApiVersion">API version</see> the policy is for.</param>
+    /// <returns>A new <see cref="IDeprecationPolicyBuilder">deprecation policy builder</see>.</returns>
+    /// <exception cref="ArgumentException">The <paramref name="name"/> and <paramref name="apiVersion"/>
+    /// parameters are both <c>null</c>.</exception>
+    public IDeprecationPolicyBuilder Deprecate( string? name, ApiVersion? apiVersion );
 }

src/Common/src/Common/ApiVersioningPolicyBuilder.cs

@@ -10,13 +10,18 @@ namespace Asp.Versioning;
 public class ApiVersioningPolicyBuilder : IApiVersioningPolicyBuilder
 {
     private Dictionary<PolicyKey, ISunsetPolicyBuilder>? sunsetPolicies;
+    private Dictionary<PolicyKey, IDeprecationPolicyBuilder>? deprecationPolicies;
 
     /// <inheritdoc />
     public virtual IReadOnlyList<T> OfType<T>() where T : notnull
     {
         if ( typeof( T ) == typeof( ISunsetPolicyBuilder ) && sunsetPolicies != null )
         {
-            return ( sunsetPolicies.Values.ToArray() as IReadOnlyList<T> )!;
+            return sunsetPolicies.Values.Cast<T>().ToArray();
+        }
+        else if ( typeof( T ) == typeof( IDeprecationPolicyBuilder ) && deprecationPolicies != null )
+        {
+            return deprecationPolicies.Values.Cast<T>().ToArray();
         }
 
         return Array.Empty<T>();
@@ -42,4 +47,25 @@ public virtual ISunsetPolicyBuilder Sunset( string? name, ApiVersion? apiVersion
 
         return builder;
     }
+
+    /// <inheritdoc />
+    public virtual IDeprecationPolicyBuilder Deprecate( string? name, ApiVersion? apiVersion )
+    {
+        if ( string.IsNullOrEmpty( name ) && apiVersion == null )
+        {
+            var message = string.Format( CultureInfo.CurrentCulture, Format.InvalidPolicyKey, nameof( name ), nameof( apiVersion ) );
+            throw new System.ArgumentException( message );
+        }
+
+        var key = new PolicyKey( name, apiVersion );
+
+        deprecationPolicies ??= [];
+
+        if ( !deprecationPolicies.TryGetValue( key, out var builder ) )
+        {
+            deprecationPolicies.Add( key, builder = new DeprecationPolicyBuilder( name, apiVersion ) );
+        }
+
+        return builder;
+    }
 }

src/Common/test/Common.Tests/ApiVersioningPolicyBuilderTest.cs

@@ -36,6 +36,38 @@ public void sunset_should_return_same_policy_builder( string name, double? versi
         result.Should().BeSameAs( expected );
     }
 
+    [Fact]
+    public void deprecate_should_not_allow_empty_name_and_version()
+    {
+        // arrange
+        var builder = new ApiVersioningPolicyBuilder();
+
+        // act
+        Func<IDeprecationPolicyBuilder> deprecation = () => builder.Deprecate( default, default );
+
+        // assert
+        deprecation.Should().Throw<ArgumentException>().And
+              .Message.Should().Be( "'name' and 'apiVersion' cannot both be null." );
+    }
+
+    [Theory]
+    [InlineData( "Test", null )]
+    [InlineData( null, 1.1 )]
+    [InlineData( "Test", 1.1 )]
+    public void deprecate_should_return_same_policy_builder( string name, double? version )
+    {
+        // arrange
+        var apiVersion = version is null ? default : new ApiVersion( version.Value );
+        var builder = new ApiVersioningPolicyBuilder();
+        var expected = builder.Deprecate( name, apiVersion );
+
+        // act
+        var result = builder.Deprecate( name, apiVersion );
+
+        // assert
+        result.Should().BeSameAs( expected );
+    }
+
     [Fact]
     public void of_type_should_return_empty_list_for_unknown_type()
     {
@@ -50,16 +82,34 @@ public void of_type_should_return_empty_list_for_unknown_type()
     }
 
     [Fact]
-    public void of_type_should_return_filtered_builders()
+    public void of_type_sunset_should_return_filtered_builders()
     {
         // arrange
         var builder = new ApiVersioningPolicyBuilder();
         var expected = builder.Sunset( default, ApiVersion.Default );
+        var deprecation = builder.Deprecate( default, ApiVersion.Default );
 
         // act
         var list = builder.OfType<ISunsetPolicyBuilder>();
 
         // assert
         list.Single().Should().BeSameAs( expected );
+        list.Single().Should().NotBeSameAs( deprecation );
+    }
+
+    [Fact]
+    public void of_type_deprecation_should_return_filtered_builders()
+    {
+        // arrange
+        var builder = new ApiVersioningPolicyBuilder();
+        var sunset = builder.Sunset( default, ApiVersion.Default );
+        var expected = builder.Deprecate( default, ApiVersion.Default );
+
+        // act
+        var list = builder.OfType<IDeprecationPolicyBuilder>();
+
+        // assert
+        list.Single().Should().BeSameAs( expected );
+        list.Single().Should().NotBeSameAs( sunset );
     }
 }