From 7e8d1daaf40d0cf676ecc15bbc47527fe353720e Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Fri, 18 Oct 2024 18:38:24 -0700 Subject: [PATCH 1/8] Add an Experimental APIs overview page --- .../experimental-overview.md | 65 +++++++++++++++++++ docs/navigate/tools-diagnostics/toc.yml | 5 ++ 2 files changed, 70 insertions(+) create mode 100644 docs/fundamentals/syslib-diagnostics/experimental-overview.md diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md new file mode 100644 index 0000000000000..b164aea97ef62 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/experimental-overview.md @@ -0,0 +1,65 @@ +--- +title: Experimental features in .NET 9+ +titleSuffix: "" +description: Learn about APIs that are marked as experimental in .NET 9 and later versions that produce SYSLIB compiler warnings. +ms.date: 10/21/2024 +--- + +# Experimental features in .NET 9+ + +Starting in .NET 9, some features make use of the to indicate that the API shape or functionality is included in the release but not yet officially supported. Experimental features offer the opportunity to collect feedback on the API shape and functionality with the intent of refining the APIs and removing the `[Experimental]` attribute in the next major release. + +When an experimental API is referenced, the compiler will produce an error. Each feature that is marked as experimental has a unique diagnostic ID. To express consent to using them, you suppress the specific diagnostic. You can do that via any of the means for suppressing diagnostics, but the recommended way is to add the diagnostic to the project's `` property. For more information, see [Suppress warnings](#suppress-warnings). + +Since each experimental feature has a separate ID, consenting to using one experimental feature doesn't consent to using another. + +## Reference + +The following table provides an index to the `SYSLIB5XXX` experimental APIs in .NET 9+. + +| Diagnostic ID | Experimental Versions | Description | +| - | - | - | +| SYSLIB5001 | .NET 9 | and related APIs in are experimental | +| SYSLIB5002 | .NET 9 | alternate colors are experimental | +| SYSLIB5003 | .NET 9 | is experimental | +| SYSLIB5004 | .NET 9 | is experimental since performance is not as optimized as `T.DivRem` | +| SYSLIB5005 | .NET 9 | is experimental | + + +## Suppress warnings + +Using an experimental feature offers the opportunity to submit feedback on the API shape and functionality before the feature is marked as stable and fully supported, but using the feature will produce a warning from the compiler. Suppressing the warning acknowledges that the API shape or functionality might change in the next major release. The warning can be suppressed through a `#pragma` directive in code or a `` project setting. + +To suppress the warnings in code: + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB5001 + +// Code that uses an experimental API that produces the diagnostic SYSLIB5001 +//... + +// Re-enable the warning. +#pragma warning restore SYSLIB5001 +``` + +To suppress the warnings in a project file: + +```xml + + + net9.0 + + $(NoWarn);SYSLIB5001 + + $(NoWarn);SYSLIB5002 + $(NoWarn);SYSLIB5003 + + $(NoWarn);SYSLIB5001;SYSLIB5002;SYSLIB5003 + + +``` + +## See also + +- [Preview APIs](../../../fundamentals/apicompat/preview-apis.md) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 5e2bd415760b8..8a82233ea88e4 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1800,6 +1800,11 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0056.md - name: SYSLIB0057 href: ../../fundamentals/syslib-diagnostics/syslib0057.md + - name: Experimental features + items: + - name: Overview + displayName: syslib, experimental + href: ../../fundamentals/syslib-diagnostics/experimental-overview.md - name: Source-generated code items: - name: Overview From a86d50334f2d5451413c8813bd5f198b6ae319dc Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Fri, 18 Oct 2024 18:45:20 -0700 Subject: [PATCH 2/8] Update link for Tensor APIs to point to the new experimental APIs overview page --- docs/core/whats-new/dotnet-9/libraries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/whats-new/dotnet-9/libraries.md b/docs/core/whats-new/dotnet-9/libraries.md index aeb42b7cee2dd..48c09d6e7f033 100644 --- a/docs/core/whats-new/dotnet-9/libraries.md +++ b/docs/core/whats-new/dotnet-9/libraries.md @@ -757,7 +757,7 @@ The following codes shows some of the APIs included with the new `Tensor` typ :::code language="csharp" source="../snippets/dotnet-9/csharp/Tensors.cs" id="Tensor"::: > [!NOTE] -> This API is marked as [experimental](../../../fundamentals/apicompat/preview-apis.md#experimentalattribute) for .NET 9. +> This API is marked as [experimental](../../../fundamentals/syslib-diagnostics/experimental-overview) for .NET 9. ### TensorPrimitives From 71eb18da424ced3e06f0fb9212a441fb30355d40 Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Fri, 18 Oct 2024 18:50:06 -0700 Subject: [PATCH 3/8] Update DivRem xref --- docs/fundamentals/syslib-diagnostics/experimental-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md index b164aea97ef62..f919429404a66 100644 --- a/docs/fundamentals/syslib-diagnostics/experimental-overview.md +++ b/docs/fundamentals/syslib-diagnostics/experimental-overview.md @@ -22,7 +22,7 @@ The following table provides an index to the `SYSLIB5XXX` experimental APIs in . | SYSLIB5001 | .NET 9 | and related APIs in are experimental | | SYSLIB5002 | .NET 9 | alternate colors are experimental | | SYSLIB5003 | .NET 9 | is experimental | -| SYSLIB5004 | .NET 9 | is experimental since performance is not as optimized as `T.DivRem` | +| SYSLIB5004 | .NET 9 | is experimental since performance is not as optimized as `T.DivRem` | | SYSLIB5005 | .NET 9 | is experimental | From baa0e3ebc7add996941ab8b96399d50a8cd860d7 Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Mon, 21 Oct 2024 09:40:24 -0700 Subject: [PATCH 4/8] Fix lint error and invalid links --- docs/core/whats-new/dotnet-9/libraries.md | 2 +- docs/fundamentals/syslib-diagnostics/experimental-overview.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/core/whats-new/dotnet-9/libraries.md b/docs/core/whats-new/dotnet-9/libraries.md index 48c09d6e7f033..0356d756fabc9 100644 --- a/docs/core/whats-new/dotnet-9/libraries.md +++ b/docs/core/whats-new/dotnet-9/libraries.md @@ -757,7 +757,7 @@ The following codes shows some of the APIs included with the new `Tensor` typ :::code language="csharp" source="../snippets/dotnet-9/csharp/Tensors.cs" id="Tensor"::: > [!NOTE] -> This API is marked as [experimental](../../../fundamentals/syslib-diagnostics/experimental-overview) for .NET 9. +> This API is marked as [experimental](../../../fundamentals/syslib-diagnostics/experimental-overview.md) for .NET 9. ### TensorPrimitives diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md index f919429404a66..69e8715c77f3d 100644 --- a/docs/fundamentals/syslib-diagnostics/experimental-overview.md +++ b/docs/fundamentals/syslib-diagnostics/experimental-overview.md @@ -25,7 +25,6 @@ The following table provides an index to the `SYSLIB5XXX` experimental APIs in . | SYSLIB5004 | .NET 9 | is experimental since performance is not as optimized as `T.DivRem` | | SYSLIB5005 | .NET 9 | is experimental | - ## Suppress warnings Using an experimental feature offers the opportunity to submit feedback on the API shape and functionality before the feature is marked as stable and fully supported, but using the feature will produce a warning from the compiler. Suppressing the warning acknowledges that the API shape or functionality might change in the next major release. The warning can be suppressed through a `#pragma` directive in code or a `` project setting. @@ -62,4 +61,4 @@ To suppress the warnings in a project file: ## See also -- [Preview APIs](../../../fundamentals/apicompat/preview-apis.md) +- [Preview APIs](../apicompat/preview-apis.md) From 14f48f22d58481873ae0b1506ee77c2d099c4ad9 Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Tue, 22 Oct 2024 15:53:43 -0700 Subject: [PATCH 5/8] Apply feedback from review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../syslib-diagnostics/experimental-overview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md index 69e8715c77f3d..8d66f68bd1be5 100644 --- a/docs/fundamentals/syslib-diagnostics/experimental-overview.md +++ b/docs/fundamentals/syslib-diagnostics/experimental-overview.md @@ -7,9 +7,9 @@ ms.date: 10/21/2024 # Experimental features in .NET 9+ -Starting in .NET 9, some features make use of the to indicate that the API shape or functionality is included in the release but not yet officially supported. Experimental features offer the opportunity to collect feedback on the API shape and functionality with the intent of refining the APIs and removing the `[Experimental]` attribute in the next major release. +Starting in .NET 9, some features make use of the to indicate that the API shape or functionality is included in the release but not yet officially supported. Experimental features let the .NET team collect feedback on an API's shape and functionality with the intent of refining the API and removing the `[Experimental]` attribute in the next major release. -When an experimental API is referenced, the compiler will produce an error. Each feature that is marked as experimental has a unique diagnostic ID. To express consent to using them, you suppress the specific diagnostic. You can do that via any of the means for suppressing diagnostics, but the recommended way is to add the diagnostic to the project's `` property. For more information, see [Suppress warnings](#suppress-warnings). +When your code references an experimental API, the compiler produces an error with an ID like `SYSLIB5XXX`. Each feature that's marked as experimental has a unique diagnostic ID. To express consent to using an experimental feature, you suppress the specific diagnostic. You can do that via any of the means for suppressing diagnostics, but the recommended way is to add the diagnostic to the project's `` property. For more information, see [Suppress warnings](#suppress-warnings). Since each experimental feature has a separate ID, consenting to using one experimental feature doesn't consent to using another. @@ -17,7 +17,7 @@ Since each experimental feature has a separate ID, consenting to using one exper The following table provides an index to the `SYSLIB5XXX` experimental APIs in .NET 9+. -| Diagnostic ID | Experimental Versions | Description | +| Diagnostic ID | Experimental version | Description | | - | - | - | | SYSLIB5001 | .NET 9 | and related APIs in are experimental | | SYSLIB5002 | .NET 9 | alternate colors are experimental | @@ -27,7 +27,7 @@ The following table provides an index to the `SYSLIB5XXX` experimental APIs in . ## Suppress warnings -Using an experimental feature offers the opportunity to submit feedback on the API shape and functionality before the feature is marked as stable and fully supported, but using the feature will produce a warning from the compiler. Suppressing the warning acknowledges that the API shape or functionality might change in the next major release. The warning can be suppressed through a `#pragma` directive in code or a `` project setting. +Using an experimental feature gives you the opportunity to submit feedback on the API shape and functionality before the feature is marked as stable and fully supported. But using the feature produces a warning from the compiler. When you suppress the warning, you acknowledge that the API shape or functionality might change in the next major release. The API might even be removed. You can suppress the warning through a `#pragma` directive in code or a `` project setting. To suppress the warnings in code: From 832d7df62d67f5b2b95e5fdd35e52c58c034909e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 24 Oct 2024 15:07:30 -0700 Subject: [PATCH 6/8] Swap suppression sections --- .../experimental-overview.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md index 8d66f68bd1be5..0699398b7ac77 100644 --- a/docs/fundamentals/syslib-diagnostics/experimental-overview.md +++ b/docs/fundamentals/syslib-diagnostics/experimental-overview.md @@ -29,19 +29,6 @@ The following table provides an index to the `SYSLIB5XXX` experimental APIs in . Using an experimental feature gives you the opportunity to submit feedback on the API shape and functionality before the feature is marked as stable and fully supported. But using the feature produces a warning from the compiler. When you suppress the warning, you acknowledge that the API shape or functionality might change in the next major release. The API might even be removed. You can suppress the warning through a `#pragma` directive in code or a `` project setting. -To suppress the warnings in code: - -```csharp -// Disable the warning. -#pragma warning disable SYSLIB5001 - -// Code that uses an experimental API that produces the diagnostic SYSLIB5001 -//... - -// Re-enable the warning. -#pragma warning restore SYSLIB5001 -``` - To suppress the warnings in a project file: ```xml @@ -59,6 +46,19 @@ To suppress the warnings in a project file: ``` +To suppress the warnings in code: + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB5001 + +// Code that uses an experimental API that produces the diagnostic SYSLIB5001 +//... + +// Re-enable the warning. +#pragma warning restore SYSLIB5001 +``` + ## See also - [Preview APIs](../apicompat/preview-apis.md) From 0e0581e45ef07586bdc081f3501345041d1f546c Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 24 Oct 2024 15:09:18 -0700 Subject: [PATCH 7/8] Update docs/fundamentals/syslib-diagnostics/experimental-overview.md --- docs/fundamentals/syslib-diagnostics/experimental-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md index 0699398b7ac77..f180077ce23e9 100644 --- a/docs/fundamentals/syslib-diagnostics/experimental-overview.md +++ b/docs/fundamentals/syslib-diagnostics/experimental-overview.md @@ -27,7 +27,7 @@ The following table provides an index to the `SYSLIB5XXX` experimental APIs in . ## Suppress warnings -Using an experimental feature gives you the opportunity to submit feedback on the API shape and functionality before the feature is marked as stable and fully supported. But using the feature produces a warning from the compiler. When you suppress the warning, you acknowledge that the API shape or functionality might change in the next major release. The API might even be removed. You can suppress the warning through a `#pragma` directive in code or a `` project setting. +Using an experimental feature gives you the opportunity to submit feedback on the API shape and functionality before the feature is marked as stable and fully supported. But using the feature produces a warning from the compiler. When you suppress the warning, you acknowledge that the API shape or functionality might change in the next major release. The API might even be removed. You can suppress the warning through a `` project setting (recommended) or a `#pragma` directive in code. To suppress the warnings in a project file: From e7f73d54dec1d94e6ebcc22dd09ef2eb44002130 Mon Sep 17 00:00:00 2001 From: Jeff Handley Date: Thu, 24 Oct 2024 15:20:09 -0700 Subject: [PATCH 8/8] Add a link to Experimental features from Preview APIs --- docs/fundamentals/apicompat/preview-apis.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/fundamentals/apicompat/preview-apis.md b/docs/fundamentals/apicompat/preview-apis.md index 6fbfc5ee8be89..42fad69e6ca33 100644 --- a/docs/fundamentals/apicompat/preview-apis.md +++ b/docs/fundamentals/apicompat/preview-apis.md @@ -54,6 +54,8 @@ When building against an experimental API, the compiler will produce an error. E Since each experimental feature has a separate ID, consenting to using one experimental feature doesn't consent to using another. +For more information, see [Experimental features][experimental-overview]. + ## Choose between the options Library developers should only use prerelease NuGet packages or mark APIs with `[Experimental]`: @@ -67,3 +69,4 @@ The `[RequiresPreviewFeatures]` attribute is only meant for components of the .N The exception to this rule is if you're building a stable library and want to expose certain features that in turn depend on runtime or language preview behaviors. In that case you should use `[RequiresPreviewFeatures]` for the entry points of that feature. However, you need to consider that users of such APIs have to turn on preview features too, which exposes them to all runtime, library, and language preview behaviors. [choosing-diagnostic-ids]: ../../csharp/roslyn-sdk/choosing-diagnostic-ids.md +[experimental-overview]: ../syslib-diagnostics/experimental-overview.md