dotnet · gewarren · Jan 27, 2025 · Jan 19, 2025 · Jan 19, 2025 · Jan 19, 2025
@@ -4,6 +4,10 @@
             "source_path_from_root": "/docs/fundamentals/apicompat/package-validation/diagnostic-ids.md",
             "redirect_url": "/dotnet/fundamentals/apicompat/diagnostic-ids"
         },
+        {
+            "source_path_from_root": "/docs/fundamentals/apicompat/preview-apis.md",
+            "redirect_url": "/dotnet/fundamentals/runtime-libraries/preview-apis"
+        },
         {
             "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1071.md",
             "redirect_url": "/dotnet/fundamentals/code-analysis/quality-rules/index"

@@ -70,7 +70,7 @@ For more information, see [What's new in the SDK for .NET 9](sdk.md).
 - Builds on top of `TensorPrimitives` for efficient math operations.
 - Provides efficient interop with AI libraries (ML.NET, TorchSharp, ONNX Runtime) using zero copies where possible.
 - Enables easy and efficient data manipulation with indexing and slicing operations.
-- Is [experimental](../../../fundamentals/apicompat/preview-apis.md#experimentalattribute) in .NET 9.
+- Is [experimental](../../../fundamentals/runtime-libraries/preview-apis.md#experimentalattribute) in .NET 9.
 
 ### ML.NET
 
@@ -125,7 +125,7 @@ The focus of .NET Multi-platform App UI (.NET MAUI) in .NET 9 is enhanced perfor
 - <xref:Microsoft.Maui.Controls.Entry> now supports additional keyboard modes.
 - Control handlers automatically disconnect from their controls when possible.
 - <xref:Microsoft.Maui.Controls.Application.MainPage> is deprecated in favor of setting the primary page of the app by overriding <xref:Microsoft.Maui.Controls.Application.CreateWindow(Microsoft.Maui.IActivationState)?displayProperty=nameWithType> class.
-  
+
 For more information about that these new features and more, see [What's new in .NET MAUI for .NET 9](/dotnet/maui/whats-new/dotnet-9).
 
 ## EF Core

@@ -0,0 +1,69 @@
+---
+title: Preview APIs
+description: Learn how to mark .NET APIs as preview.
+ms.date: 01/27/2025
+---
+
+# Preview APIs
+
+The .NET platform takes compatibility seriously. As such, the library ecosystem tends to avoid making breaking changes, especially with respect to the API.
+
+Nonetheless, when designing APIs, it's important to be able to collect feedback from users and make changes to the API based on that feedback if necessary. To avoid surprises, you should understand which APIs you use are considered stable and which ones are still in active development and might change.
+
+There are multiple ways an API can express that it's in preview form:
+
+* The entire component is considered preview if it's exposed:
+
+  * In a preview release of the .NET runtime.
+  * In a prerelease NuGet package.
+
+* An otherwise stable component marks specific APIs as preview with the following attributes:
+
+  * <xref:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute>
+  * <xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute>
+
+This article explains how each option works, and, for library developers, how to choose between these options.
+
+## .NET runtime previews
+
+With the exception of release candidates (RCs) with a go-live license, preview versions of the .NET runtime and SDK aren't supported.
+
+As such, any APIs added as part of a .NET preview are considered subject to change, based on feedback the previews receive. To use a .NET runtime preview, you need to explicitly target a newer framework version in your project. By doing so, you implicitly express consent to consume APIs that might change.
+
+## Prerelease NuGet packages
+
+NuGet packages can either be stable or *prerelease*. Prerelease packages are marked as such with a prerelease suffix on their version. For example, `System.Text.Json 9.0.0-preview.2.24128.5` has a prerelease suffix of `preview.2.24128.5`.
+
+Prerelease packages are commonly used as a means to collect feedback from early adopters. They are generally unsupported by their author.
+
+When you install a package, either via the CLI or UI, you must explicitly indicate whether you want to install a prerelease version. By doing so, you implicitly express consent to consume APIs that might change.
+
+## `RequiresPreviewFeaturesAttribute`
+
+The <xref:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute> attribute is used for APIs that require preview behaviors across the stack, including the runtime, the C# compiler, and libraries. When you consume APIs marked with this attribute, you'll receive a build error unless your project file includes the property `<EnablePreviewFeatures>true</EnablePreviewFeatures>`. Setting that property to `true` also sets `<LangVersion>Preview</LangVersion>`, which allows the use of preview language features.
+
+As an example, in .NET 6 the *generic math* library was marked with <xref:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute> because it required static interface members, which were in preview at the time.
+
+## `ExperimentalAttribute`
+
+.NET 8 added <xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute>, which doesn't require any runtime or language preview features and simply indicates that a given API isn't stable yet.
+
+When building against an experimental API, the compiler produces an error. Each feature that's marked as experimental has its own separate diagnostic ID. To express consent to using an experimental API, 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 `<NoWarn>` property.
+
+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].
+
+## Guidance for library developers
+
+Library developers should generally express that an API is in preview in one of two ways:
+
+* For new APIs introduced in a *prerelease* version of your package, you don't need to do anything; the package already expresses preview quality.
+* If you want to ship a stable package that contains some preview quality APIs, you should mark those APIs using `[Experimental]`. Make sure to use [your own diagnostic ID][choosing-diagnostic-ids] and make it specific to those features. If you have multiple independent features, consider using multiple IDs.
+
+The `[RequiresPreviewFeatures]` attribute is only meant for components of the .NET platform itself. Even there, it's only used for APIs that require runtime and language preview features. If it's just an API that's in preview, the .NET platform uses the `[Experimental]` attribute.
+
+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
@@ -17,13 +17,13 @@ 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 version | Description |
-| - | - | - |
-| SYSLIB5001 | .NET 9 | <xref:System.Numerics.Tensors.Tensor%601> and related APIs in <xref:System.Numerics.Tensors> are experimental |
-| SYSLIB5002 | .NET 9 | <xref:System.Drawing.SystemColors> alternate colors are experimental |
-| [SYSLIB5003](./syslib5003.md) | .NET 9 | <xref:System.Runtime.Intrinsics.Arm.Sve> is experimental |
-| SYSLIB5004 | .NET 9 | <xref:System.Runtime.Intrinsics.X86.X86Base.DivRem(System.UInt32,System.Int32,System.Int32)> is experimental since performance is not as optimized as `T.DivRem` |
-| SYSLIB5005 | .NET 9 | <xref:System.Formats.Nrbf> is experimental |
+| Diagnostic ID                 | Experimental version | Description                                                          |
+|-------------------------------|----------------------|----------------------------------------------------------------------|
+| SYSLIB5001                    | .NET 9               | <xref:System.Numerics.Tensors.Tensor%601> and related APIs in <xref:System.Numerics.Tensors> are experimental |
+| SYSLIB5002                    | .NET 9               | <xref:System.Drawing.SystemColors> alternate colors are experimental |
+| [SYSLIB5003](./syslib5003.md) | .NET 9               | <xref:System.Runtime.Intrinsics.Arm.Sve> is experimental             |
+| SYSLIB5004                    | .NET 9               | <xref:System.Runtime.Intrinsics.X86.X86Base.DivRem(System.UInt32,System.Int32,System.Int32)> is experimental since performance is not as optimized as `T.DivRem` |
+| SYSLIB5005                    | .NET 9               | <xref:System.Formats.Nrbf> is experimental                           |
 
 ## Suppress warnings
 
@@ -61,4 +61,4 @@ To suppress the warnings in code:
 
 ## See also
 
-- [Preview APIs](../apicompat/preview-apis.md)
+- [Preview APIs](../runtime-libraries/preview-apis.md)
@@ -540,6 +540,8 @@ items:
     items:
       - name: Overview
         href: ../standard/runtime-libraries-overview.md
+      - name: Preview APIs
+        href: runtime-libraries/preview-apis.md
       - name: Format numbers, dates, other types
         items:
           - name: Overview

@@ -1925,8 +1925,6 @@ items:
       - name: Overview
         href: ../../fundamentals/apicompat/overview.md
         displayName: api compatibility,apicompat
-      - name: Preview APIs
-        href: ../../fundamentals/apicompat/preview-apis.md
       - name: Diagnostic IDs
         href: ../../fundamentals/apicompat/diagnostic-ids.md
       - name: Assembly validation

@@ -65,20 +65,20 @@ A NuGet package supports many [metadata properties](/nuget/reference/nuspec). Th
 
 > Source Link automatically adds `RepositoryUrl` and `RepositoryType` metadata to the NuGet package. Source Link also adds information about the exact source code the package was built from. For example, a package created from a Git repository will have the commit hash added as metadata.
 
-## Pre-release packages
+## Prerelease packages
 
-NuGet packages with a version suffix are considered [pre-release](/nuget/create-packages/prerelease-packages). By default, the NuGet Package Manager UI shows stable releases unless a user opts-in to pre-release packages, making pre-release packages ideal for limited user testing.
+NuGet packages with a version suffix are considered [prerelease](/nuget/create-packages/prerelease-packages). By default, the NuGet Package Manager UI shows stable releases unless a user opts-in to prerelease packages, making prerelease packages ideal for limited user testing.
 
 ```xml
 <PackageVersion>1.0.1-beta1</PackageVersion>
 ```
 
 > [!NOTE]
-> A stable package cannot depend on a pre-release package. You must either make your own package pre-release or depend on an older stable version.
+> A stable package cannot depend on a prerelease package. You must either make your own package prerelease or depend on an older stable version.
 
-![NuGet pre-release package dependency](./media/nuget/nuget-prerelease-package.png "NuGet pre-release package dependency")
+![NuGet prerelease package dependency](./media/nuget/nuget-prerelease-package.png "NuGet prerelease package dependency")
 
-✔️ DO publish a pre-release package when testing, previewing, or experimenting.
+✔️ DO publish a prerelease package when testing, previewing, or experimenting.
 
 ✔️ DO publish a stable package when it's ready so other stable packages can reference it.