Update local copy of ExperimentalAttribute per dotnet/runtime#85444

Author: RussKie

Directory.Build.targets

@@ -66,7 +66,9 @@
   </Target>
 
   <ItemGroup Condition="'$(Stage)' == 'dev' AND '$(OutputType)' != 'Exe' AND '$(Api)' != 'false'">
-    <AssemblyAttribute Include="System.Diagnostics.CodeAnalysis.ExperimentalAttribute" />
+    <AssemblyAttribute Include="System.Diagnostics.CodeAnalysis.ExperimentalAttribute">
+      <_Parameter1>TBD</_Parameter1>
+    </AssemblyAttribute>
   </ItemGroup>
 
   <Target Name="AddInternalsVisibleToDynamicProxyGenAssembly2" BeforeTargets="BeforeCompile">

src/LegacySupport/ExperimentalAttribute/ExperimentalAttribute.cs

@@ -1,6 +1,8 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+#if !NET8_0_OR_GREATER
+
 namespace System.Diagnostics.CodeAnalysis;
 
 /// <summary>
@@ -24,30 +26,31 @@ internal sealed class ExperimentalAttribute : Attribute
     /// <summary>
     /// Initializes a new instance of the <see cref="ExperimentalAttribute"/> class.
     /// </summary>
-    public ExperimentalAttribute()
+    /// <param name="diagnosticId">Human readable explanation for marking experimental API.</param>
+    public ExperimentalAttribute(string diagnosticId)
     {
-        // Intentionally left empty.
+        DiagnosticId = diagnosticId;
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="ExperimentalAttribute"/> class.
+    ///  Gets the ID that the compiler will use when reporting a use of the API the attribute applies to.
     /// </summary>
-    /// <param name="message">Human readable explanation for marking experimental API.</param>
-    public ExperimentalAttribute(string message)
-    {
-#pragma warning disable R9A014 // Use the 'Microsoft.Extensions.Diagnostics.Throws' class instead of explicitly throwing exception for improved performance
-#pragma warning disable R9A039 // Remove superfluous null check when compiling in a nullable context
-#pragma warning disable R9A060 // Consider removing unnecessary null coalescing (??) since the left-hand value is statically known not to be null
-#pragma warning disable SA1101 // Prefix local calls with this
-        Message = message ?? throw new ArgumentNullException(nameof(message));
-#pragma warning restore SA1101 // Prefix local calls with this
-#pragma warning restore R9A060 // Consider removing unnecessary null coalescing (??) since the left-hand value is statically known not to be null
-#pragma warning restore R9A039 // Remove superfluous null check when compiling in a nullable context
-#pragma warning restore R9A014 // Use the 'Microsoft.Extensions.Diagnostics.Throws' class instead of explicitly throwing exception for improved performance
-    }
+    /// <value>The unique diagnostic ID.</value>
+    /// <remarks>
+    ///  The diagnostic ID is shown in build output for warnings and errors.
+    ///  <para>This property represents the unique ID that can be used to suppress the warnings or errors, if needed.</para>
+    /// </remarks>
+    public string DiagnosticId { get; }
 
     /// <summary>
-    /// Gets a human readable explanation for marking API as experimental.
+    ///  Gets or sets the URL for corresponding documentation.
+    ///  The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID.
     /// </summary>
-    public string? Message { get; }
+    /// <value>The format string that represents a URL to corresponding documentation.</value>
+    /// <remarks>An example format string is <c>https://contoso.com/obsoletion-warnings/{0}</c>.</remarks>
+#pragma warning disable S3996 // URI properties should not be strings
+    public string? UrlFormat { get; set; }
+#pragma warning restore S3996 // URI properties should not be strings
 }
+
+#endif

src/Libraries/Microsoft.AspNetCore.Telemetry.Middleware/Logging/LoggingOptions.cs

@@ -67,7 +67,7 @@ public class LoggingOptions
     /// <value>
     /// The default value is <see cref="HttpRouteParameterRedactionMode.Strict"/>.
     /// </value>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     public HttpRouteParameterRedactionMode RequestPathParameterRedactionMode { get; set; } = DefaultPathParameterRedactionMode;
 
     /// <summary>
@@ -208,7 +208,7 @@ public class LoggingOptions
     /// };
     /// </code>
     /// </example>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     [Required]
     [SuppressMessage("Usage", "CA2227:Collection properties should be read only",
         Justification = "Options pattern.")]

src/Libraries/Microsoft.AspNetCore.Telemetry/Enrichment.RequestHeaders/RequestHeadersLogEnricherOptions.cs

@@ -20,7 +20,7 @@ public class RequestHeadersLogEnricherOptions
     /// Default value is an empty dictionary.
     /// </remarks>
     [Required]
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
 #pragma warning disable CA2227 // Collection properties should be read only
     public IDictionary<string, DataClassification> HeadersDataClasses { get; set; } = new Dictionary<string, DataClassification>();
 #pragma warning restore CA2227 // Collection properties should be read only

