Deprecate IResourceUtilizationPublisher

Directory.Build.targets

@@ -22,6 +22,9 @@
     <!-- Experimental warnings are for customers, not for this repo -->
     <NoWarn>$(NoWarn);EXTEXP0001;EXTEXP0002;EXTEXP0003;EXTEXP0004;EXTEXP0005;EXTEXP0006;EXTEXP0007;EXTEXP0008;EXTEXP0009;EXTEXP0010;EXTEXP0011;EXTEXP0012;EXTEXP0013;EXTEXP0014;EXTEXP0015;EXTEXP0016;EXTEXP0017</NoWarn>
 
+    <!-- Obsoletion warnings are for customers, not for this repo -->
+    <NoWarn>$(NoWarn);EXTOBS0001;</NoWarn>
+
     <!-- NU5104: A stable release of a package should not have a prerelease dependency -->
     <NoWarn>$(NoWarn);NU5104</NoWarn>
 

docs/list-of-diagnostics.md

@@ -41,6 +41,16 @@ if desired.
 | `EXTEXP0016` | Hosting integration testing experiments |
 | `EXTEXP0017` | Contextual options experiments |
 
+# Obsoletions
+
+At some point in its lifecycle APIs become obsolete. If you use obsolete APIs, you will get one of the diagnostic shown below.
+
+You may continue using obsolete APIs in your application, but we advise exploring proposed alternatives which you will find in the obsoletion message.
+
+| Diagnostic ID     | Description |
+| :---------------- | :---------- |
+| `EXTOBS0001` | IResourceUtilizationPublisher obsoletions. Please use observable instruments from [here](https://github.com/dotnet/extensions/blob/6e0195db97d66cdf082e32799858c34bf5fd0cdb/src/Libraries/Microsoft.Extensions.Diagnostics.ResourceMonitoring/ResourceUtilizationInstruments.cs). |
+
 # LoggerMessage
 
 | Diagnostic ID     | Description |

eng/MSBuild/LegacySupport.props

@@ -50,4 +50,8 @@
   <ItemGroup Condition="'$(InjectExperimentalAttributeOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netcoreapp3.1' or '$(TargetFramework)' == 'net6.0' or '$(TargetFramework)' == 'net7.0')">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\ExperimentalAttribute\*.cs" LinkBase="LegacySupport\ExperimentalAttribute" />
   </ItemGroup>
+
+  <ItemGroup Condition="'$(InjectObsoleteAttributeOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netcoreapp3.1')">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\ObsoleteAttribute\*.cs" LinkBase="LegacySupport\ObsoleteAttribute" />
+  </ItemGroup>
 </Project>

src/LegacySupport/ObsoleteAttribute/ObsoleteAttribute.cs

@@ -0,0 +1,52 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#if !NET5_0_OR_GREATER
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace System;
+
+/// <summary>
+/// Marks program elements that are no longer in use.
+/// </summary>
+/// <remarks>
+/// Source code imported from 
+/// <see href="https://github.com/dotnet/runtime/blob/5535e31a712343a63f5d7d796cd874e563e5ac14/src/libraries/System.Private.CoreLib/src/System/ObsoleteAttribute.cs">
+/// ObsoleteAttribute.cs</see> without any changes, all resulting warnings ignored accordingly.
+/// </remarks>
+#pragma warning disable CA1019 // Define accessors for attribute arguments
+#pragma warning disable S3996 // URI properties should not be strings
+[ExcludeFromCodeCoverage]
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum |
+    AttributeTargets.Interface | AttributeTargets.Constructor | AttributeTargets.Method |
+    AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Event |
+    AttributeTargets.Delegate,
+    Inherited = false)]
+internal sealed class ObsoleteAttribute : Attribute
+{
+    public ObsoleteAttribute()
+    {
+    }
+
+    public ObsoleteAttribute(string? message)
+    {
+        Message = message;
+    }
+
+    public ObsoleteAttribute(string? message, bool error)
+    {
+        Message = message;
+        IsError = error;
+    }
+
+    public string? Message { get; }
+
+    public bool IsError { get; }
+
+    public string? DiagnosticId { get; set; }
+
+    public string? UrlFormat { get; set; }
+}
+
+#endif

src/LegacySupport/ObsoleteAttribute/README.md

@@ -0,0 +1,7 @@
+To use this source in your project, add the following to your `.csproj` file:
+
+```xml
+<PropertyGroup>
+  <InjectObsoleteAttributeOnLegacy>true</InjectObsoleteAttributeOnLegacy>
+</PropertyGroup>
+```

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

@@ -1,8 +1,10 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System;
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring;
 
@@ -21,6 +23,12 @@ public interface IResourceMonitorBuilder
     /// </summary>
     /// <typeparam name="T">The publisher's implementation type.</typeparam>
     /// <returns>The value of the object instance.</returns>
+#if !NET5_0_OR_GREATER
+#pragma warning disable CS0436 // Type conflicts with imported type
+#endif
+    [Obsolete("This method is obsolete and will be removed in a future version. Consider using observable instruments.",
+        DiagnosticId = DiagnosticIds.Obsoletions.ResourceMonitoring,
+        UrlFormat = DiagnosticIds.UrlFormat)]
     IResourceMonitorBuilder AddPublisher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>()
         where T : class, IResourceUtilizationPublisher;
 }

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

