Define new interfaces for policies

ISunsetPolicyBuilder and IDeprecationPolicyBuilder contained duplicated functionality. This was extracted into the new interfaces IPolicyWithLink and IPolicyWithEffectiveDate and corresponding extension methods.
To avoid naming collisions, the `Effective` method was renamed to `SetEffectiveDate`.

Author: Matthias Gessinger

src/Abstractions/src/Asp.Versioning.Abstractions/IDeprecationPolicyBuilder.cs

@@ -5,20 +5,4 @@ namespace Asp.Versioning;
 /// <summary>
 /// Defines the behavior of a deprecation policy builder.
 /// </summary>
-public interface IDeprecationPolicyBuilder : IPolicyBuilder<DeprecationPolicy>
-{
-    /// <summary>
-    /// Creates and returns a new link builder.
-    /// </summary>
-    /// <param name="linkTarget">The link target URL.</param>
-    /// <returns>A new <see cref="ILinkBuilder">link builder</see>.</returns>
-    ILinkBuilder Link( Uri linkTarget );
-
-    /// <summary>
-    /// Indicates when a deprecation policy is applied.
-    /// </summary>
-    /// <param name="deprecationDate">The <see cref="DateTimeOffset">date and time</see> when a
-    /// deprecation policy is applied.</param>
-    /// <returns>The current <see cref="IDeprecationPolicyBuilder">deprecation policy builder</see>.</returns>
-    IDeprecationPolicyBuilder Effective( DateTimeOffset deprecationDate );
-}
+public interface IDeprecationPolicyBuilder : IPolicyBuilder<DeprecationPolicy>, IPolicyWithLink, IPolicyWithEffectiveDate { }

src/Abstractions/src/Asp.Versioning.Abstractions/IDeprecationPolicyBuilderExtensions.cs

@@ -0,0 +1,52 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning;
+
+/// <summary>
+/// Provides extension methods for the <see cref="IPolicyBuilder{T}"/> interface.
+/// </summary>
+public static class IPolicyBuilderExtensions
+{
+    /// <summary>
+    /// Creates and returns a new link builder.
+    /// </summary>
+    /// <param name="builder">The extended <see cref="IPolicyBuilder{T}">policy builder</see>.</param>
+    /// <param name="linkTarget">The link target URL.</param>
+    /// <returns>A new <see cref="ILinkBuilder">link builder</see>.</returns>
+    public static ILinkBuilder Link( this IPolicyWithLink builder, string linkTarget )
+    {
+        ArgumentNullException.ThrowIfNull( builder );
+        return builder.Link( new Uri( linkTarget, UriKind.RelativeOrAbsolute ) );
+    }
+
+    /// <summary>
+    /// Indicates when a policy is applied.
+    /// </summary>
+    /// <typeparam name="TBuilder">The type of <see cref="IPolicyBuilder{T}">policy builder</see>.</typeparam>
+    /// <param name="builder">The extended <see cref="IPolicyBuilder{T}">policy builder</see>.</param>
+    /// <param name="effectiveDate">The time when the policy is applied.</param>
+    /// <returns>The current <see cref="IPolicyBuilder{T}">policy builder</see>.</returns>
+    public static TBuilder Effective<TBuilder>( this TBuilder builder, DateTimeOffset effectiveDate )
+        where TBuilder : notnull, IPolicyWithEffectiveDate
+    {
+        ArgumentNullException.ThrowIfNull( builder );
+        builder.SetEffectiveDate( effectiveDate );
+        return builder;
+    }
+
+    /// <summary>
+    /// Indicates when a policy is applied.
+    /// </summary>
+    /// <typeparam name="TBuilder">The type of <see cref="IPolicyBuilder{T}">policy builder</see>.</typeparam>
+    /// <param name="builder">The extended <see cref="IPolicyBuilder{T}">policy builder</see>.</param>
+    /// <param name="year">The year when the policy is applied.</param>
+    /// <param name="month">The month when the policy is applied.</param>
+    /// <param name="day">The day when the policy is applied.</param>
+    /// <returns>The current <see cref="IPolicyBuilder{T}">policy builder</see>.</returns>
+    public static TBuilder Effective<TBuilder>( this TBuilder builder, int year, int month, int day )
+        where TBuilder : notnull, IPolicyWithEffectiveDate
+    {
+        ArgumentNullException.ThrowIfNull( builder );
+        return builder.Effective( new DateTimeOffset( new DateTime( year, month, day ) ) );
+    }
+}

