Mark the System.Formats.Nrbf assembly as [Experimental] with SYSLIB50…

…05 (#107950) Co-authored-by: Jeff Handley <jeffhandley@users.noreply.github.com>
dotnet · Sep 18, 2024 · 7e1c7c4 · 7e1c7c4
1 parent 7688892
commit 7e1c7c4
Show file tree

Hide file tree

Showing 11 changed files with 43 additions and 8 deletions.
diff --git a/docs/project/list-of-diagnostics.md b/docs/project/list-of-diagnostics.md
@@ -310,3 +310,4 @@ Diagnostic id values for experimental APIs must not be recycled, as that could s
 |  __`SYSLIB5002`__ |     .NET 9 |     TBD | `SystemColors` alternate colors are experimental in .NET 9 |
 |  __`SYSLIB5003`__ |     .NET 9 |     TBD | `System.Runtime.Intrinsics.Arm.Sve` is experimental in .NET 9 |
 |  __`SYSLIB5004`__ |     .NET 9 |     TBD | `X86Base.DivRem` is experimental in .NET 9 since performance is not as optimized as `T.DivRem` |
+|  __`SYSLIB5005`__ |     .NET 9 |     TBD | `System.Formats.Nrbf` is experimental in .NET 9 |
diff --git a/src/libraries/Common/src/System/Experimentals.cs b/src/libraries/Common/src/System/Experimentals.cs
@@ -28,6 +28,9 @@ internal static class Experimentals
         // X86Base.DivRem is experimental in .NET 9 since performance is not as optimized as T.DivRem
         internal const string X86BaseDivRemDiagId = "SYSLIB5004";
 
+        // System.Formats.Nrbf is experimental in .NET 9
+        internal const string NrbfDecoderDiagId = "SYSLIB5005";
+
         // When adding a new diagnostic ID, add it to the table in docs\project\list-of-diagnostics.md as well.
         // Keep new const identifiers above this comment.
     }