@@ -1,14 +1,22 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring;
 
 /// <summary>
 /// Defines the contract for a resource utilization publisher that gets invoked whenever resource utilization is computed.
 /// </summary>
+#if !NET5_0_OR_GREATER
+#pragma warning disable CS0436 // Type conflicts with imported type
+#endif
+[Obsolete("This API is obsolete and will be removed in a future version. Consider using observable instruments.",
+    DiagnosticId = DiagnosticIds.Obsoletions.ResourceMonitoring,
+    UrlFormat = DiagnosticIds.UrlFormat)]
 public interface IResourceUtilizationPublisher
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.Diagnostics.ResourceMonitoring/Microsoft.Extensions.Diagnostics.ResourceMonitoring.csproj

@@ -12,6 +12,7 @@
     <InjectSharedDataValidation>true</InjectSharedDataValidation>
     <InjectSharedRentedSpan>true</InjectSharedRentedSpan>
     <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
+    <InjectObsoleteAttributeOnLegacy>true</InjectObsoleteAttributeOnLegacy>
     <InjectSharedBufferWriterPool>true</InjectSharedBufferWriterPool>
     <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
   </PropertyGroup>

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

@@ -1,10 +1,12 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System;
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Hosting;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring;
 
@@ -21,6 +23,12 @@ public ResourceMonitorBuilder(IServiceCollection services)
         Services = services;
     }
 
+#if !NET5_0_OR_GREATER
+#pragma warning disable CS0436 // Type conflicts with imported type
+#endif
+    [Obsolete("This API is obsolete and will be removed in a future version. Consider using observable instruments.",
+        DiagnosticId = DiagnosticIds.Obsoletions.ResourceMonitoring,
+        UrlFormat = DiagnosticIds.UrlFormat)]
     public IResourceMonitorBuilder AddPublisher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>()
         where T : class, IResourceUtilizationPublisher
     {

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

@@ -8,9 +8,6 @@ namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring;
 /// <summary>
 /// Represents the names of instruments published by this package.
 /// </summary>
-/// <remarks>
-/// These metrics are currently only published on Linux.
-/// </remarks>
 /// <seealso cref="System.Diagnostics.Metrics.Instrument"/>
 internal static class ResourceUtilizationInstruments
 {

src/Libraries/Microsoft.Extensions.Diagnostics.ResourceMonitoring/Windows/Log.cs

@@ -6,7 +6,6 @@
 namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring.Windows;
 
 #pragma warning disable S109
-#pragma warning disable IDE0060 // Remove unused parameters - Reason: used by source generator.
 
 internal static partial class Log
 {

src/Shared/DiagnosticIds/DiagnosticIds.cs

@@ -117,6 +117,11 @@ internal static class AuditReports
         internal const string AUDREPGEN000 = nameof(AUDREPGEN000);
         internal const string AUDREPGEN001 = nameof(AUDREPGEN001);
     }
+
+    internal static class Obsoletions
+    {
+        internal const string ResourceMonitoring = "EXTOBS0001";
+    }
 }
 
 #pragma warning restore S1144

test/Libraries/Microsoft.Extensions.Diagnostics.ResourceMonitoring.Tests/Publishers/EmptyPublisher.cs

@@ -7,7 +7,7 @@
 namespace Microsoft.Extensions.Diagnostics.ResourceMonitoring.Test.Publishers;
 
 /// <summary>
-/// A publisher that do nothing.
+/// A publisher that does nothing.
 /// </summary>
 internal sealed class EmptyPublisher : IResourceUtilizationPublisher
 {

test/Libraries/Microsoft.Extensions.Diagnostics.ResourceMonitoring.Tests/ResourceMonitoringServiceTests.cs

@@ -32,7 +32,7 @@ public sealed class ResourceMonitoringServiceTests
     /// <summary>
     /// Simply construct the object.
     /// </summary>
-    /// <remarks>Tests that look into internals like this are evil.  Consider removing long term.</remarks>
+    /// <remarks>Tests that look into internals like this are evil. Consider removing long term.</remarks>
     [Fact]
     public void BasicConstructor()
     {
@@ -75,7 +75,7 @@ public void BasicConstructor_NullOptions_Throws()
     /// <summary>
     /// Simply construct the object (publisher constructor).
     /// </summary>
-    /// <remarks>Tests that look into internals like this are evil.  Consider removing long term.</remarks>
+    /// <remarks>Tests that look into internals like this are evil. Consider removing long term.</remarks>
     [Fact]
     public void BasicConstructor_NullPublishers_Throws()
     {
@@ -293,7 +293,7 @@ public async Task RunTrackerAsync_IfPublisherThrows_LogsError()
     /// <summary>
     /// Validate that the tracker invokes the publisher's Publish method.
     /// </summary>
-    /// <remarks>Tests that look into internals like this are evil.  Consider removing long term.</remarks>
+    /// <remarks>Tests that look into internals like this are evil. Consider removing long term.</remarks>
     [Fact]
     public async Task ResourceUtilizationTracker_InitializedProperly_InvokesPublishers()
     {

test/Libraries/Microsoft.Extensions.Http.Resilience.Tests/Resilience/RequestMessageSnapshotTests.cs

@@ -11,7 +11,6 @@
 
 namespace Microsoft.Extensions.Http.Resilience.Test.Resilience;
 
-#pragma warning disable CS0618 // Type or member is obsolete
 #pragma warning disable CS0618 // Type or member is obsolete
 
 public class RequestMessageSnapshotTests