Skip to content

Mark the System.Formats.Nrbf assembly as [Experimental] with SYSLIB5005 #107905

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 17, 2024
Merged

Mark the System.Formats.Nrbf assembly as [Experimental] with SYSLIB5005 #107905

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/project/list-of-diagnostics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
3 changes: 3 additions & 0 deletions src/libraries/Common/src/System/Experimentals.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
}
Expand Down
4 changes: 4 additions & 0 deletions src/libraries/System.Formats.Nrbf/ref/System.Formats.Nrbf.Experimental.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}")]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Huh, we don't have any kind of description on experimental that provides more detail in the diagnostic. I thought we did. Should we look at adding that? Someone can go to the docs, but it'd be nice if the message here could say that it's fully supported but the shape might change.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought we did too until I did one of the earlier experimentals. But yeah, that API doesn't have a message attribute; it always uses a message from Roslyn. I'll submit an API suggestion to add it.

5 changes: 5 additions & 0 deletions src/libraries/System.Formats.Nrbf/ref/System.Formats.Nrbf.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)" />
Expand Down
7 changes: 7 additions & 0 deletions src/libraries/System.Formats.Nrbf/src/AssemblyInfo.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)]
2 changes: 2 additions & 0 deletions src/libraries/System.Formats.Nrbf/src/PACKAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
15 changes: 9 additions & 6 deletions src/libraries/System.Formats.Nrbf/src/System.Formats.Nrbf.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 2 additions & 0 deletions src/libraries/System.Formats.Nrbf/tests/System.Formats.Nrbf.Tests.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
<PropertyGroup>
<TargetFrameworks>$(NetCoreAppCurrent);$(NetFrameworkMinimum)</TargetFrameworks>
<EnableDefaultItems>true</EnableDefaultItems>
<!-- SYSLIB5005: System.Formats.Nrbf is experimental -->
<NoWarn>$(NoWarn);SYSLIB5005</NoWarn>
</PropertyGroup>

<ItemGroup>
Expand Down
7 changes: 6 additions & 1 deletion ...aries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions src/libraries/System.Resources.Extensions/src/System.Resources.Extensions.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
3 changes: 2 additions & 1 deletion ....Extensions/tests/BinaryFormatTests/System.Resources.Extensions.BinaryFormat.Tests.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down
Loading