src/Abstractions/src/Asp.Versioning.Abstractions/IPolicyBuilderExtensions.cs

@@ -0,0 +1,17 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning;
+
+/// <summary>
+/// A policy which can be configured to only be effective after a particular date.
+/// </summary>
+public interface IPolicyWithEffectiveDate
+{
+    /// <summary>
+    /// Indicates when a policy is applied.
+    /// </summary>
+    /// <param name="effectiveDate">
+    /// The <see cref="DateTimeOffset">date and time</see> when a policy is applied.
+    /// </param>
+    void SetEffectiveDate( DateTimeOffset effectiveDate );
+}

src/Abstractions/src/Asp.Versioning.Abstractions/IPolicyWithEffectiveDate.cs

@@ -0,0 +1,16 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning;
+
+/// <summary>
+/// Defines a policy which can (optionally) expose a link to more information.
+/// </summary>
+public interface IPolicyWithLink
+{
+    /// <summary>
+    /// Creates and returns a new link builder.
+    /// </summary>
+    /// <param name="linkTarget">The link target URL.</param>
+    /// <returns>A new <see cref="ILinkBuilder">link builder</see>.</returns>
+    ILinkBuilder Link( Uri linkTarget );
+}

src/Abstractions/src/Asp.Versioning.Abstractions/IPolicyWithLink.cs

@@ -5,20 +5,4 @@ namespace Asp.Versioning;
 /// <summary>
 /// Defines the behavior of a sunset policy builder.
 /// </summary>
-public interface ISunsetPolicyBuilder : IPolicyBuilder<SunsetPolicy>
-{
-    /// <summary>
-    /// Creates and returns a new link builder.
-    /// </summary>
-    /// <param name="linkTarget">The link target URL.</param>
-    /// <returns>A new <see cref="ILinkBuilder">link builder</see>.</returns>
-    ILinkBuilder Link( Uri linkTarget );
-
-    /// <summary>
-    /// Indicates when a sunset policy is applied.
-    /// </summary>
-    /// <param name="sunsetDate">The <see cref="DateTimeOffset">date and time</see> when a
-    /// sunset policy is applied.</param>
-    /// <returns>The current <see cref="ISunsetPolicyBuilder">sunset policy builder</see>.</returns>
-    ISunsetPolicyBuilder Effective( DateTimeOffset sunsetDate );
-}
+public interface ISunsetPolicyBuilder : IPolicyBuilder<SunsetPolicy>, IPolicyWithLink, IPolicyWithEffectiveDate { }

src/Abstractions/src/Asp.Versioning.Abstractions/ISunsetPolicyBuilder.cs

@@ -2,7 +2,7 @@
 
 namespace Asp.Versioning;
 
-public class ISunsetPolicyManagerExtensionsTest
+public class IPolicyManagerExtensionsTest
 {
     [Fact]
     public void try_get_policy_should_get_global_policy_by_version()

src/Abstractions/src/Asp.Versioning.Abstractions/ISunsetPolicyBuilderExtensions.cs

@@ -673,4 +673,4 @@ public int GetHashCode( [DisallowNull] ApiDescription obj )
             return hash.ToHashCode();
         }
     }
-}
+}

…ts/ISunsetPolicyManagerExtensionsTest.cs …ns.Tests/IPolicyManagerExtensionsTest.cssrc/Abstractions/test/Asp.Versioning.Abstractions.Tests/ISunsetPolicyManagerExtensionsTest.cs renamed to src/Abstractions/test/Asp.Versioning.Abstractions.Tests/IPolicyManagerExtensionsTest.cs src/Abstractions/test/Asp.Versioning.Abstractions.Tests/ISunsetPolicyManagerExtensionsTest.cs renamed to src/Abstractions/test/Asp.Versioning.Abstractions.Tests/IPolicyManagerExtensionsTest.cs

@@ -20,10 +20,9 @@ public DeprecationPolicyBuilder( string? name, ApiVersion? apiVersion )
         : base( name, apiVersion ) { }
 
     /// <inheritdoc />
-    public virtual IDeprecationPolicyBuilder Effective( DateTimeOffset deprecationDate )
+    public virtual void SetEffectiveDate( DateTimeOffset effectiveDate )
     {
-        date = deprecationDate;
-        return this;
+        date = effectiveDate;
     }
 
     /// <inheritdoc />