From 44d70a2cde88058a883aef6374e5159538c680c4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Sat, 18 Jan 2025 17:16:10 -0800 Subject: [PATCH 1/5] move preview apis article --- .openpublishing.redirection.fundamentals.json | 4 ++ docs/fundamentals/apicompat/preview-apis.md | 72 ------------------- .../runtime-libraries/preview-apis.md | 69 ++++++++++++++++++ docs/fundamentals/toc.yml | 4 +- docs/standard/library-guidance/versioning.md | 19 +++-- 5 files changed, 88 insertions(+), 80 deletions(-) delete mode 100644 docs/fundamentals/apicompat/preview-apis.md create mode 100644 docs/fundamentals/runtime-libraries/preview-apis.md diff --git a/.openpublishing.redirection.fundamentals.json b/.openpublishing.redirection.fundamentals.json index c0c1dd8542380..0628c88210ff8 100644 --- a/.openpublishing.redirection.fundamentals.json +++ b/.openpublishing.redirection.fundamentals.json @@ -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/preview-apis" + }, { "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1071.md", "redirect_url": "/dotnet/fundamentals/code-analysis/quality-rules/index" diff --git a/docs/fundamentals/apicompat/preview-apis.md b/docs/fundamentals/apicompat/preview-apis.md deleted file mode 100644 index 42fad69e6ca33..0000000000000 --- a/docs/fundamentals/apicompat/preview-apis.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Preview APIs -description: Learn how to mark .NET APIs as preview. -ms.date: 4/4/2024 ---- - -# Preview APIs - -The .NET platform prides itself with taking 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 collect feedback from users and change the API based on that feedback if necessary. To avoid surprises, it's important that users understand which APIs are considered stable and which ones are still in active development and might change. - -There are multiple ways an API can express to be in preview form: - -* The entire component is considered preview: - - * Exposed in a preview release of the .NET runtime - * Exposed in a prerelease NuGet package - -* An otherwise stable component specifically marks certain APIs as preview: - - * Marked with - * Marked with - -This article explains how to choose between these options and how each of them works. - -## .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. By doing so, you implicitly express consent to consume APIs that might change. - -## Prerelease NuGet packages - -NuGet packages can either be stable or marked as prerelease, that is, the package has a prerelease suffix. For example, `System.Text.Json 9.0.0-preview.2.24128.5` has a prerelease suffix of `preview.2.24128.5`. - -Package authors generally don't support prerelease packages and use them as a means to collect feedback from early adopters. - -When installing packages, either via the CLI or UI, you generally have to explicitly indicate whether you want to install prerelease, again implicitly expressing consent to consume APIs that might change. - -## `RequiresPreviewFeaturesAttribute` - -Since .NET 6, the platform includes the attribute. - -This 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 sets `true`. Setting that property to `true` also sets `Preview`, allowing the use of preview language features. - -The .NET team used the attribute in .NET 6 to test out generic math, because it required static interface members, which were in preview at the time. - -## `ExperimentalAttribute` - -.NET 8 added , 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 will produce an error. Each feature that is marked as experimental has its own separate 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. - -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]`: - -* 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]`. Ensure 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. And 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 diff --git a/docs/fundamentals/runtime-libraries/preview-apis.md b/docs/fundamentals/runtime-libraries/preview-apis.md new file mode 100644 index 0000000000000..678687ea564d4 --- /dev/null +++ b/docs/fundamentals/runtime-libraries/preview-apis.md @@ -0,0 +1,69 @@ +--- +title: Preview APIs +description: Learn how to mark .NET APIs as preview. +ms.date: 4/4/2024 +--- + +# 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 to be 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: + + * + * + +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 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 `true`. Setting that property to `true` also sets `Preview`, which allows the use of preview language features. + +As an example, in .NET 6 the *generic math* library was marked with because it required static interface members, which were in preview at the time. + +## `ExperimentalAttribute` + +.NET 8 added , 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 `` 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 diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index f3c21c755d52a..168aafab75afc 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -539,7 +539,9 @@ items: - name: Runtime libraries items: - name: Overview - href: ../standard/runtime-libraries-overview.md + href: ../standard/ + - name: Preview APIs + href: runtime-libraries/preview-apis.md - name: Format numbers, dates, other types items: - name: Overview diff --git a/docs/standard/library-guidance/versioning.md b/docs/standard/library-guidance/versioning.md index fd68f4ebacd47..cdb1f473532b0 100644 --- a/docs/standard/library-guidance/versioning.md +++ b/docs/standard/library-guidance/versioning.md @@ -5,7 +5,7 @@ ms.date: 01/26/2021 --- # Versioning -A software library is rarely complete in version 1.0. Good libraries evolve over time, adding features, fixing bugs, and improving performance. It is important that you can release new versions of a .NET library, providing additional value with each version, without breaking existing users. +A software library is rarely complete in version 1.0. Good libraries evolve over time, adding features, fixing bugs, and improving performance. It's important that you can release new versions of a .NET library without breaking existing users. ## Breaking changes @@ -15,25 +15,30 @@ For information about handling breaking changes between versions, see [Breaking A .NET library has many ways to specify a version. These versions are the most important: +- [NuGet package version](#nuget-package-version) +- [Assembly version](#assembly-version) +- [Assembly file version](#assembly-file-version) +- [Assembly informational version](#assembly-informational-version) + ### NuGet package version -The [NuGet package version](/nuget/reference/package-versioning) is displayed on NuGet.org, the Visual Studio NuGet package manager, and is added to source code when the package is used. The NuGet package version is the version number users will commonly see, and they'll refer to it when they talk about the version of a library they're using. The NuGet package version is used by NuGet and has no effect on runtime behavior. +The [NuGet package version](/nuget/reference/package-versioning) is displayed on NuGet.org and the Visual Studio NuGet package manager, and is added to source code when the package is used. The NuGet package version is the version number users will commonly see, and they'll refer to it when they talk about the version of a library they're using. The NuGet package version is used by NuGet and has no effect on runtime behavior. ```xml 1.0.0-alpha1 ``` -The NuGet package identifier combined with the NuGet package version is used to identify a package in NuGet. For example, `Newtonsoft.Json` + `11.0.2`. A package with a suffix is a pre-release package and has special behavior that makes it ideal for testing. For more information, see [Pre-release packages](./nuget.md#pre-release-packages). +The NuGet package identifier combined with the NuGet package version is used to identify a package in NuGet. For example, `Newtonsoft.Json` + `11.0.2`. A package with a suffix is a prerelease package and has special behavior that makes it ideal for testing. For more information, see [prerelease packages](./nuget.md#prerelease-packages). -Because the NuGet package version is the most visible version to developers, it's a good idea to update it using [Semantic Versioning (SemVer)](https://semver.org/). SemVer indicates the significance of changes between release and helps developers make an informed decision when choosing what version to use. For example, going from `1.0` to `2.0` indicates that there are potentially breaking changes. +Because the NuGet package version is the most visible version to developers, it's a good idea to update it using [Semantic Versioning (SemVer)](https://semver.org/). SemVer indicates the significance of changes between releases and helps developers make an informed decision when choosing what version to use. For example, going from `1.0` to `2.0` indicates that there are potentially breaking changes. ✔️ CONSIDER using [SemVer 2.0.0](https://semver.org/) to version your NuGet package. ✔️ DO use the NuGet package version in public documentation as it's the version number that users will commonly see. -✔️ DO include a pre-release suffix when releasing a non-stable package. +✔️ DO include a prerelease suffix when releasing a nonstable package. (For more information about marking APIs as preview or experimental, see [Preview APIs](../../fundamentals/runtime-libraries/preview-apis.md).) -> Users must opt in to getting pre-release packages, so they will understand that the package is not complete. + > Users must opt in to getting prerelease packages, so they understand that the package is not complete. ### Assembly version @@ -45,7 +50,7 @@ The assembly version is what the CLR uses at run time to select which version of The .NET Framework CLR demands an exact match to load a strong-named assembly. For example, `Library1, Version=1.0.0.0` was compiled with a reference to `Newtonsoft.Json, Version=11.0.0.0`. .NET Framework will only load that exact version `11.0.0.0`. To load a different version at run time, a binding redirect must be added to the .NET application's config file. -Strong naming combined with assembly version enables [strict assembly version loading](../assembly/versioning.md). While strong naming a library has a number of benefits, it often results in run-time exceptions that an assembly can't be found and [requires binding redirects](../../framework/configure-apps/redirect-assembly-versions.md) in `app.config` or `web.config` to be fixed. In .NET Core, assembly loading is more relaxed. The .NET Core runtime automatically loads assemblies with a higher version at run time. +Strong naming combined with assembly version enables [strict assembly version loading](../assembly/versioning.md). While strong naming a library has a number of benefits, it often results in run-time exceptions that an assembly can't be found and [requires binding redirects](../../framework/configure-apps/redirect-assembly-versions.md) in `app.config` or `web.config` to be fixed. In .NET (Core), assembly loading is more relaxed. The .NET (Core) runtime automatically loads assemblies with a higher version at run time. ✔️ CONSIDER only including a major version in the AssemblyVersion. From f068202d7adbee015f3836a1ef5b61e4a733f1aa Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Sat, 18 Jan 2025 17:18:46 -0800 Subject: [PATCH 2/5] remove old toc entry --- .openpublishing.redirection.fundamentals.json | 2 +- docs/navigate/tools-diagnostics/toc.yml | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/.openpublishing.redirection.fundamentals.json b/.openpublishing.redirection.fundamentals.json index 0628c88210ff8..75ff5502a916c 100644 --- a/.openpublishing.redirection.fundamentals.json +++ b/.openpublishing.redirection.fundamentals.json @@ -6,7 +6,7 @@ }, { "source_path_from_root": "/docs/fundamentals/apicompat/preview-apis.md", - "redirect_url": "/dotnet/fundamentals/preview-apis" + "redirect_url": "/dotnet/fundamentals/runtime-libraries/preview-apis" }, { "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1071.md", diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 413e1b7ab298a..9df4e4f632bca 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -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 From ed83e4c8a66397255103d51301bc6a19b38ff987 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Sun, 19 Jan 2025 12:23:43 -0800 Subject: [PATCH 3/5] fix build warnings --- docs/fundamentals/toc.yml | 2 +- docs/standard/library-guidance/nuget.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 168aafab75afc..085d715dfd474 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -539,7 +539,7 @@ items: - name: Runtime libraries items: - name: Overview - href: ../standard/ + href: ../standard/runtime-libraries-overview.md - name: Preview APIs href: runtime-libraries/preview-apis.md - name: Format numbers, dates, other types diff --git a/docs/standard/library-guidance/nuget.md b/docs/standard/library-guidance/nuget.md index 6d6c6ec871844..5e40529f3e957 100644 --- a/docs/standard/library-guidance/nuget.md +++ b/docs/standard/library-guidance/nuget.md @@ -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 1.0.1-beta1 ``` > [!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. From 068ca084467178dfdff6a2c6ec631124635d0c5e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 21 Jan 2025 12:19:47 -0800 Subject: [PATCH 4/5] fix links --- docs/core/whats-new/dotnet-9/overview.md | 4 ++-- .../syslib-diagnostics/experimental-overview.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/core/whats-new/dotnet-9/overview.md b/docs/core/whats-new/dotnet-9/overview.md index b4db955e4c5cf..b054069c19e35 100644 --- a/docs/core/whats-new/dotnet-9/overview.md +++ b/docs/core/whats-new/dotnet-9/overview.md @@ -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 - now supports additional keyboard modes. - Control handlers automatically disconnect from their controls when possible. - is deprecated in favor of setting the primary page of the app by overriding 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 diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md index 495e2afb4e0f8..7ecbfa741fbcf 100644 --- a/docs/fundamentals/syslib-diagnostics/experimental-overview.md +++ b/docs/fundamentals/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 | and related APIs in are experimental | -| SYSLIB5002 | .NET 9 | alternate colors are experimental | -| [SYSLIB5003](./syslib5003.md) | .NET 9 | is experimental | -| SYSLIB5004 | .NET 9 | is experimental since performance is not as optimized as `T.DivRem` | -| SYSLIB5005 | .NET 9 | is experimental | +| Diagnostic ID | Experimental version | Description | +|-------------------------------|----------------------|----------------------------------------------------------------------| +| SYSLIB5001 | .NET 9 | and related APIs in are experimental | +| SYSLIB5002 | .NET 9 | alternate colors are experimental | +| [SYSLIB5003](./syslib5003.md) | .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 @@ -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) From d1fafd3f887a3ca52d49a18d5fc278f9cbc81d18 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 27 Jan 2025 12:16:03 -0800 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Bill Wagner --- docs/fundamentals/runtime-libraries/preview-apis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/runtime-libraries/preview-apis.md b/docs/fundamentals/runtime-libraries/preview-apis.md index 678687ea564d4..0ce64693a5944 100644 --- a/docs/fundamentals/runtime-libraries/preview-apis.md +++ b/docs/fundamentals/runtime-libraries/preview-apis.md @@ -1,7 +1,7 @@ --- title: Preview APIs description: Learn how to mark .NET APIs as preview. -ms.date: 4/4/2024 +ms.date: 01/27/2025 --- # Preview APIs @@ -10,7 +10,7 @@ The .NET platform takes compatibility seriously. As such, the library ecosystem 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 to be in preview form: +There are multiple ways an API can express that it's in preview form: * The entire component is considered preview if it's exposed: