Skip to content

Commit

Permalink
Update local copy of ExperimentalAttribute per dotnet/runtime#85444
Browse files Browse the repository at this point in the history
  • Loading branch information
RussKie committed Jun 21, 2023
1 parent fe0feb2 commit 8427979
Show file tree
Hide file tree
Showing 76 changed files with 146 additions and 132 deletions.
4 changes: 3 additions & 1 deletion Directory.Build.targets
Original file line number Diff line number Diff line change
Expand Up @@ -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></_Parameter1>
</AssemblyAttribute>
</ItemGroup>

<Target Name="AddInternalsVisibleToDynamicProxyGenAssembly2" BeforeTargets="BeforeCompile">
Expand Down
9 changes: 9 additions & 0 deletions docs/list-of-diagnostics.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# List of Diagnostics Produced by .NET Extensions Libraries APIs

## Analyzer Warnings

### NETEXT (`NETEXT0001`)

| Diagnostic ID | Description |
| :---------------- | :---------- |
| __`NETEXT0001`__ | Experimental API |
39 changes: 21 additions & 18 deletions src/LegacySupport/ExperimentalAttribute/ExperimentalAttribute.cs
Original file line number Diff line number Diff line change
@@ -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>
Expand All @@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ public class LoggingOptions
/// <value>
/// The default value is <see cref="HttpRouteParameterRedactionMode.Strict"/>.
/// </value>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public HttpRouteParameterRedactionMode RequestPathParameterRedactionMode { get; set; } = DefaultPathParameterRedactionMode;