src/Libraries/Microsoft.AspNetCore.Telemetry/Tracing/HttpTracingExtensions.cs

@@ -116,7 +116,7 @@ public static TracerProviderBuilder AddHttpTraceEnricher(this TracerProviderBuil
     /// <param name="services">The <see cref="IServiceCollection"/> to add this enricher.</param>
     /// <returns><see cref="IServiceCollection"/> for chaining.</returns>
     /// <exception cref="ArgumentNullException">The argument <paramref name="services"/> is <see langword="null"/>.</exception>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     public static IServiceCollection AddHttpTraceEnricher<T>(this IServiceCollection services)
         where T : class, IHttpTraceEnricher
     {
@@ -132,7 +132,7 @@ public static IServiceCollection AddHttpTraceEnricher<T>(this IServiceCollection
     /// <param name="enricher">Enricher to be added.</param>
     /// <returns><see cref="TracerProviderBuilder"/> for chaining.</returns>
     /// <exception cref="ArgumentNullException">The argument <paramref name="services"/> or <paramref name="enricher"/> is <see langword="null" />.</exception>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     public static IServiceCollection AddHttpTraceEnricher(this IServiceCollection services, IHttpTraceEnricher enricher)
     {
         _ = Throw.IfNull(services);

src/Libraries/Microsoft.AspNetCore.Telemetry/Tracing/HttpTracingOptions.cs

@@ -51,7 +51,7 @@ public class HttpTracingOptions
     /// <remarks>
     /// This property is applicable when the <see cref="IncludePath"/> option is enabled.
     /// </remarks>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     public HttpRouteParameterRedactionMode RequestPathParameterRedactionMode { get; set; } = DefaultPathParameterRedactionMode;
 
     /// <summary>

src/Libraries/Microsoft.Extensions.AsyncState/IAsyncLocalContext.cs

@@ -11,7 +11,7 @@ namespace Microsoft.Extensions.AsyncState;
 /// </summary>
 /// <typeparam name="T">The type of the asynchronous state.</typeparam>
 /// <remarks>This type is intended for internal use. Use <see cref="IAsyncContext{T}"/> instead.</remarks>
-[Experimental]
+[Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
 [EditorBrowsable(EditorBrowsableState.Never)]
 #pragma warning disable S4023 // Interfaces should not be empty
 public interface IAsyncLocalContext<T> : IAsyncContext<T>

src/Libraries/Microsoft.Extensions.Diagnostics.HealthChecks.Common/CommonHealthChecksExtensions.TelemetryPublisher.cs

@@ -30,7 +30,7 @@ public static IServiceCollection AddTelemetryHealthCheckPublisher(this IServiceC
     /// <param name="section">Configuration for <see cref="TelemetryHealthCheckPublisherOptions"/>.</param>
     /// <returns>The value of <paramref name="services"/>.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="services" /> or <paramref name="section"/> are <see langword="null" />.</exception>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     public static IServiceCollection AddTelemetryHealthCheckPublisher(this IServiceCollection services, IConfigurationSection section)
         => Throw.IfNull(services)
             .Configure<TelemetryHealthCheckPublisherOptions>(Throw.IfNull(section))
@@ -44,7 +44,7 @@ public static IServiceCollection AddTelemetryHealthCheckPublisher(this IServiceC
     /// <param name="configure">Configuration for <see cref="TelemetryHealthCheckPublisherOptions"/>.</param>
     /// <returns>The value of <paramref name="services"/>.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="services" /> or <paramref name="configure"/> are <see langword="null" />.</exception>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     public static IServiceCollection AddTelemetryHealthCheckPublisher(this IServiceCollection services, Action<TelemetryHealthCheckPublisherOptions> configure)
         => Throw.IfNull(services)
             .Configure(Throw.IfNull(configure))

src/Libraries/Microsoft.Extensions.Diagnostics.HealthChecks.Common/TelemetryHealthCheckPublisherOptions.cs

@@ -8,7 +8,7 @@ namespace Microsoft.Extensions.Diagnostics.HealthChecks;
 /// <summary>
 /// Options for the telemetry health check publisher.
 /// </summary>
-[Experimental]
+[Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
 public class TelemetryHealthCheckPublisherOptions
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.Diagnostics.ResourceMonitoring/ResourceMonitoringOptions.cs

@@ -50,7 +50,7 @@ public class ResourceMonitoringOptions
     /// The value needs to be less than or equal to the <see cref="CollectionWindow"/>.
     /// Most importantly, this period is used to calculate <see cref="Utilization"/> instances pushed to publishers.
     /// </remarks>
-    [Experimental]
+    [Experimental(diagnosticId: "TBD", UrlFormat = "TBD")]
     [TimeSpan(MinimumSamplingWindow, MaximumSamplingWindow)]
     public TimeSpan CalculationPeriod { get; set; } = DefaultCollectionWindow;
 }