diff --git a/src/libraries/System.Formats.Nrbf/ref/System.Formats.Nrbf.Experimental.cs b/src/libraries/System.Formats.Nrbf/ref/System.Formats.Nrbf.Experimental.cs
@@ -0,0 +1,4 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+[assembly: System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5005", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
diff --git a/src/libraries/System.Formats.Nrbf/ref/System.Formats.Nrbf.csproj b/src/libraries/System.Formats.Nrbf/ref/System.Formats.Nrbf.csproj
@@ -12,6 +12,11 @@
     <ProjectReference Include="$(LibrariesProjectRoot)System.Reflection.Metadata\ref\System.Reflection.Metadata.csproj" />
   </ItemGroup>
 
+  <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
+    <Compile Include="$(CoreLibSharedDir)System\Diagnostics\CodeAnalysis\ExperimentalAttribute.cs"
+         Link="Common\ExperimentalAttribute.cs" />
+  </ItemGroup>
+
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">
     <Compile Include="$(CoreLibSharedDir)System\Diagnostics\CodeAnalysis\RequiresDynamicCodeAttribute.cs" />
     <PackageReference Include="System.Memory" Version="$(SystemMemoryVersion)" />

diff --git a/src/libraries/System.Formats.Nrbf/src/AssemblyInfo.cs b/src/libraries/System.Formats.Nrbf/src/AssemblyInfo.cs
@@ -0,0 +1,7 @@
+// 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;
+
+[assembly: Experimental(Experimentals.NrbfDecoderDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
diff --git a/src/libraries/System.Formats.Nrbf/src/PACKAGE.md b/src/libraries/System.Formats.Nrbf/src/PACKAGE.md
@@ -6,6 +6,8 @@
 
 You can think of [NrbfDecoder](https://learn.microsoft.com/en-us/dotnet/api/system.formats.nrbf.nrbfdecoder) as being the equivalent of using a JSON/XML reader without the deserializer.
 
+**Note:** The 9.0.0 release of the `System.Formats.Nrbf` package is marked `[Experimental]` as the API shape is subject to change in the next major release. Even with the experimental annotation, the package is officially supported. Using the APIs from this package will produce a build warning with diagnostic ID `SYSLIB5005`. The diagnostic can be suppressed with the acknowledgement that the API shape is subject to change in the next major release.
+
 ## How to Use
 
 The NRBF payload consists of serialization records that represent the serialized objects and their metadata. To read the whole payload and get the root record, you need to call one of the [NrbfDecoder.Decode](https://learn.microsoft.com/dotnet/api/system.formats.nrbf.nrbfdecoder.decode) methods.

diff --git a/src/libraries/System.Formats.Nrbf/src/System.Formats.Nrbf.csproj b/src/libraries/System.Formats.Nrbf/src/System.Formats.Nrbf.csproj
@@ -5,18 +5,21 @@
     <EnableDefaultItems>true</EnableDefaultItems>
     <CLSCompliant>false</CLSCompliant>
     <IsPackable>true</IsPackable>
-    <PackageDescription>Provides a safe reader for .NET Remoting Binary Format (NRBF) payloads.
-
-Commonly Used Types:
-System.Formats.Nrbf.NrbfDecoder</PackageDescription>
 
     <!-- Disabling baseline validation since this is a brand new package.
          Once this package has shipped a stable version, the following line
          should be removed in order to re-enable validation. -->
     <DisablePackageBaselineValidation>true</DisablePackageBaselineValidation>
-    <!-- TODO: Add package README file: https://github.com/dotnet/runtime/issues/99358 -->
-    <EnableDefaultPackageReadmeFile>false</EnableDefaultPackageReadmeFile>
+    <EnableDefaultPackageReadmeFile>true</EnableDefaultPackageReadmeFile>
   </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="$(CommonPath)System\Experimentals.cs"
+         Link="Common\Experimentals.cs" />
+  </ItemGroup>
+  <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
+    <Compile Include="$(CoreLibSharedDir)System\Diagnostics\CodeAnalysis\ExperimentalAttribute.cs"
+         Link="Common\ExperimentalAttribute.cs" />
+  </ItemGroup>
   <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">
     <ProjectReference Include="$(LibrariesProjectRoot)\System.Reflection.Metadata\src\System.Reflection.Metadata.csproj" />
   </ItemGroup>

diff --git a/src/libraries/System.Formats.Nrbf/tests/System.Formats.Nrbf.Tests.csproj b/src/libraries/System.Formats.Nrbf/tests/System.Formats.Nrbf.Tests.csproj
@@ -3,6 +3,8 @@
   <PropertyGroup>
     <TargetFrameworks>$(NetCoreAppCurrent);$(NetFrameworkMinimum)</TargetFrameworks>
     <EnableDefaultItems>true</EnableDefaultItems>
+    <!-- SYSLIB5005: System.Formats.Nrbf is experimental -->
+    <NoWarn>$(NoWarn);SYSLIB5005</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/...aries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs b/...aries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs
@@ -22,7 +22,12 @@ namespace System.Diagnostics.CodeAnalysis
                     AttributeTargets.Event |
                     AttributeTargets.Interface |
                     AttributeTargets.Delegate, Inherited = false)]
-    public sealed class ExperimentalAttribute : Attribute
+#if SYSTEM_PRIVATE_CORELIB
+    public
+#else
+    internal
+#endif
+        sealed class ExperimentalAttribute : Attribute
     {
         /// <summary>
         ///  Initializes a new instance of the <see cref="ExperimentalAttribute"/> class, specifying the ID that the compiler will use

diff --git a/src/libraries/System.Resources.Extensions/src/System.Resources.Extensions.csproj b/src/libraries/System.Resources.Extensions/src/System.Resources.Extensions.csproj
@@ -17,6 +17,8 @@ System.Resources.Extensions.DeserializingResourceReader
 System.Resources.Extensions.PreserializedResourceWriter</PackageDescription>
     <!-- TODO: Add package README file: https://github.com/dotnet/runtime/issues/99358 -->
     <EnableDefaultPackageReadmeFile>false</EnableDefaultPackageReadmeFile>
+    <!-- SYSLIB5005: System.Formats.Nrbf is experimental -->
+    <NoWarn>$(NoWarn);SYSLIB5005</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/....Extensions/tests/BinaryFormatTests/System.Resources.Extensions.BinaryFormat.Tests.csproj b/....Extensions/tests/BinaryFormatTests/System.Resources.Extensions.BinaryFormat.Tests.csproj
@@ -8,8 +8,9 @@
      SYSLIB0011: BinaryFormatter obsolete
      SYSLIB0050: Obsolete attribute
      SYSLIB0051: Formatters obsolete
+     SYSLIB5005: System.Formats.Nrbf experimental
     -->
-    <NoWarn>$(NoWarn);CS1574;CS1580;CA1036;CA1051;CA1066;SYSLIB0011;SYSLIB0050;SYSLIB0051;xUnit1013;CS0649</NoWarn>
+    <NoWarn>$(NoWarn);CS1574;CS1580;CA1036;CA1051;CA1066;SYSLIB0011;SYSLIB0050;SYSLIB0051;SYSLIB5005;xUnit1013;CS0649</NoWarn>
     <StringResourcesPath>$(LibrariesProjectRoot)\System.Resources.Extensions\src\Resources\Strings.resx</StringResourcesPath>
   </PropertyGroup>