/// <summary>
Expand Down Expand Up @@ -208,7 +208,7 @@ public class LoggingOptions
/// };
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[Required]
[SuppressMessage("Usage", "CA2227:Collection properties should be read only",
Justification = "Options pattern.")]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ public class RequestHeadersLogEnricherOptions
/// Default value is an empty dictionary.
/// </remarks>
[Required]
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
#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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static IServiceCollection AddHttpTraceEnricher<T>(this IServiceCollection services)
where T : class, IHttpTraceEnricher
{
Expand All @@ -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: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static IServiceCollection AddHttpTraceEnricher(this IServiceCollection services, IHttpTraceEnricher enricher)
{
_ = Throw.IfNull(services);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ public class HttpTracingOptions
/// <remarks>
/// This property is applicable when the <see cref="IncludePath"/> option is enabled.
/// </remarks>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public HttpRouteParameterRedactionMode RequestPathParameterRedactionMode { get; set; } = DefaultPathParameterRedactionMode;

/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[EditorBrowsable(EditorBrowsableState.Never)]
#pragma warning disable S4023 // Interfaces should not be empty
public interface IAsyncLocalContext<T> : IAsyncContext<T>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static IServiceCollection AddTelemetryHealthCheckPublisher(this IServiceCollection services, IConfigurationSection section)
=> Throw.IfNull(services)
.Configure<TelemetryHealthCheckPublisherOptions>(Throw.IfNull(section))
Expand All @@ -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: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static IServiceCollection AddTelemetryHealthCheckPublisher(this IServiceCollection services, Action<TelemetryHealthCheckPublisherOptions> configure)
=> Throw.IfNull(services)
.Configure(Throw.IfNull(configure))
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ namespace Microsoft.Extensions.Diagnostics.HealthChecks;
/// <summary>
/// Options for the telemetry health check publisher.
/// </summary>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public class TelemetryHealthCheckPublisherOptions
{
/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[TimeSpan(MinimumSamplingWindow, MaximumSamplingWindow)]
public TimeSpan CalculationPeriod { get; set; } = DefaultCollectionWindow;
}
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring;
/// <summary>
/// Options for WindowsCounters.
/// </summary>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public class WindowsCountersOptions
{
internal const int MinimumCachingInterval = 100;
Expand All @@ -33,7 +33,7 @@ public class WindowsCountersOptions
/// <value>
/// The default value is 5 seconds.
/// </value>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[TimeSpan(MinimumCachingInterval, MaximumCachingInterval)]
public TimeSpan CachingInterval { get; set; } = DefaultCachingInterval;
}
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ public static IResourceMonitorBuilder AddWindowsPerfCounterPublisher(this IResou
/// <returns>The value of <paramref name="builder" />.</returns>
/// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null" />.</exception>
/// <seealso cref="System.Diagnostics.Metrics.Instrument"/>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static IResourceMonitorBuilder AddWindowsCounters(this IResourceMonitorBuilder builder)
{
_ = Throw.IfNull(builder);
Expand Down Expand Up @@ -93,7 +93,7 @@ public static IResourceMonitorBuilder AddWindowsCounters(this IResourceMonitorBu
/// <returns>The value of <paramref name="builder"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null" />.</exception>
/// <seealso cref="System.Diagnostics.Metrics.Instrument"/>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static IResourceMonitorBuilder AddWindowsCounters(this IResourceMonitorBuilder builder, IConfigurationSection section)
{
_ = Throw.IfNull(builder);
Expand Down Expand Up @@ -123,7 +123,7 @@ public static IResourceMonitorBuilder AddWindowsCounters(this IResourceMonitorBu
/// <returns>The value of <paramref name="builder"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="builder"/> is <see langword="null" />.</exception>
/// <seealso cref="System.Diagnostics.Metrics.Instrument"/>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static IResourceMonitorBuilder AddWindowsCounters(this IResourceMonitorBuilder builder, Action<WindowsCountersOptions> configure)
{
_ = Throw.IfNull(builder);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ namespace Microsoft.Extensions.Hosting.Testing;
/// <summary>
/// Extension methods supporting host unit testing scenarios.
/// </summary>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public static class HostingFakesExtensions
{
/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Interface)]
[Conditional("CODE_GENERATION_ATTRIBUTES")]
public sealed class AutoClientAttribute : Attribute
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// </code>
/// </example>
[SuppressMessage("Design", "CA1032:Implement standard exception constructors", Justification = "Not applicable to this exception")]
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public class AutoClientException : Exception
{
/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// When a REST API client fails, it will throw a <see cref="AutoClientException"/>.
/// This exception contains a <see cref="AutoClientHttpError"/> instance that holds details like content, headers and status code.
/// </remarks>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public class AutoClientHttpError
{
/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// });
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public class AutoClientOptions
{
/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Parameter)]
[Conditional("CODE_GENERATION_ATTRIBUTES")]
public sealed class BodyAttribute : Attribute
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// <summary>
/// Defines the types of encoding possible for request bodies.
/// </summary>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
public enum BodyContentType
{
/// <summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Parameter)]
[Conditional("CODE_GENERATION_ATTRIBUTES")]
public sealed class HeaderAttribute : Attribute
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
public sealed class DeleteAttribute : Attribute
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
public sealed class GetAttribute : Attribute
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
public sealed class HeadAttribute : Attribute
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
public sealed class OptionsAttribute : Attribute
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
public sealed class PatchAttribute : Attribute
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
public sealed class PostAttribute : Attribute
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
public sealed class PutAttribute : Attribute
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Parameter)]
[Conditional("CODE_GENERATION_ATTRIBUTES")]
public sealed class QueryAttribute : Attribute
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Method)]
[Conditional("CODE_GENERATION_ATTRIBUTES")]
public sealed class RequestNameAttribute : Attribute
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ namespace Microsoft.Extensions.Http.AutoClient;
/// }
/// </code>
/// </example>
[Experimental]
[Experimental(diagnosticId: "NETEXT0001", UrlFormat = "https://aka.ms/dotnet-extensions-warnings/{0}")]
[AttributeUsage(AttributeTargets.Interface | AttributeTargets.Method, AllowMultiple = true)]
[Conditional("CODE_GENERATION_ATTRIBUTES")]
public sealed class StaticHeaderAttribute : Attribute
Expand Down
Loading

0 comments on commit 8427979

Please sign in to comment.