diff --git a/docs/core/docker/build-container.md b/docs/core/docker/build-container.md index 0817b3adc1633..6c466191613a9 100644 --- a/docs/core/docker/build-container.md +++ b/docs/core/docker/build-container.md @@ -1,7 +1,7 @@ --- title: Containerize an app with Docker tutorial description: In this tutorial, you learn how to containerize a .NET application with Docker. -ms.date: 01/07/2025 +ms.date: 11/06/2025 ms.topic: tutorial ms.custom: "mvc" zone_pivot_groups: dotnet-version @@ -33,12 +33,20 @@ You explore the Docker container build and deploy tasks for a .NET application. Install the following prerequisites: +:::zone pivot="dotnet-10-0" + +- [.NET 10+ SDK](https://dotnet.microsoft.com/download/dotnet/10.0).\ +If you have .NET installed, use the `dotnet --info` command to determine which SDK you're using. + +:::zone-end + :::zone pivot="dotnet-9-0" - [.NET 9+ SDK](https://dotnet.microsoft.com/download/dotnet/9.0).\ If you have .NET installed, use the `dotnet --info` command to determine which SDK you're using. :::zone-end + :::zone pivot="dotnet-8-0" - [.NET 8+ SDK](https://dotnet.microsoft.com/download/dotnet/8.0).\ @@ -99,16 +107,7 @@ Console.WriteLine("Hello World!"); Replace the file with the following code that counts numbers every second: -:::zone pivot="dotnet-9-0" - -:::code source="snippets/9.0/App/Program.cs"::: - -:::zone-end -:::zone pivot="dotnet-8-0" - -:::code source="snippets/8.0/App/Program.cs"::: - -:::zone-end +:::code source="snippets/App/Program.cs"::: Save the file and test the program again with `dotnet run`. Remember that this app runs indefinitely. Use the cancel command Ctrl+C to stop it. Consider the following example output: @@ -143,8 +142,6 @@ The `dotnet publish` command compiles your app to the _publish_ folder. The path From the _App_ folder, get a directory listing of the publish folder to verify that the _DotNet.Docker.dll_ file was created. -:::zone pivot="dotnet-9-0" - ```powershell dir .\bin\Release\net9.0\publish\ @@ -159,46 +156,15 @@ Mode LastWriteTime Length Name -a---- 1/6/2025 10:11 AM 340 DotNet.Docker.runtimeconfig.json ``` -:::zone-end -:::zone pivot="dotnet-8-0" - -```powershell -dir .\bin\Release\net8.0\publish\ - - Directory: C:\Users\default\docker-working\App\bin\Release\net8.0\publish - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 9/22/2023 9:17 AM 431 DotNet.Docker.deps.json --a--- 9/22/2023 9:17 AM 6144 DotNet.Docker.dll --a--- 9/22/2023 9:17 AM 157696 DotNet.Docker.exe --a--- 9/22/2023 9:17 AM 11688 DotNet.Docker.pdb --a--- 9/22/2023 9:17 AM 353 DotNet.Docker.runtimeconfig.json -``` - -:::zone-end - #### [Linux](#tab/linux) Use the `ls` command to get a directory listing and verify that the _DotNet.Docker.dll_ file was created. -:::zone pivot="dotnet-9-0" - ```bash me@DESKTOP:/docker-working/app$ ls bin/Release/net9.0/publish DotNet.Docker.deps.json DotNet.Docker.dll DotNet.Docker.exe DotNet.Docker.pdb DotNet.Docker.runtimeconfig.json ``` -:::zone-end -:::zone pivot="dotnet-8-0" - -```bash -me@DESKTOP:/docker-working/app$ ls bin/Release/net8.0/publish -DotNet.Docker.deps.json DotNet.Docker.dll DotNet.Docker.exe DotNet.Docker.pdb DotNet.Docker.runtimeconfig.json -``` - -:::zone-end - --- ## Create the Dockerfile @@ -207,31 +173,17 @@ The _Dockerfile_ file is used by the `docker build` command to create a containe Create a file named _Dockerfile_ in the directory containing the _.csproj_ and open it in a text editor. This tutorial uses the ASP.NET Core runtime image (which contains the .NET runtime image) and corresponds with the .NET console application. -:::zone pivot="dotnet-9-0" - -:::code language="docker" source="snippets/9.0/App/Dockerfile"::: +:::code language="docker" source="snippets/App/Dockerfile"::: > [!NOTE] > The ASP.NET Core runtime image is used intentionally here, although the `mcr.microsoft.com/dotnet/runtime:9.0` image could be used instead. -:::zone-end -:::zone pivot="dotnet-8-0" - -:::code language="docker" source="snippets/8.0/App/Dockerfile"::: - -> [!NOTE] -> The ASP.NET Core runtime image is used intentionally here, although the `mcr.microsoft.com/dotnet/runtime:8.0` image could be used instead. - -:::zone-end - > [!IMPORTANT] > Including a secure hash algorithm (SHA) after the image tag in a _Dockerfile_ is a best practice. This ensures that the image is not tampered with and that the image is the same as the one you expect. The SHA is a unique identifier for the image. For more information, see [Docker Docs: Pull an image by digest](https://docs.docker.com/reference/cli/docker/image/pull/#pull-an-image-by-digest-immutable-identifier). > [!TIP] > This _Dockerfile_ uses multi-stage builds, which optimize the final size of the image by layering the build and leaving only required artifacts. For more information, see [Docker Docs: multi-stage builds](https://docs.docker.com/build/building/multi-stage/). -:::zone pivot="dotnet-9-0" - The `FROM` keyword requires a fully qualified Docker container image name. The Microsoft Container Registry (MCR, mcr.microsoft.com) is a syndicate of Docker Hub, which hosts publicly accessible containers. The `dotnet` segment is the container repository, whereas the `sdk` or `aspnet` segment is the container image name. The image is tagged with `9.0`, which is used for versioning. Thus, `mcr.microsoft.com/dotnet/aspnet:9.0` is the .NET 9.0 runtime. Make sure that you pull the runtime version that matches the runtime targeted by your SDK. For example, the app created in the previous section used the .NET 9.0 SDK, and the base image referred to in the _Dockerfile_ is tagged with **9.0**. > [!IMPORTANT] @@ -263,37 +215,6 @@ Save the _Dockerfile_ file. The directory structure of the working folder should └──... ``` -:::zone-end -:::zone pivot="dotnet-8-0" - -The `FROM` keyword requires a fully qualified Docker container image name. The Microsoft Container Registry (MCR, mcr.microsoft.com) is a syndicate of Docker Hub, which hosts publicly accessible containers. The `dotnet` segment is the container repository, whereas the `sdk` or `aspnet` segment is the container image name. The image is tagged with `8.0`, which is used for versioning. Thus, `mcr.microsoft.com/dotnet/aspnet:8.0` is the .NET 8.0 runtime. Make sure that you pull the runtime version that matches the runtime targeted by your SDK. For example, the app created in the previous section used the .NET 8.0 SDK, and the base image referred to in the _Dockerfile_ is tagged with **8.0**. - -> [!IMPORTANT] -> When using Windows-based container images, you need to specify the image tag beyond simply `8.0`, for example, `mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-1809` instead of `mcr.microsoft.com/dotnet/aspnet:8.0`. Select an image name based on whether you're using Nano Server or Windows Server Core and which version of that OS. You can find a full list of all supported tags on .NET's [Docker Hub page](https://hub.docker.com/_/microsoft-dotnet). - -Save the _Dockerfile_ file. The directory structure of the working folder should look like the following. Some of the deeper-level files and folders are omitted to save space in the article: - -```Directory -πŸ“ docker-working - β””β”€β”€πŸ“‚ App - β”œβ”€β”€ Dockerfile - β”œβ”€β”€ DotNet.Docker.csproj - β”œβ”€β”€ Program.cs - β”œβ”€β”€πŸ“‚ bin - β”‚ β””β”€β”€πŸ“‚ Release - β”‚ β””β”€β”€πŸ“‚ net8.0 - β”‚ β””β”€β”€πŸ“‚ publish - β”‚ β”œβ”€β”€ DotNet.Docker.deps.json - β”‚ β”œβ”€β”€ DotNet.Docker.exe - β”‚ β”œβ”€β”€ DotNet.Docker.dll - β”‚ β”œβ”€β”€ DotNet.Docker.pdb - β”‚ └── DotNet.Docker.runtimeconfig.json - β””β”€β”€πŸ“ obj - └──... -``` - -:::zone-end - The `ENTRYPOINT` instruction sets `dotnet` as the host for the `DotNet.Docker.dll`. However, it's possible to instead define the `ENTRYPOINT` as the app executable itself, relying on the OS as the app host: ```dockerfile @@ -310,28 +231,13 @@ docker build -t counter-image -f Dockerfile . Docker processes each line in the _Dockerfile_. The `.` in the `docker build` command sets the build context of the image. The `-f` switch is the path to the _Dockerfile_. This command builds the image and creates a local repository named **counter-image** that points to that image. After this command finishes, run `docker images` to see a list of images installed: -:::zone pivot="dotnet-9-0" - ```console REPOSITORY TAG IMAGE ID CREATED SIZE counter-image latest 1c1f1433e51d 32 seconds ago 223MB ``` -:::zone-end -:::zone pivot="dotnet-8-0" - -```console -docker images -REPOSITORY TAG IMAGE ID CREATED SIZE -counter-image latest 2f15637dc1f6 10 minutes ago 217MB -``` - -:::zone-end - The `counter-image` repository is the name of the image. Additionally, the image tag, image identifier, size and when it was created are all part of the output. The final steps of the _Dockerfile_ are to create a container from the image and run the app, copy the published app to the container, and define the entry point: -:::zone pivot="dotnet-9-0" - ```dockerfile FROM mcr.microsoft.com/dotnet/aspnet:9.0 WORKDIR /App @@ -339,18 +245,6 @@ COPY --from=build /App/out . ENTRYPOINT ["dotnet", "DotNet.Docker.dll"] ``` -:::zone-end -:::zone pivot="dotnet-8-0" - -```dockerfile -FROM mcr.microsoft.com/dotnet/aspnet:8.0 -WORKDIR /App -COPY --from=build /App/out . -ENTRYPOINT ["dotnet", "DotNet.Docker.dll"] -``` - -:::zone-end - The `FROM` command specifies the base image and tag to use. The `WORKDIR` command changes the **current directory** inside of the container to _App_. The `COPY` command tells Docker to copy the specified source directory to a destination folder. In this example, the _publish_ contents in the `build` layer are output into the folder named _App/out_, so it's the source to copy from. All of the published contents in the _App/out_ directory are copied into current working directory (_App_). @@ -580,6 +474,15 @@ During this tutorial, you created containers and images. If you want, delete the Next, delete any images that you no longer want on your machine. Delete the image created by your _Dockerfile_ and then delete the .NET image the _Dockerfile_ was based on. You can use the **IMAGE ID** or the **REPOSITORY:TAG** formatted string. +:::zone pivot="dotnet-10-0" + +```console +docker rmi counter-image:latest +docker rmi mcr.microsoft.com/dotnet/aspnet:10.0 +``` + +:::zone-end + :::zone pivot="dotnet-9-0" ```console @@ -588,6 +491,7 @@ docker rmi mcr.microsoft.com/dotnet/aspnet:9.0 ``` :::zone-end + :::zone pivot="dotnet-8-0" ```console diff --git a/docs/core/docker/snippets/8.0/App/Dockerfile b/docs/core/docker/snippets/8.0/App/Dockerfile deleted file mode 100644 index c1678c5d0801a..0000000000000 --- a/docs/core/docker/snippets/8.0/App/Dockerfile +++ /dev/null @@ -1,15 +0,0 @@ -FROM mcr.microsoft.com/dotnet/sdk:8.0@sha256:35792ea4ad1db051981f62b313f1be3b46b1f45cadbaa3c288cd0d3056eefb83 AS build -WORKDIR /App - -# Copy everything -COPY . ./ -# Restore as distinct layers -RUN dotnet restore -# Build and publish a release -RUN dotnet publish -o out - -# Build runtime image -FROM mcr.microsoft.com/dotnet/aspnet:8.0@sha256:6c4df091e4e531bb93bdbfe7e7f0998e7ced344f54426b7e874116a3dc3233ff -WORKDIR /App -COPY --from=build /App/out . -ENTRYPOINT ["dotnet", "DotNet.Docker.dll"] diff --git a/docs/core/docker/snippets/8.0/App/DotNet.Docker.csproj b/docs/core/docker/snippets/8.0/App/DotNet.Docker.csproj deleted file mode 100644 index 91b464afeacc1..0000000000000 --- a/docs/core/docker/snippets/8.0/App/DotNet.Docker.csproj +++ /dev/null @@ -1,10 +0,0 @@ - - - - Exe - net8.0 - enable - enable - - - diff --git a/docs/core/docker/snippets/9.0/App/Program.cs b/docs/core/docker/snippets/9.0/App/Program.cs deleted file mode 100644 index 82e9ce0b61b99..0000000000000 --- a/docs/core/docker/snippets/9.0/App/Program.cs +++ /dev/null @@ -1,9 +0,0 @@ -ο»Ώvar counter = 0; -var max = args.Length is not 0 ? Convert.ToInt32(args[0]) : -1; - -while (max is -1 || counter < max) -{ - Console.WriteLine($"Counter: {++counter}"); - - await Task.Delay(TimeSpan.FromMilliseconds(1_000)); -} diff --git a/docs/core/docker/snippets/9.0/App/Dockerfile b/docs/core/docker/snippets/App/Dockerfile similarity index 100% rename from docs/core/docker/snippets/9.0/App/Dockerfile rename to docs/core/docker/snippets/App/Dockerfile diff --git a/docs/core/docker/snippets/9.0/App/DotNet.Docker.csproj b/docs/core/docker/snippets/App/DotNet.Docker.csproj similarity index 100% rename from docs/core/docker/snippets/9.0/App/DotNet.Docker.csproj rename to docs/core/docker/snippets/App/DotNet.Docker.csproj diff --git a/docs/core/docker/snippets/8.0/App/Program.cs b/docs/core/docker/snippets/App/Program.cs similarity index 100% rename from docs/core/docker/snippets/8.0/App/Program.cs rename to docs/core/docker/snippets/App/Program.cs diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index bfd6287616ac5..05891bcc558ff 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -33,12 +33,12 @@ By default, .NET is installed to the _Program Files\\dotnet_ directory on your c There are three different runtimes for Windows, which enable different types of apps to run. The SDK includes all three runtimes, and an installer for a runtime might include an additional runtime. The following table describes which runtime is included with a particular .NET installer: -| Installer | Includes .NET Runtime | Includes .NET Desktop Runtime | Includes ASP.NET Core Runtime | -| ------------------------ | ----------------------------- | ----------------------------- | ----------------------------- | -| **.NET Runtime** | Yes | No | No | -| **.NET Desktop Runtime** | Yes | Yes | No | -| **ASP.NET Core Runtime** | No | No | Yes | -| **.NET SDK** | Yes | Yes | Yes | +| Installer | Includes .NET Runtime | Includes .NET Desktop Runtime | Includes ASP.NET Core Runtime | +|--------------------------|-----------------------|-------------------------------|-------------------------------| +| **.NET Runtime** | Yes | No | No | +| **.NET Desktop Runtime** | Yes | Yes | No | +| **ASP.NET Core Runtime** | No | No | Yes | +| **.NET SDK** | Yes | Yes | Yes | To ensure that you can run all .NET apps on Windows, install both the ASP.NET Core Runtime and the .NET Desktop Runtime. The ASP.NET Core Runtime runs web-based apps, and the .NET Desktop Runtime runs desktop apps, such as a Windows Presentation Foundation (WPF) or Windows Forms app. @@ -58,7 +58,7 @@ If you're unsure which method you should choose after reviewing the lists in the Install the **C# Dev Kit** extension for Visual Studio Code to develop .NET apps. The extension can use an SDK that's already installed or install one for you. -### Users and Developers +### Users and developers - [.NET Installer](#net-installer) @@ -77,19 +77,19 @@ If you're unsure which method you should choose after reviewing the lists in the The following table is a list of currently supported .NET releases and the versions of Windows they're supported on. These versions remain supported until either the version of [.NET reaches end-of-support](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) or the version of [Windows reaches end-of-life](https://support.microsoft.com/help/13853/windows-lifecycle-fact-sheet). > [!TIP] -> As a reminder, this table applies to modern .NET (as opposed to .NET Framework). To install .NET Framework, see the [.NET Framework Installation guide](../../framework/install/index.md). +> As a reminder, this table applies to modern .NET (as opposed to .NET Framework). To install .NET Framework, see the [.NET Framework installation guide](../../framework/install/index.md). Windows 10 versions end-of-service dates are segmented by edition. Only **Home**, **Pro**, **Pro Education**, and **Pro for Workstations** editions are considered in the following table. Check the [Windows lifecycle fact sheet](https://support.microsoft.com/help/13853/windows-lifecycle-fact-sheet) for specific details. -| Operating System | .NET 9 (Architectures) | .NET 8 (Architectures) | -|---------------------------------------|------------------------|------------------------| -| Windows 11 (24H2, 23H2, 22H2 Ent/Edu) | βœ”οΈ x64, x86, Arm64 | βœ”οΈ x64, x86, Arm64 | -| Windows 10 (22H2+) | βœ”οΈ x64, x86, Arm64 | βœ”οΈ x64, x86, Arm64 | -| Windows Server 2025
Windows Server 2022
Windows Server 2019
Windows Server, Version 1903 or later
Windows Server 2016
Windows Server 2012 R2
Windows Server 2012 | βœ”οΈ x64, x86 | βœ”οΈ x64, x86 | -| Windows Server Core 2012 (and R2) | βœ”οΈ x64, x86 | βœ”οΈ x64, x86 | -| Nano Server (2022, 2019) | βœ”οΈ x64 | βœ”οΈ x64 | -| Windows 8.1 | ❌ | ❌ | -| Windows 7 SP1 [ESU][esu] | ❌ | ❌ | +| Operating System | .NET 10 (Architectures) | .NET 9 (Architectures) | .NET 8 (Architectures) | +|---------------------------------------|--------------------------|------------------------|------------------------| +| Windows 11
(25H2, 24H2, 23H2, 22H2 Ent/Edu) | βœ”οΈ x64, x86, Arm64 | βœ”οΈ x64, x86, Arm64 | βœ”οΈ x64, x86, Arm64 | +| Windows 10 (22H2+) | βœ”οΈ x64, x86, Arm64 | βœ”οΈ x64, x86, Arm64 | βœ”οΈ x64, x86, Arm64 | +| Windows Server 2025
Windows Server 2022
Windows Server 2019
Windows Server, Version 1903 or later
Windows Server 2016
Windows Server 2012 R2
Windows Server 2012 | βœ”οΈ x64, x86 | βœ”οΈ x64, x86 | βœ”οΈ x64, x86 | +| Windows Server Core 2012 (and R2) | βœ”οΈ x64, x86 | βœ”οΈ x64, x86 | βœ”οΈ x64, x86 | +| Nano Server (2022, 2019) | βœ”οΈ x64 | βœ”οΈ x64 | βœ”οΈ x64 | +| Windows 8.1 | ❌ | ❌ | ❌ | +| Windows 7 SP1 [ESU][esu] | ❌ | ❌ | ❌ | > [!TIP] > A `+` symbol represents the minimum version. @@ -145,12 +145,13 @@ The Visual Studio documentation provides instructions on how to: :::image type="content" source="media/windows/vs-workloads.png" alt-text="A screenshot that shows Visual Studio Installer with the .NET Desktop workload highlighted with a red box."::: -### .NET Versions and Visual Studio +### .NET versions and Visual Studio If you're using Visual Studio to develop .NET apps, the following table describes the minimum required version of Visual Studio based on the target .NET SDK version. | .NET SDK version | Visual Studio version | | --------------------- | ------------------------------------------- | +| 10 | Visual Studio 2026 version 18.0 or higher. | | 9 | Visual Studio 2022 version 17.12 or higher. | | 8 | Visual Studio 2022 version 17.8 or higher. | | 7 | Visual Studio 2022 version 17.4 or higher. | @@ -186,7 +187,7 @@ Additionally, the [C# Dev Kit](https://marketplace.visualstudio.com/items?itemNa For instructions on installing .NET through Visual Studio Code, see [Getting Started with C# in VS Code](https://code.visualstudio.com/docs/csharp/get-started). -## .NET Installer +## .NET installer The [download page](https://dotnet.microsoft.com/download/dotnet) for .NET provides Windows Installer executables. @@ -254,11 +255,11 @@ Check if the installations key files or components are damaged and restore them. The installer executables always install new content before removing the previous installation. Applications that are running might be interrupted or crash when older runtimes are removed. To minimize the impact of updating .NET, you can specify when a previous .NET installation should be removed using a registry key. -| .NET version | Registry key | Name | Type | Value | -| -------------- | :--------- | :---------- | :---------- | :---------- | -| All | HKLM\SOFTWARE\Microsoft\\.NET | RemovePreviousVersion | REG_SZ | `always`, `never`, or `nextSession` | -| .NET 9 | HKLM\SOFTWARE\Microsoft\\.NET\9.0 | RemovePreviousVersion | REG_SZ | `always`, `never`, or `nextSession` | -| .NET 8 | HKLM\SOFTWARE\Microsoft\\.NET\8.0 | RemovePreviousVersion | REG_SZ | `always`, `never`, or `nextSession` | +| .NET version | Registry key | Name | Type | Value | +|--------------|:----------------------------------|:----------------------|:-------|:------------------------------------| +| All | HKLM\SOFTWARE\Microsoft\\.NET | RemovePreviousVersion | REG_SZ | `always`, `never`, or `nextSession` | +| .NET 9 | HKLM\SOFTWARE\Microsoft\\.NET\9.0 | RemovePreviousVersion | REG_SZ | `always`, `never`, or `nextSession` | +| .NET 8 | HKLM\SOFTWARE\Microsoft\\.NET\8.0 | RemovePreviousVersion | REG_SZ | `always`, `never`, or `nextSession` | - `never` retains previous installations and requires manual intervention to remove previous .NET installations. - `always` removes previous installations after the new version is installed. This is the default behavior in .NET. diff --git a/docs/core/porting/versioning-sdk-msbuild-vs.md b/docs/core/porting/versioning-sdk-msbuild-vs.md index dbd6a37cb8c38..1ae0c7687ed82 100644 --- a/docs/core/porting/versioning-sdk-msbuild-vs.md +++ b/docs/core/porting/versioning-sdk-msbuild-vs.md @@ -2,7 +2,6 @@ title: .NET SDK, MSBuild, and Visual Studio versioning description: Learn about the versioning relationship between the .NET SDK and MSBuild/VS. author: StephenBonikowsky -ms.author: stebon ms.custom: updateeachrelease ms.date: 10/23/2025 --- diff --git a/docs/core/project-sdk/msbuild-props-desktop.md b/docs/core/project-sdk/msbuild-props-desktop.md index 19df71fe63a4e..a36297b161267 100644 --- a/docs/core/project-sdk/msbuild-props-desktop.md +++ b/docs/core/project-sdk/msbuild-props-desktop.md @@ -20,7 +20,7 @@ This page is a reference for the MSBuild properties and items that you use to co To use WinForms or WPF, specify the following settings in the project file of your WinForms or WPF project: - Target the .NET SDK `Microsoft.NET.Sdk`. For more information, see [Project files](overview.md#project-files). -- Set [`TargetFramework`](msbuild-props.md#targetframework) to a [Windows-specific target framework moniker](../../standard/frameworks.md#net-5-os-specific-tfms), such as `net8.0-windows`. +- Set [`TargetFramework`](msbuild-props.md#targetframework) to a [Windows-specific target framework moniker](../../standard/frameworks.md#os-specific-tfms), such as `net8.0-windows`. - Add a UI framework property (or both, if necessary): - Set [`UseWPF`](#usewpf) to `true` to import and use WPF. - Set [`UseWindowsForms`](#usewindowsforms) to `true` to import and use WinForms. diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index dd8f1a3198b2d..cf224ef7b6f1c 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -169,8 +169,7 @@ The `PackRelease` property is similar to the [PublishRelease](#publishrelease) p > [!NOTE] > -> - Starting in the .NET 8 SDK, `PackRelease` defaults to `true`. For more information, see ['dotnet pack' uses Release configuration](../compatibility/sdk/8.0/dotnet-pack-config.md). -> - .NET 7 SDK only: To use `PackRelease` in a project that's part of a Visual Studio solution, you must set the environment variable `DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS` to `true` (or any other value). For solutions that have many projects, setting this variable increases the time required to pack. +> Starting in the .NET 8 SDK, `PackRelease` defaults to `true`. For more information, see ['dotnet pack' uses Release configuration](../compatibility/sdk/8.0/dotnet-pack-config.md). ## Package validation properties @@ -345,7 +344,7 @@ The `PackageValidationReferencePath` item specifies the directory path where the ```xml - + ``` @@ -541,8 +540,7 @@ The `PublishRelease` property informs `dotnet publish` to use the `Release` conf > [!NOTE] > > - Starting in the .NET 8 SDK, `PublishRelease` defaults to `true` for projects that target .NET 8 or later. For more information, see ['dotnet publish' uses Release configuration](../compatibility/sdk/8.0/dotnet-publish-config.md). -> - This property does not affect the behavior of `dotnet build /t:Publish`, and it only changes the configuration only when publishing via the .NET CLI. -> - .NET 7 SDK only: To use `PublishRelease` in a project that's part of a Visual Studio solution, you must set the environment variable `DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS` to `true` (or any other value). When publishing a solution with this variable enabled, the executable project's `PublishRelease` value takes precedence and flows the new default configuration to any other projects in the solution. If a solution contains multiple executable or top-level projects with differing values of `PublishRelease`, the solution won't successfully publish. For solutions that have many projects, use of this setting increases the time required to publish. +> - This property does not affect the behavior of `dotnet build /t:Publish`, and it changes the configuration only when publishing via the .NET CLI. ### PublishSelfContained @@ -734,7 +732,7 @@ Additionally, if you specify an operating system-specific target framework in th - Platform with version (`IOS15_1`) - Platform with version minimum bound (`IOS15_1_OR_GREATER`) -For more information on operating system-specific target framework monikers, see [OS-specific TFMs](../../standard/frameworks.md#net-5-os-specific-tfms). +For more information on operating system-specific target framework monikers, see [OS-specific TFMs](../../standard/frameworks.md#os-specific-tfms). Finally, if your target framework implies support for older target frameworks, preprocessor symbols for those older frameworks are emitted. For example, `net6.0` **implies** support for `net5.0` and so on all the way back to `.netcoreapp1.0`. So for each of these target frameworks, the *Framework with version minimum bound* symbol will be defined. @@ -977,6 +975,10 @@ The following table shows the values you can specify. | `latest-` | The latest code analyzers that have been released are used. The `` value determines which rules are enabled. | | `preview` | The latest code analyzers are used, even if they are in preview. | | `preview-` | The latest code analyzers are used, even if they are in preview. The `` value determines which rules are enabled. | +| `10.0` | The set of rules that was available for the .NET 10 release is used, even if newer rules are available. | +| `10.0-` | The set of rules that was available for the .NET 10 release is used, even if newer rules are available. The `` value determines which rules are enabled. | +| `10` | The set of rules that was available for the .NET 10 release is used, even if newer rules are available. | +| `10-` | The set of rules that was available for the .NET 10 release is used, even if newer rules are available. The `` value determines which rules are enabled. | | `9.0` | The set of rules that was available for the .NET 9 release is used, even if newer rules are available. | | `9.0-` | The set of rules that was available for the .NET 9 release is used, even if newer rules are available. The `` value determines which rules are enabled. | | `9` | The set of rules that was available for the .NET 9 release is used, even if newer rules are available. | @@ -985,10 +987,6 @@ The following table shows the values you can specify. | `8.0-` | The set of rules that was available for the .NET 8 release is used, even if newer rules are available. The `` value determines which rules are enabled. | | `8` | The set of rules that was available for the .NET 8 release is used, even if newer rules are available. | | `8-` | The set of rules that was available for the .NET 8 release is used, even if newer rules are available. The `` value determines which rules are enabled. | -| `7.0` | The set of rules that was available for the .NET 7 release is used, even if newer rules are available. | -| `7.0-` | The set of rules that was available for the .NET 7 release is used, even if newer rules are available. The `` value determines which rules are enabled. | -| `7` | The set of rules that was available for the .NET 7 release is used, even if newer rules are available. | -| `7-` | The set of rules that was available for the .NET 7 release is used, even if newer rules are available. The `` value determines which rules are enabled. | > [!NOTE] > @@ -1347,7 +1345,7 @@ Example *Directory.Packages.props* file: ... - + ``` diff --git a/docs/core/whats-new/dotnet-6.md b/docs/core/whats-new/dotnet-6.md index c4f4d16c47a25..e734f27d07700 100644 --- a/docs/core/whats-new/dotnet-6.md +++ b/docs/core/whats-new/dotnet-6.md @@ -205,7 +205,7 @@ The *source tarball*, which contains all the source for the .NET SDK, is now a p ## Target framework monikers -Additional OS-specific target framework monikers (TFMs) have been added for .NET 6, for example, `net6.0-android`, `net6.0-ios`, and `net6.0-macos`. For more information, see [.NET 5+ OS-specific TFMs](../../standard/frameworks.md#net-5-os-specific-tfms). +Additional OS-specific target framework monikers (TFMs) have been added for .NET 6, for example, `net6.0-android`, `net6.0-ios`, and `net6.0-macos`. For more information, see [OS-specific TFMs](../../standard/frameworks.md#os-specific-tfms). ## Generic math diff --git a/docs/framework/install/on-windows-and-server.md b/docs/framework/install/on-windows-and-server.md index 8f15584e90d63..2b544b59a892c 100644 --- a/docs/framework/install/on-windows-and-server.md +++ b/docs/framework/install/on-windows-and-server.md @@ -1,7 +1,7 @@ --- title: Install .NET Framework on Windows description: Learn how to install .NET Framework on Windows 11, Windows 10, and Windows Server. This article also includes information about .NET Framework and unsupported versions of Windows, such as Windows 8, Windows Vista, and Windows XP. -ms.date: 07/10/2025 +ms.date: 11/06/2025 --- # Install .NET Framework on Windows and Windows Server @@ -52,6 +52,7 @@ In the following table, ❌ represents an unsupported version of Windows 11 and | Windows 11 version | .NET Framework included | Latest .NET Framework supported | |-----------------------|-------------------------|---------------------------------| +| βœ”οΈ 25H2 (September 2025) | 4.8.1 | 4.8.1 | | βœ”οΈ 24H2 (October 2024) | 4.8.1 | 4.8.1 | | βœ”οΈ 23H2 (October 2023) | 4.8.1 | 4.8.1 | | ❌ 22H2 (September 2022) | 4.8.1 | 4.8.1 | diff --git a/docs/framework/install/versions-and-dependencies.md b/docs/framework/install/versions-and-dependencies.md index c05ab60e7958b..403922b7557eb 100644 --- a/docs/framework/install/versions-and-dependencies.md +++ b/docs/framework/install/versions-and-dependencies.md @@ -58,7 +58,7 @@ Jump to: | | Versions | |--------------------|-----------------------| | **CLR** | 4 | -| **Windows** | βœ”οΈ 11 version 24H2 (version 26100)
βœ”οΈ 11 October 2023 Release (version 22631)
βœ”οΈ 11 September 2022 Release (version 22621)
βž• 11 October 2021 Release (version 22000)
βž• 10 October 2022 Update (22H2)
βž• 10 November 2021 Update
βž• 10 May 2021 Update
βž• 10 October 2020 Update
| +| **Windows** | βœ”οΈ 11 September 2025 Release (version 26200)
βœ”οΈ 11 October 2024 Release (version 26100)
βœ”οΈ 11 October 2023 Release (version 22631)
βœ”οΈ 11 September 2022 Release (version 22621)
βž• 11 October 2021 Release (version 22000)
βž• 10 October 2022 Update (22H2)
βž• 10 November 2021 Update
βž• 10 May 2021 Update
βž• 10 October 2020 Update
| | **Windows Server** | βœ”οΈ Windows Server 2025
βž• Windows Server 2022 | To determine the installed .NET version, use the following `Release` DWORD: diff --git a/docs/fsharp/index.yml b/docs/fsharp/index.yml index 8480d506db697..3a41fcd37475e 100644 --- a/docs/fsharp/index.yml +++ b/docs/fsharp/index.yml @@ -53,7 +53,7 @@ landingContent: - text: "F# library reference" url: https://fsharp.github.io/fsharp-core-docs - text: ".NET library reference" - url: ../../api/index.md?view=net-9.0 + url: ../../api/index.md - title: "F# fundamentals" linkLists: diff --git a/docs/index.yml b/docs/index.yml index 8a30b9bde4abf..8298d176467e7 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -357,11 +357,11 @@ additionalContent: # Card - title: ".NET API reference" summary: API reference documentation for .NET - url: ../api/index.md?view=net-9.0 + url: ../api/index.md?view=net-10.0 # Card - title: "ASP.NET Core API reference" summary: API reference documentation for ASP.NET Core - url: ../api/index.md?view=view=aspnetcore-9.0&preserve-view=true + url: ../api/index.md?view=aspnetcore-10.0&preserve-view=true # Card - title: "C# language reference" summary: C# language reference and specification diff --git a/docs/standard/analyzers/platform-compat-analyzer.md b/docs/standard/analyzers/platform-compat-analyzer.md index 3c4c71d622776..875bba35e5625 100644 --- a/docs/standard/analyzers/platform-compat-analyzer.md +++ b/docs/standard/analyzers/platform-compat-analyzer.md @@ -7,9 +7,9 @@ ms.date: 09/20/2021 # Platform compatibility analyzer -You've probably heard the motto of "One .NET": a single, unified platform for building any type of application. The .NET SDK includes ASP.NET Core, Entity Framework Core, Windows Forms, WPF, and ML.NET, and will add support for more platforms over time. .NET 5+ strives to provide an experience where you don't have to reason about the different flavors of .NET, but doesn't attempt to fully abstract away the underlying operating system (OS). You'll continue to be able to call platform-specific APIs, for example, P/Invokes and WinRT. +.NET is a single, unified platform for building any type of application. It strives to provide an experience where you don't have to reason about the different flavors of .NET, but doesn't attempt to fully abstract away the underlying operating system (OS). You can continue to call platform-specific APIs, for example, P/Invokes and WinRT. -But using platform-specific APIs on a component means the code no longer works across all platforms. We needed a way to detect this at design time so developers get diagnostics when they inadvertently use platform-specific APIs. To achieve this goal, .NET 5 introduced the [platform compatibility analyzer](../../fundamentals/code-analysis/quality-rules/ca1416.md) and complementary APIs to help developers identify and use platform-specific APIs where appropriate. +But using platform-specific APIs on a component means the code no longer works across all platforms. The [platform compatibility analyzer](../../fundamentals/code-analysis/quality-rules/ca1416.md) and complementary APIs provide diagnostics to help you identify and use platform-specific APIs where appropriate. The complementary APIs include: diff --git a/docs/standard/frameworks.md b/docs/standard/frameworks.md index 210d067106a5f..c6fcc14740dd9 100644 --- a/docs/standard/frameworks.md +++ b/docs/standard/frameworks.md @@ -1,7 +1,7 @@ --- title: Target frameworks in SDK-style projects - .NET description: Learn about target frameworks for .NET apps and libraries. -ms.date: 04/07/2025 +ms.date: 11/06/2025 ms.service: dotnet ms.custom: updateeachrelease ms.subservice: standard-library @@ -26,6 +26,7 @@ The following table defines the most common target frameworks, how they're refer | Target framework | Latest
stable version | Target framework moniker (TFM) | Implemented
.NET Standard version | |:----------------:|:---------------------------:|:------------------------------:|:---------------------------------------:| +| .NET 10 | 10 | net10.0 | 2.1 | | .NET 9 | 9 | net9.0 | 2.1 | | .NET 8 | 8 | net8.0 | 2.1 | | .NET Standard | 2.1 | netstandard2.1 | N/A | @@ -38,7 +39,7 @@ A target framework is typically referenced by a TFM. The following table shows t | Target Framework | TFM | | -------------------------- | --- | -| .NET 5+ (and .NET Core) | netcoreapp1.0
netcoreapp1.1
netcoreapp2.0
netcoreapp2.1
netcoreapp2.2
netcoreapp3.0
netcoreapp3.1
net5.0*
net6.0*
net7.0*
net8.0*
net9.0* | +| .NET 5+ (and .NET Core) | netcoreapp1.0
netcoreapp1.1
netcoreapp2.0
netcoreapp2.1
netcoreapp2.2
netcoreapp3.0
netcoreapp3.1
net5.0*
net6.0*
net7.0*
net8.0*
net9.0*
net10.0* | | .NET Standard | netstandard1.0
netstandard1.1
netstandard1.2
netstandard1.3
netstandard1.4
netstandard1.5
netstandard1.6
netstandard2.0
netstandard2.1 | | .NET Framework | net11
net20
net35
net40
net403
net45
net451
net452
net46
net461
net462
net47
net471
net472
net48
net481 | | Windows Store | netcore [netcore45]
netcore45 [win] [win8]
netcore451 [win81] | @@ -48,35 +49,16 @@ A target framework is typically referenced by a TFM. The following table shows t | Windows Phone | wp [wp7]
wp7
wp75
wp8
wp81
wpa81 | | Universal Windows Platform | uap [uap10.0]
uap10.0 [win10] [netcore50] | -\* .NET 5 and later TFMs include some operating system-specific variations. For more information, see the following section, [.NET 5+ OS-specific TFMs](#net-5-os-specific-tfms). +\* .NET 5 and later TFMs include some operating system-specific variations. For more information, see the following section, [OS-specific TFMs](#os-specific-tfms). -### .NET 5+ OS-specific TFMs +### OS-specific TFMs -The `net5.0`, `net6.0`, `net7.0`, `net8.0`, and `net9.0` TFMs include technologies that work across different platforms. Specifying an *OS-specific TFM* makes APIs that are specific to an operating system available to your app, for example, Windows Forms or iOS bindings. OS-specific TFMs also inherit every API available to their base TFM, for example, the `net9.0` TFM. +The `net8.0`, `net9.0`, and `net10.0` TFMs include technologies that work across different platforms. Specifying an *OS-specific TFM* makes APIs that are specific to an operating system available to your app, for example, Windows Forms or iOS bindings. OS-specific TFMs also inherit every API available to their base TFM, for example, the `net10.0` TFM. -.NET 5 introduced the `net5.0-windows` OS-specific TFM, which includes Windows-specific bindings for WinForms, WPF, and UWP APIs. .NET 6 and later versions have additional OS-specific TFMs, for example, `net6.0-ios`. - -The following table shows the compatibility of the .NET 5+ TFMs. +The following table shows the compatibility of the .NET 8+ TFMs. | TFM | Compatible with | |----------------------|------------------------------------------------------------------| -| `net5.0` | net1..4 (with NU1701 warning)
netcoreapp1..3.1 (warning when WinForms or WPF is referenced)
netstandard1..2.1 | -| `net5.0-windows` | netcoreapp1..3.1 (plus everything else inherited from `net5.0`) | -| `net6.0` | (Subsequent version of `net5.0`) | -| `net6.0-android` | `xamarin.android` (plus everything else inherited from `net6.0`) | -| `net6.0-ios` | Everything inherited from `net6.0` | -| `net6.0-maccatalyst` | Everything inherited from `net6.0` | -| `net6.0-macos` | Everything inherited from `net6.0` | -| `net6.0-tvos` | Everything inherited from `net6.0` | -| `net6.0-windows` | (Subsequent version of `net5.0-windows`) | -| `net7.0` | (Subsequent version of `net6.0`) | -| `net7.0-android` | (Subsequent version of `net6.0-android`) | -| `net7.0-ios` | (Subsequent version of `net6.0-ios`) | -| `net7.0-maccatalyst` | (Subsequent version of `net6.0-maccatalyst`) | -| `net7.0-macos` | (Subsequent version of `net6.0-macos`) | -| `net7.0-tizen` | `tizen40` (plus everything else inherited from `net7.0`) | -| `net7.0-tvos` | (Subsequent version of `net6.0-tvos`) | -| `net7.0-windows` | (Subsequent version of `net6.0-windows`) | | `net8.0` | (Subsequent version of `net7.0`) | | `net8.0-android` | (Subsequent version of `net7.0-android`) | | `net8.0-browser` | Everything inherited from `net8.0` | @@ -95,6 +77,15 @@ The following table shows the compatibility of the .NET 5+ TFMs. | `net9.0-tizen` | (Subsequent version of `net8.0-tizen`) | | `net9.0-tvos` | (Subsequent version of `net8.0-tvos`) | | `net9.0-windows` | (Subsequent version of `net8.0-windows`) | +| `net10.0` | (Subsequent version of `net9.0`) | +| `net10.0-android` | (Subsequent version of `net9.0-android`) | +| `net10.0-browser` | (Subsequent version of `net9.0-browser`) | +| `net10.0-ios` | (Subsequent version of `net9.0-ios`) | +| `net10.0-maccatalyst` | (Subsequent version of `net9.0-maccatalyst`) | +| `net10.0-macos` | (Subsequent version of `net9.0-macos`) | +| `net10.0-tizen` | (Subsequent version of `net9.0-tizen`) | +| `net10.0-tvos` | (Subsequent version of `net9.0-tvos`) | +| `net10.0-windows` | (Subsequent version of `net9.0-windows`) | To make your app portable across different platforms but still have access to OS-specific APIs, you can target multiple OS-specific TFMs and add platform guards around OS-specific API calls using `#if` preprocessor directives. For a list of the available symbols, see [Preprocessor symbols](#preprocessor-symbols). @@ -102,24 +93,25 @@ To make your app portable across different platforms but still have access to OS Use these guidelines to determine which TFM to use in your app: -- Apps that are portable to multiple platforms should target a base TFM, for example, `net9.0`. This includes most libraries but also ASP.NET Core and Entity Framework. -- Platform-specific libraries should target platform-specific flavors. For example, WinForms and WPF projects should target `net9.0-windows`. -- Cross-platform application models (for example, ASP.NET Core) should at least target the base TFM, for example, `net9.0`, but might also target additional platform-specific flavors to light-up more APIs or features. +- Apps that are portable to multiple platforms should target a base TFM, for example, `net10.0`. This includes most libraries but also ASP.NET Core and Entity Framework. +- Platform-specific libraries should target platform-specific flavors. For example, WinForms and WPF projects should target `net10.0-windows`. +- Cross-platform application models (for example, ASP.NET Core) should at least target the base TFM, for example, `net10.0`, but might also target additional platform-specific flavors to light-up more APIs or features. #### OS version in TFMs -You can also specify an optional OS version at the end of an OS-specific TFM, for example, `net6.0-ios15.0`. The version indicates which APIs are available to your app or library. It doesn't control the OS version that your app or library supports at run time. It's used to select the reference assemblies that your project compiles against, and to select assets from NuGet packages. Think of this version as the "platform version" or "OS API version" to disambiguate it from the run-time OS version. +You can also specify an optional OS version at the end of an OS-specific TFM, for example, `net8.0-ios17.2`. The version indicates which APIs are available to your app or library. It doesn't control the OS version that your app or library supports at run time. It's used to select the reference assemblies that your project compiles against, and to select assets from NuGet packages. Think of this version as the "platform version" or "OS API version" to disambiguate it from the run-time OS version. -The .NET SDK is designed to be able to support newly released APIs for an individual platform without a new version of the base TFM. This enables you to access platform-specific functionality without waiting for a major release of .NET. You can gain access to these newly released APIs by incrementing the platform version in the TFM. For example, if the Android platform added API level 32 APIs in a .NET 6.0.x SDK update, you could access them by using the TFM `net6.0-android32.0`. +The .NET SDK is designed to be able to support newly released APIs for an individual platform without a new version of the base TFM. This enables you to access platform-specific functionality without waiting for a major release of .NET. You can gain access to these newly released APIs by incrementing the platform version in the TFM. For example, if the Android platform added API level 34 APIs in a .NET 8.0.x SDK update, you could access them by using the TFM `net8.0-android34.0`. -When an OS-specific TFM doesn't specify the platform version explicitly, it has an implied value that can be inferred from the base TFM and platform name. For example, the default platform version for Android in .NET 9 is `35.0`, which means that `net9.0-android` is shorthand for the canonical `netp.0-android35.0` TFM. The shorthand form is intended for use in project files only, and is expanded to the canonical form by the .NET SDK's MSBuild targets before being passed to other tools, such as NuGet. +When an OS-specific TFM doesn't specify the platform version explicitly, it has an implied value that can be inferred from the base TFM and platform name. For example, the default platform version for Android in .NET 9 is `35.0`, which means that `net9.0-android` is shorthand for the canonical `net9.0-android35.0` TFM. The shorthand form is intended for use in project files only, and is expanded to the canonical form by the .NET SDK's MSBuild targets before being passed to other tools, such as NuGet. -The following table shows the *default* target platform version (TPV) for each .NET release. **If you want to use the latest bindings, use the default (that is, don't specify an OS version).** +The following table shows the *default* target platform version (TPV) for Android and iOS for each .NET release. **If you want to use the latest bindings, use the default (that is, don't specify an OS version).** -| .NET version | Android | iOS | Mac Catalyst | macOS | tvOS | Tizen | Windows | -|--------------|--------:|-----:|-------------:|------:|-----:|------:|--------:| -| .NET 8 | 34.0 | 17.2 | 17.2 | 14.2 | 17.1 | 10.0 | 7.0 | -| .NET 9 | 35.0 | 18.0 | 18.0 | 15.0 | | 10.0 | 7.0 | +| .NET version | Android | iOS | +|--------------|--------:|-----:| +| .NET 8 | 34.0 | 17.2 | +| .NET 9 | 35.0 | 18.0 | +| .NET 10 | 36.0 | 18.7 | Starting in .NET 9, when service releases introduce support for a later TPV (which will always have the same *major* version number as when the .NET version was initially released), the earliest supported TPV for that .NET version will remain supported. For example, for .NET 9, the earliest supported iOS version, 18.0, will remain supported, even when a service release adds support for the latest iOS 18.x version. **If you need to use the earliest bindings for a .NET release, use a specific OS version number in your TFM.** @@ -134,7 +126,7 @@ Starting in .NET 9, when service releases introduce support for a later TPV (whi #### Precedence -If your app references a package that has multiple assets for different TFMs, the assets that are closer in version number are preferred. For example, if your app targets `net6.0-ios` and the package offers assets for `net6.0` and `net5.0-ios`, the `net6.0` assets are used. For more information, see [Precedences](https://github.com/dotnet/designs/blob/main/accepted/2020/net5/net5.md#precedences). +If your app references a package that has multiple assets for different TFMs, the assets that are closer in version number are preferred. For example, if your app targets `net9.0-ios` and the package offers assets for `net9.0` and `net8.0-ios`, the `net9.0` assets are used. For more information, see [Precedences](https://github.com/dotnet/designs/blob/main/accepted/2020/net5/net5.md#precedences). #### Support older OS versions @@ -144,7 +136,7 @@ For your app to run correctly on an older OS version, it can't call APIs that do The `SupportedOSPlatformVersion` value (whether explicit or default) is used by the [platform compatibility analyzer](analyzers/platform-compat-analyzer.md), which detects and warns about unguarded calls to newer APIs. It's burned into the project's compiled assembly as an assembly attribute, so that the platform compatibility analyzer can detect unguarded calls to that assembly's APIs from projects with a lower `SupportedOSPlatformVersion` value. On some platforms, the `SupportedOSPlatformVersion` value affects platform-specific app packaging and build processes, which is covered in the documentation for those platforms. -Here is an example excerpt of a project file that uses the `TargetFramework` and `SupportedOSPlatformVersion` MSBuild properties to specify that the app or library has access to iOS 15.0 APIs but supports running on iOS 13.0 and above: +The following example is an excerpt of a project file that uses the `TargetFramework` and `SupportedOSPlatformVersion` MSBuild properties to specify that the app or library has access to iOS 15.0 APIs but supports running on iOS 13.0 and higher: ```xml @@ -160,20 +152,20 @@ Here is an example excerpt of a project file that uses the `TargetFramework` and ## How to specify a target framework -Target frameworks are specified in a project file. When a single target framework is specified, use the [TargetFramework element](../core/project-sdk/msbuild-props.md#targetframework). The following console app project file demonstrates how to target .NET 9: +Target frameworks are specified in a project file. When a single target framework is specified, use the [TargetFramework element](../core/project-sdk/msbuild-props.md#targetframework). The following console app project file demonstrates how to target .NET 10: ```xml Exe - net9.0 + net10.0 ``` -When you specify multiple target frameworks, you may conditionally reference assemblies for each target framework. In your code, you can conditionally compile against those assemblies by using [preprocessor symbols](#preprocessor-symbols) with *if-then-else* logic. +When you specify multiple target frameworks, you can conditionally reference assemblies for each target framework. In your code, you can conditionally compile against those assemblies by using [preprocessor symbols](#preprocessor-symbols) with *if-then-else* logic. The following library project targets APIs of .NET Standard (`netstandard1.4`) and .NET Framework (`net40` and `net45`). Use the plural [TargetFrameworks element](../core/project-sdk/msbuild-props.md#targetframeworks) with multiple target frameworks. The `Condition` attributes include implementation-specific packages when the library is compiled for the two .NET Framework TFMs: @@ -218,7 +210,7 @@ public class MyClass ## Preprocessor symbols -The build system is aware of preprocessor symbols representing the target frameworks shown in the [Supported target framework versions](#supported-target-frameworks) table when you're using SDK-style projects. To convert a .NET Standard, .NET Core, or .NET 5+ TFM to a preprocessor symbol, replace dots and hyphens with an underscore, and change lowercase letters to uppercase (for example, the symbol for `netstandard1.4` is `NETSTANDARD1_4`). +The build system is aware of preprocessor symbols representing the target frameworks shown in the [Supported target framework versions](#supported-target-frameworks) table when you're using SDK-style projects. To convert a .NET Standard, .NET Core, or .NET 5+ TFM to a preprocessor symbol, replace dots and hyphens with an underscore, and change lowercase letters to uppercase (for example, the symbol for `netstandard2.0` is `NETSTANDARD2_0`). You can disable generation of these symbols via the `DisableImplicitFrameworkDefines` property. For more information about this property, see [DisableImplicitFrameworkDefines](../core/project-sdk/msbuild-props.md#disableimplicitframeworkdefines). diff --git a/docs/standard/library-guidance/cross-platform-targeting.md b/docs/standard/library-guidance/cross-platform-targeting.md index f73fd18a53bd7..50cb2593205fd 100644 --- a/docs/standard/library-guidance/cross-platform-targeting.md +++ b/docs/standard/library-guidance/cross-platform-targeting.md @@ -1,7 +1,7 @@ --- title: Cross-platform targeting for .NET libraries description: Best practice recommendations for creating cross-platform .NET libraries. -ms.date: 08/20/2025 +ms.date: 11/06/2025 --- # Cross-platform targeting diff --git a/docs/standard/net-standard.md b/docs/standard/net-standard.md index 62b43be221521..84ae857031196 100644 --- a/docs/standard/net-standard.md +++ b/docs/standard/net-standard.md @@ -1,11 +1,10 @@ --- title: .NET Standard description: Learn about .NET Standard, its versions, and the .NET implementations that support it. -ms.date: 11/11/2024 +ms.date: 11/06/2025 ms.service: dotnet ms.subservice: standard-library ms.custom: "updateeachrelease" -ms.assetid: c044882c-af15-45f2-96d1-534557a5ee9b --- # .NET Standard @@ -88,19 +87,19 @@ If you only need to consume .NET Standard 2.0 libraries in your projects, you ca ## .NET 5+ and .NET Standard -.NET 5, .NET 6, .NET 7, .NET 8, and .NET 9 are single products with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. The .NET 9 [TFMs](frameworks.md), for example, reflect this broad range of scenarios: +.NET 5, .NET 6, .NET 7, .NET 8, .NET 9, and .NET 10 are single products with a uniform set of capabilities and APIs that can be used for Windows desktop apps and cross-platform console apps, cloud services, and websites. The .NET 10 [TFMs](frameworks.md), for example, reflect this broad range of scenarios: -- `net9.0` +- `net10.0` - This TFM is for code that runs everywhere. With a few exceptions, it includes only technologies that work cross-platform. For .NET 9 code, `net9.0` replaces both `netcoreapp` and `netstandard` TFMs. + This TFM is for code that runs everywhere. With a few exceptions, it includes only technologies that work cross-platform. -- `net9.0-windows` +- `net10.0-windows` - This is an example of an [OS-specific TFM](frameworks.md#net-5-os-specific-tfms) that adds OS-specific functionality to everything that `net9.0` refers to. + This is an example of an [OS-specific TFM](frameworks.md#os-specific-tfms) that adds OS-specific functionality to everything that `net10.0` refers to. ### When to target `netx.0` vs. `netstandard` -For existing code that targets .NET Standard 2.0 or later, there's no need to change the TFM to `net8.0` or a later TFM. .NET 8 and .NET 9 implement .NET Standard 2.1 and earlier. The only reason to retarget from .NET Standard to .NET 8+ would be to gain access to more runtime features, language features, or APIs. For example, to use C# 9, you need to target .NET 5 or a later version. You can multitarget .NET and .NET Standard to get access to newer features and still have your library available to other .NET implementations. +For existing code that targets .NET Standard 2.0 or later, there's no need to change the TFM to `net8.0` or a later TFM. .NET 8, .NET 9, and .NET 10 implement .NET Standard 2.1 and earlier. The only reason to retarget from .NET Standard to .NET 8+ would be to gain access to more runtime features, language features, or APIs. For example, to use C# 9, you need to target .NET 5 or a later version. You can multitarget .NET and .NET Standard to get access to newer features and still have your library available to other .NET implementations. > [!NOTE] > If your project targets .NET Standard 1.x, we recommend you retarget it to .NET Standard 2.0 or .NET 8+. For more information, see [Warning emitted for .NET Standard 1.x targets](../core/compatibility/sdk/9.0/netstandard-warning.md). @@ -109,13 +108,13 @@ Here are some guidelines for new code for .NET 5+: - App components - If you're using libraries to break down an application into several components, we recommend you target `net9.0`. For simplicity, it's best to keep all projects that make up your application on the same version of .NET. Then you can assume the same BCL features everywhere. + If you're using libraries to break down an application into several components, we recommend you target `net10.0`. For simplicity, it's best to keep all projects that make up your application on the same version of .NET. Then you can assume the same BCL features everywhere. - Reusable libraries If you're building reusable libraries that you plan to ship on NuGet, consider the trade-off between reach and available feature set. .NET Standard 2.0 is the latest version that's supported by .NET Framework, so it gives good reach with a fairly large feature set. We don't recommend targeting .NET Standard 1.x, as you'd limit the available feature set for a minimal increase in reach. - If you don't need to support .NET Framework, you could target .NET Standard 2.1 or .NET 9. We recommend you skip .NET Standard 2.1 and go straight to .NET 9. Most widely used libraries multi-target for both .NET Standard 2.0 and .NET 5+. Supporting .NET Standard 2.0 gives you the most reach, while supporting .NET 5+ ensures you can leverage the latest platform features for customers that are already on .NET 5+. + If you don't need to support .NET Framework, you could target .NET Standard 2.1 or .NET 10. We recommend you skip .NET Standard 2.1 and go straight to .NET 10. Most widely used libraries multi-target for both .NET Standard 2.0 and .NET 5+. Supporting .NET Standard 2.0 gives you the most reach, while supporting .NET 5+ ensures you can leverage the latest platform features for customers that are already on .NET 5+. ### .NET Standard problems @@ -131,7 +130,7 @@ Here are some problems with .NET Standard that help explain why .NET 5 and later The separation of the API specification from its implementations results in complex mapping between API specification versions and implementation versions. This complexity is evident in the table shown earlier in this article and the instructions for how to interpret it. - **Solution in .NET 5+:** There's no separation between a .NET 5+ API specification and its implementation. The result is a simplified TFM scheme. There's one TFM prefix for all workloads: `net9.0` is used for libraries, console apps, and web apps. The only variation is a [suffix that specifies platform-specific APIs](frameworks.md#net-5-os-specific-tfms) for a particular platform, such as `net9.0-windows`. Thanks to this TFM naming convention, you can easily tell whether a given app can use a given library. No version number equivalents table, like the one for .NET Standard, is needed. + **Solution in .NET 5+:** There's no separation between a .NET 5+ API specification and its implementation. The result is a simplified TFM scheme. There's one TFM prefix for all workloads: `net10.0` is used for libraries, console apps, and web apps. The only variation is a [suffix that specifies platform-specific APIs](frameworks.md#os-specific-tfms) for a particular platform, such as `net10.0-windows`. Thanks to this TFM naming convention, you can easily tell whether a given app can use a given library. No version number equivalents table, like the one for .NET Standard, is needed. - Platform-unsupported exceptions at run time diff --git a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md index cadca3a4c1e25..88cfbfa949b82 100644 --- a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md +++ b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md @@ -581,7 +581,7 @@ If you need to continue to use `Newtonsoft.Json` for certain target frameworks, ### Customize JSON format -::: zone pivot="dotnet-9-0" +::: zone pivot="dotnet-10-0,dotnet-9-0" `JsonTextWriter` includes the following settings, for which has no equivalent: diff --git a/docs/zone-pivot-groups.yml b/docs/zone-pivot-groups.yml index 2e67ac2189898..f021fbcd88cc7 100644 --- a/docs/zone-pivot-groups.yml +++ b/docs/zone-pivot-groups.yml @@ -60,8 +60,10 @@ groups: title: .NET preview version prompt: Choose a .NET version pivots: + - id: dotnet-11-0 + title: .NET 11 Preview - id: dotnet-10-0 - title: .NET 10 Preview + title: .NET 10 - id: dotnet-9-0 title: .NET 9 - id: dotnet-8-0 @@ -70,6 +72,8 @@ groups: title: .NET version prompt: Choose a .NET version pivots: + - id: dotnet-10-0 + title: .NET 10 - id: dotnet-9-0 title: .NET 9 - id: dotnet-8-0 diff --git a/includes/net-standard-1.0.md b/includes/net-standard-1.0.md index bc0490c3ce312..928acffbfe2d4 100644 --- a/includes/net-standard-1.0.md +++ b/includes/net-standard-1.0.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | | -------------------------- | ------------------------------------------------------------------- | -| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework | 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 4.6, 5.4, 6.4 | | Xamarin.iOS | 10.0, 10.14, 12.16 | diff --git a/includes/net-standard-1.1.md b/includes/net-standard-1.1.md index 7efc732613a73..9464a9b778676 100644 --- a/includes/net-standard-1.1.md +++ b/includes/net-standard-1.1.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | |----------------------------|------------------------------------------------------------| -| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework | 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 4.6, 5.4, 6.4 | | Xamarin.iOS | 10.0, 10.14, 12.16 | diff --git a/includes/net-standard-1.2.md b/includes/net-standard-1.2.md index 760a3fb47013d..1edb9036d5211 100644 --- a/includes/net-standard-1.2.md +++ b/includes/net-standard-1.2.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | | -------------------------- | -------------------------------------------------------------- | -| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework | 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 4.6, 5.4, 6.4 | | Xamarin.iOS | 10.0, 10.14, 12.16 | diff --git a/includes/net-standard-1.3.md b/includes/net-standard-1.3.md index 787006d0f14c9..e22561fc6987e 100644 --- a/includes/net-standard-1.3.md +++ b/includes/net-standard-1.3.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | |----------------------------|------------------------------------------------------------| -| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework | 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 4.6, 5.4, 6.4 | | Xamarin.iOS | 10.0, 10.14, 12.16 | diff --git a/includes/net-standard-1.4.md b/includes/net-standard-1.4.md index 79da9c6f80a7b..d77801e8144fb 100644 --- a/includes/net-standard-1.4.md +++ b/includes/net-standard-1.4.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | |----------------------------|------------------------------------------------------------| -| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework | 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 4.6, 5.4, 6.4 | | Xamarin.iOS | 10.0, 10.14, 12.16 | diff --git a/includes/net-standard-1.5.md b/includes/net-standard-1.5.md index 2fae7fa398f62..84003bc0e5cd4 100644 --- a/includes/net-standard-1.5.md +++ b/includes/net-standard-1.5.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | |-----------------------------|------------------------------------------------------------| -| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework 1 | 4.6.1 2, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 4.6, 5.4, 6.4 | | Xamarin.iOS | 10.0, 10.14, 12.16 | diff --git a/includes/net-standard-1.6.md b/includes/net-standard-1.6.md index 31bc52103602a..03dcd4995df94 100644 --- a/includes/net-standard-1.6.md +++ b/includes/net-standard-1.6.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | |-----------------------------|------------------------------------------------------------| -| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 1.0, 1.1, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework 1 | 4.6.1 2, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 4.6, 5.4, 6.4 | | Xamarin.iOS | 10.0, 10.14, 12.16 | diff --git a/includes/net-standard-2.0.md b/includes/net-standard-2.0.md index 948c5bfbb6b1b..18ba3724ef4df 100644 --- a/includes/net-standard-2.0.md +++ b/includes/net-standard-2.0.md @@ -2,7 +2,7 @@ | .NET implementation | Version support | | --------------------------- | -------------------------------------------------------- | -| .NET and .NET Core | 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | +| .NET and .NET Core | 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | | .NET Framework 1 | 4.6.1 2, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 | | Mono | 5.4, 6.4 | | Xamarin.iOS | 10.14, 12.16 | diff --git a/includes/net-standard-2.1.md b/includes/net-standard-2.1.md index 8cd9cf4668ee6..8770325702261 100644 --- a/includes/net-standard-2.1.md +++ b/includes/net-standard-2.1.md @@ -1,15 +1,15 @@ .NET Standard 2.1 has 37,118 of the 37,118 available APIs. -| .NET implementation | Version support | -|-----------------------------|-----------------------------------| -| .NET and .NET Core | 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0 | -| .NET Framework 1 | N/A2 | -| Mono | 6.4 | -| Xamarin.iOS | 12.16 | -| Xamarin.Mac | 5.16 | -| Xamarin.Android | 10.0 | -| Universal Windows Platform | N/A3 | -| Unity | 2021.2 | +| .NET implementation | Version support | +|-----------------------------|-----------------------------------------| +| .NET and .NET Core | 3.0, 3.1, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 | +| .NET Framework 1 | N/A2 | +| Mono | 6.4 | +| Xamarin.iOS | 12.16 | +| Xamarin.Mac | 5.16 | +| Xamarin.Android | 10.0 | +| Universal Windows Platform | N/A3 | +| Unity | 2021.2 | 1 The versions listed for .NET Framework apply to .NET Core 2.0 SDK and later versions of the tooling. Older versions used a different mapping for .NET Standard 1.5 and higher. You can [download tooling for .NET Core tools for Visual Studio 2015](https://github.com/dotnet/core/blob/main/release-notes/download-archives) if you cannot upgrade to Visual Studio 2017 or a later version. diff --git a/includes/preprocessor-symbols.md b/includes/preprocessor-symbols.md index 7df83cb2fac70..f71658739a3ff 100644 --- a/includes/preprocessor-symbols.md +++ b/includes/preprocessor-symbols.md @@ -5,7 +5,7 @@ ms.custom: "updateeachrelease" | ------------------| ------- | ------------------------------------------------ | -------------------------------------------------------------------- | | .NET Framework | `NETFRAMEWORK`, `NET481`, `NET48`, `NET472`, `NET471`, `NET47`, `NET462`, `NET461`, `NET46`, `NET452`, `NET451`, `NET45`, `NET40`, `NET35`, `NET20` | `NET48_OR_GREATER`, `NET472_OR_GREATER`, `NET471_OR_GREATER`, `NET47_OR_GREATER`, `NET462_OR_GREATER`, `NET461_OR_GREATER`, `NET46_OR_GREATER`, `NET452_OR_GREATER`, `NET451_OR_GREATER`, `NET45_OR_GREATER`, `NET40_OR_GREATER`, `NET35_OR_GREATER`, `NET20_OR_GREATER` | | | .NET Standard | `NETSTANDARD`, `NETSTANDARD2_1`, `NETSTANDARD2_0`, `NETSTANDARD1_6`, `NETSTANDARD1_5`, `NETSTANDARD1_4`, `NETSTANDARD1_3`, `NETSTANDARD1_2`, `NETSTANDARD1_1`, `NETSTANDARD1_0` | `NETSTANDARD2_1_OR_GREATER`, `NETSTANDARD2_0_OR_GREATER`, `NETSTANDARD1_6_OR_GREATER`, `NETSTANDARD1_5_OR_GREATER`, `NETSTANDARD1_4_OR_GREATER`, `NETSTANDARD1_3_OR_GREATER`, `NETSTANDARD1_2_OR_GREATER`, `NETSTANDARD1_1_OR_GREATER`, `NETSTANDARD1_0_OR_GREATER` | | -| .NET 5+ (and .NET Core) | `NET`, `NET9_0`, `NET8_0`, `NET7_0`, `NET6_0`, `NET5_0`, `NETCOREAPP`, `NETCOREAPP3_1`, `NETCOREAPP3_0`, `NETCOREAPP2_2`, `NETCOREAPP2_1`, `NETCOREAPP2_0`, `NETCOREAPP1_1`, `NETCOREAPP1_0` | `NET9_0_OR_GREATER`, `NET8_0_OR_GREATER`, `NET7_0_OR_GREATER`, `NET6_0_OR_GREATER`, `NET5_0_OR_GREATER`, `NETCOREAPP3_1_OR_GREATER`, `NETCOREAPP3_0_OR_GREATER`, `NETCOREAPP2_2_OR_GREATER`, `NETCOREAPP2_1_OR_GREATER`, `NETCOREAPP2_0_OR_GREATER`, `NETCOREAPP1_1_OR_GREATER`, `NETCOREAPP1_0_OR_GREATER` | `ANDROID`, `BROWSER`, `IOS`, `MACCATALYST`, `MACOS`, `TVOS`, `WINDOWS`,
`[OS][version]` (for example `IOS15_1`),
`[OS][version]_OR_GREATER` (for example `IOS15_1_OR_GREATER`) | +| .NET 5+ (and .NET Core) | `NET`, `NET10_0`, `NET9_0`, `NET8_0`, `NET7_0`, `NET6_0`, `NET5_0`, `NETCOREAPP`, `NETCOREAPP3_1`, `NETCOREAPP3_0`, `NETCOREAPP2_2`, `NETCOREAPP2_1`, `NETCOREAPP2_0`, `NETCOREAPP1_1`, `NETCOREAPP1_0` | `NET10_0_OR_GREATER`, `NET9_0_OR_GREATER`, `NET8_0_OR_GREATER`, `NET7_0_OR_GREATER`, `NET6_0_OR_GREATER`, `NET5_0_OR_GREATER`, `NETCOREAPP3_1_OR_GREATER`, `NETCOREAPP3_0_OR_GREATER`, `NETCOREAPP2_2_OR_GREATER`, `NETCOREAPP2_1_OR_GREATER`, `NETCOREAPP2_0_OR_GREATER`, `NETCOREAPP1_1_OR_GREATER`, `NETCOREAPP1_0_OR_GREATER` | `ANDROID`, `BROWSER`, `IOS`, `MACCATALYST`, `MACOS`, `TVOS`, `WINDOWS`,
`[OS][version]` (for example `IOS15_1`),
`[OS][version]_OR_GREATER` (for example `IOS15_1_OR_GREATER`) | > [!NOTE] >