From f77e4296074ad4e32ed2d87324fd2b39b74ae146 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 2 Jul 2025 11:42:06 -0700 Subject: [PATCH 01/29] Temp --- docs/core/deploying/index.md | 37 ++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 076198a311ece..46642173b6f84 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -1,35 +1,44 @@ --- title: Application publishing description: Learn about the ways to publish a .NET application. .NET can publish platform-specific or cross-platform apps. You can publish an app as self-contained or as framework-dependent. Each mode affects how a user runs your app. -ms.date: 03/18/2024 +ms.date: 07/01/2025 --- # .NET application publishing overview -Applications you create with .NET can be published in two different modes, and the mode affects how a user runs your app. +INTRO PARA -Publishing your app as *self-contained* produces an application that includes the .NET runtime and libraries, and your application and its dependencies. Users of the application can run it on a machine that doesn't have the .NET runtime installed. +## What is publishing -Publishing your app as *framework-dependent* produces an application that includes only your application itself and its dependencies. Users of the application have to separately install the .NET runtime. +Publishing a .NET app means compiling source code to create an executable or binary, along with its dependencies and related files, for distribution. After publishing, you deploy the app to a server, distribution platform, container, or cloud environment. The publishing process prepares an app for deployment and use outside of your development environment. -Both publishing modes produce a platform-specific executable by default. Framework-dependent applications can be created without an executable, and these applications are cross-platform. +## Publishing modes -When an executable is produced, you can specify the target platform with a runtime identifier (RID). For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). +There are two primary ways to publish an app, and depending on how you're going to deploy your app, you would choose one or the other. The choice largly depends on if the deployment environment has the appropriate .NET Runtime installed. The two publishing modes are: + +- Publish *self-contained*\ +This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need have the .NET runtime pre-installed. + +- Publishing *framework-dependent*\ +This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing your app code, and any app dependencies. The environment that runs the app must have an version of the .NET runtime installed that the app can use. An optional platform-specific executable can be producted. + +> [!IMPORTANT] +> When an executable is produced, you can specify the target platform with a runtime identifier (RID). For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). The following table outlines the commands used to publish an app as framework-dependent or self-contained: -| Type | Command | -|--|--| -| [framework-dependent executable](#publish-framework-dependent) for the current platform. | [`dotnet publish`](../tools/dotnet-publish.md) | -| [framework-dependent executable](#publish-framework-dependent) for a specific platform. | [`dotnet publish -r `](../tools/dotnet-publish.md) | -| [framework-dependent binary](#publish-framework-dependent). | [`dotnet publish`](../tools/dotnet-publish.md) | -| [self-contained executable](#publish-self-contained). | [`dotnet publish -r --self-contained`](../tools/dotnet-publish.md) | +| Type | Command | +|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| +| [framework-dependent executable](#publish-framework-dependent) for the current platform. | [`dotnet publish`](../tools/dotnet-publish.md) | +| [framework-dependent executable](#publish-framework-dependent) for a specific platform. | [`dotnet publish -r `](../tools/dotnet-publish.md) | +| [framework-dependent binary](#publish-framework-dependent). | [`dotnet publish`](../tools/dotnet-publish.md) | +| [self-contained executable](#publish-self-contained). | [`dotnet publish -r --self-contained`](../tools/dotnet-publish.md) | For more information, see [.NET dotnet publish command](../tools/dotnet-publish.md). ## Produce an executable -Executables aren't cross-platform, they're specific to an operating system and CPU architecture. When publishing your app and creating an executable, you can publish the app as [self-contained](#publish-self-contained) or [framework-dependent](#publish-framework-dependent). Publishing an app as self-contained includes the .NET runtime with the app, and users of the app don't have to worry about installing .NET before running the app. Publishing an app as framework-dependent doesn't include the .NET runtime; only the app and third-party dependencies are included. +Executables aren't cross-platform, they're specific to an operating system and CPU architecture. When publishing your app and creating an executable, you can publish the app as [self-contained](#publish-self-contained) or [framework-dependent](#publish-framework-dependent). Publishing an app as self-contained includes the .NET runtime with the app, meaning, users don't have to worry about installing .NET before running the app. Publishing an app as framework-dependent doesn't include the .NET runtime; only the app and third-party dependencies are included. The following commands produce an executable: @@ -41,7 +50,7 @@ The following commands produce an executable: ## Produce a cross-platform binary -Cross-platform binaries are created when you publish your app as [framework-dependent](#publish-framework-dependent), in the form of a *dll* file. The *dll* file is named after your project. For example, if you have an app named **word_reader**, a file named *word_reader.dll* is created. Apps published in this way are run with the `dotnet ` command and can be run on any platform. +Cross-platform binaries are created when the app is published as [framework-dependent](#publish-framework-dependent), in the form of a *dll* file. The *dll* file is named after the project. For example, if you have an app named **word_reader**, a file named *word_reader.dll* is created. Apps published in this way are run with the `dotnet ` command. Cross-platform binaries can be run on any operating system as long as the targeted .NET runtime is already installed. If the targeted .NET runtime isn't installed, the app may run using a newer runtime if the app is configured to roll-forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). From 611c8cb2ab0d632beb6a248837065efcb8380905 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 2 Jul 2025 16:42:19 -0700 Subject: [PATCH 02/29] Temp --- docs/core/deploying/index.md | 63 ++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 46642173b6f84..3456bce715a78 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -14,16 +14,16 @@ Publishing a .NET app means compiling source code to create an executable or bin ## Publishing modes -There are two primary ways to publish an app, and depending on how you're going to deploy your app, you would choose one or the other. The choice largly depends on if the deployment environment has the appropriate .NET Runtime installed. The two publishing modes are: +There are two primary ways to publish an app, and depending on how the app is deployed, one or the other is chosen. The choice largely depends on whether the deployment environment has the appropriate .NET Runtime installed. The two publishing modes are: - Publish *self-contained*\ -This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need have the .NET runtime pre-installed. +This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need to have the .NET runtime pre-installed. -- Publishing *framework-dependent*\ -This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing your app code, and any app dependencies. The environment that runs the app must have an version of the .NET runtime installed that the app can use. An optional platform-specific executable can be producted. +- Publish *framework-dependent*\ +This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, and any app dependencies. The environment that runs the app must have a version of the .NET runtime installed that the app can use. An optional platform-specific executable can be produced. > [!IMPORTANT] -> When an executable is produced, you can specify the target platform with a runtime identifier (RID). For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). +> You specify the target platform with a runtime identifier (RID). For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). The following table outlines the commands used to publish an app as framework-dependent or self-contained: @@ -38,7 +38,7 @@ For more information, see [.NET dotnet publish command](../tools/dotnet-publish. ## Produce an executable -Executables aren't cross-platform, they're specific to an operating system and CPU architecture. When publishing your app and creating an executable, you can publish the app as [self-contained](#publish-self-contained) or [framework-dependent](#publish-framework-dependent). Publishing an app as self-contained includes the .NET runtime with the app, meaning, users don't have to worry about installing .NET before running the app. Publishing an app as framework-dependent doesn't include the .NET runtime; only the app and third-party dependencies are included. +Executables aren't cross-platform; they're specific to an operating system and CPU architecture. Executables are produced as either [self-contained](#publish-self-contained) or [framework-dependent](#publish-framework-dependent). Publishing as self-contained includes the .NET runtime with the app, so users don't have to install .NET before running it. Publishing as framework-dependent doesn't include the .NET runtime; only the app and third-party dependencies are included. The following commands produce an executable: @@ -52,12 +52,12 @@ The following commands produce an executable: Cross-platform binaries are created when the app is published as [framework-dependent](#publish-framework-dependent), in the form of a *dll* file. The *dll* file is named after the project. For example, if you have an app named **word_reader**, a file named *word_reader.dll* is created. Apps published in this way are run with the `dotnet ` command. -Cross-platform binaries can be run on any operating system as long as the targeted .NET runtime is already installed. If the targeted .NET runtime isn't installed, the app may run using a newer runtime if the app is configured to roll-forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +Cross-platform binaries can run on any operating system as long as the targeted .NET runtime is already installed. If the targeted .NET runtime isn't installed, the app might run using a newer runtime if configured to roll-forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). -You can choose to run the app as a platform-specific executable or as a cross-platform binary via `dotnet` command. There should be no app behavior difference when launching the platform-specific executable versus the `dotnet` command for ordinary server apps Launching via a platform-specific executable gives you better integration with the underlying OS. For example: +Choose to run the app as a platform-specific executable or as a cross-platform binary via the `dotnet` command. There should be no app behavior difference when launching the platform-specific executable versus the `dotnet` command. Launching via a platform-specific executable gives better integration with the underlying OS. For example: -- You see the application executable name in your process list and not `dotnet`, which could be confusing if there's more than one. -- You can customize the platform-specific executable with OS specific features. For example, see [this discussion about configuring default stack size on Windows](https://github.com/dotnet/runtime/issues/96347#issuecomment-1981470713). +- The application executable name appears in the process list instead of `dotnet`, which could be confusing if there's more than one. +- The platform-specific executable can be customized with OS-specific features. For example, see [this discussion about configuring default stack size on Windows](https://github.com/dotnet/runtime/issues/96347#issuecomment-1981470713). The following command produces a cross-platform binary: @@ -67,42 +67,42 @@ The following command produces a cross-platform binary: ## Publish framework-dependent -Apps published as framework-dependent are cross-platform and don't include the .NET runtime. The user of your app is required to install the .NET runtime. +Apps published as framework-dependent are cross-platform and don't include the .NET runtime. The user is required to install the .NET runtime. -Publishing an app as framework-dependent produces a [cross-platform binary](#produce-a-cross-platform-binary) as a *dll* file, and a [platform-specific executable](#produce-an-executable) that targets your current platform. The *dll* is cross-platform while the executable isn't. For example, if you publish an app named **word_reader** and target Windows, a *word_reader.exe* executable is created along with *word_reader.dll*. When targeting Linux or macOS, a *word_reader* executable is created along with *word_reader.dll*. If the app uses a NuGet package that has platform-specific implementations, dependencies for all platforms are copied to the *publish\\runtimes\\{platform}* folder. +Publishing as framework-dependent produces a [cross-platform binary](#produce-a-cross-platform-binary) as a *dll* file, and a [platform-specific executable](#produce-an-executable) that targets the current platform. The *dll* is cross-platform while the executable isn't. For example, if the app is named **word_reader** and targets Windows, a *word_reader.exe* executable is created along with *word_reader.dll*. When targeting Linux or macOS, a *word_reader* executable is created along with *word_reader.dll*. If the app uses a NuGet package that has platform-specific implementations, dependencies for all platforms are copied to the *publish\\runtimes\\{platform}* folder. -The cross-platform binary of your app can be run with the `dotnet ` command, and can be run on any platform. +The cross-platform binary can be run with the `dotnet ` command, and can run on any platform. ### Platform-specific and framework-dependent -You can publish a framework-dependent app that's platform-specific by passing the `-r ` parameters to the [`dotnet publish`](../tools/dotnet-publish.md) command. Publishing in this way is the same as [publish framework-dependent](#publish-framework-dependent), except that platform-specific dependencies are handled differently. If the app uses a NuGet package that has platform-specific implementations, only the targeted platform's dependencies are copied. These dependencies are copied directly to the *publish* folder. +Publish a framework-dependent app that's platform-specific by passing the `-r ` parameters to the [`dotnet publish`](../tools/dotnet-publish.md) command. Publishing in this way is the same as [publish framework-dependent](#publish-framework-dependent), except that platform-specific dependencies are handled differently. If the app uses a NuGet package that has platform-specific implementations, only the targeted platform's dependencies are copied. These dependencies are copied directly to the *publish* folder. -While technically the binary produced is cross-platform, by targeting a specific platform, your app isn't guaranteed to run cross-platform. You can run `dotnet `, but the app may crash when it tries to access platform-specific dependencies that are missing. +While technically the binary produced is cross-platform, by targeting a specific platform, the app isn't guaranteed to run cross-platform. The app can be run with `dotnet `, but it might crash when it tries to access platform-specific dependencies that are missing. For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). ### Advantages - **Small deployment**\ -Only your app and its dependencies are distributed. The .NET runtime and libraries are installed by the user and all apps share the runtime. +Only the app and its dependencies are distributed. The .NET runtime and libraries are installed by the user and all apps share the runtime. - **Cross-platform**\ -Your app and any .NET-based library runs on other operating systems. You don't need to define a target platform for your app. For information about the .NET file format, see [.NET Assembly File Format](../../standard/assembly/file-format.md). +The app and any .NET-based library runs on other operating systems. There's no need to define a target platform for the app. For information about the .NET file format, see [.NET Assembly File Format](../../standard/assembly/file-format.md). - **Uses the latest patched runtime**\ -The app uses the latest runtime (within the targeted major-minor family of .NET) installed on the target system. This means your app automatically uses the latest patched version of the .NET runtime. This default behavior can be overridden. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +The app uses the latest runtime (within the targeted major-minor family of .NET) installed on the target system. This means the app automatically uses the latest patched version of the .NET runtime. This default behavior can be overridden. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). ### Disadvantages - **Requires pre-installing the runtime**\ -Your app can run only if the version of .NET your app targets is already installed on the host system. You can configure roll-forward behavior for the app to either require a specific version of .NET or allow a newer version of .NET. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +The app can run only if the version of .NET it targets is already installed on the enviornment running the app. Configure roll-forward behavior for the app to either require a specific version of .NET or allow a newer version of .NET. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). - **.NET may change**\ -It's possible for the .NET runtime and libraries to be updated on the machine where the app is run. In rare cases, this may change the behavior of your app if you use the .NET libraries, which most apps do. You can configure how your app uses newer versions of .NET. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +It's possible that the environment where the app is run is using a newer .NET runtime. In rare cases, this might change the behavior of the app if it uses the .NET libraries, which most apps do. You can configure how an app uses newer versions of .NET, known as rolling forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). ### Examples -Publish an app as cross-platform and framework-dependent. An executable that targets your current platform is created along with the *dll* file. Any platform-specific dependencies are published with the app. +Publish an app as cross-platform and framework-dependent. An executable that targets the current platform is created along with the *dll* file. Any platform-specific dependencies are published with the app. ```dotnetcli dotnet publish @@ -116,33 +116,32 @@ dotnet publish -r linux-x64 ## Publish self-contained -Publishing your app as self-contained produces a platform-specific executable. The output publishing folder contains all components of the app, including the .NET libraries and target runtime. The app is isolated from other .NET apps and doesn't use a locally installed shared runtime. The user of your app isn't required to download and install .NET. +Publishing as self-contained produces a platform-specific executable. The output publishing folder contains all components of the app, including the .NET libraries and target runtime. The app is isolated from other .NET apps and doesn't use a locally installed shared runtime. The user isn't required to download and install .NET. -You can publish a self-contained app by passing the `--self-contained` parameter to the [`dotnet publish`](../tools/dotnet-publish.md) command. The executable binary is produced for the specified target platform. For example, if you have an app named **word_reader**, and you publish a self-contained executable for Windows, a *word_reader.exe* file is created. Publishing for Linux or macOS, a *word_reader* file is created. The target platform and architecture is specified with the `-r ` parameter for the [`dotnet publish`](../tools/dotnet-publish.md) command. For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). +Publish a self-contained app by passing the `--self-contained` parameter to the [`dotnet publish`](../tools/dotnet-publish.md) command. The executable binary is produced for the specified target platform. For example, if the app is named **word_reader**, and a self-contained executable is published for Windows, a *word_reader.exe* file is created. Publishing for Linux or macOS, a *word_reader* file is created. The target platform and architecture is specified with the `-r ` parameter for the [`dotnet publish`](../tools/dotnet-publish.md) command. For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). If the app has platform-specific dependencies, such as a NuGet package containing platform-specific dependencies, these are copied to the publish folder along with the app. ### Advantages - **Control .NET version**\ -You control which version of .NET is deployed with your app. +Control which version of .NET is deployed with the app. - **Platform-specific targeting**\ -Because you have to publish your app for each platform, you know where your app runs. If .NET introduces a new platform, users can't run your app on that platform until you release a version targeting that platform. You can test your app for compatibility problems before your users run your app on the new platform. +Because the app must be published for each platform, it's clear where the app runs. If .NET introduces a new platform, users can't run the app on that platform until a version targeting that platform is released. Test the app for compatibility problems before users run it on the new platform. ### Disadvantages - **Larger deployments**\ -Because your app includes the .NET runtime and all of your app dependencies, the download size and hard drive space required is greater than a [framework-dependent](#publish-framework-dependent) version. +Because the app includes the .NET runtime and all dependencies, the download size and hard drive space required is greater than a [framework-dependent](#publish-framework-dependent) version. > [!TIP] - > You can reduce the size of your deployment on Linux systems by approximately 28 MB by using .NET [*globalization invariant mode*](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). This forces your app to treat all cultures like the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType). - - > [!TIP] - > [IL trimming](trimming/trim-self-contained.md) can further reduce the size of your deployment. + > Reduce the size of the deployment on Linux systems by approximately 28 MB by using .NET [*globalization invariant mode*](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). This forces the app to treat all cultures like the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType). + > + > [IL trimming](trimming/trim-self-contained.md) can further reduce the size of the deployment. - **Harder to update the .NET version**\ -.NET Runtime (distributed with your app) can only be upgraded by releasing a new version of your app. +The .NET Runtime (distributed with the app) can only be upgraded by releasing a new version of the app. ### Examples @@ -160,7 +159,7 @@ dotnet publish -r win-x64 --self-contained ## Publish with ReadyToRun images -Publishing with ReadyToRun images improves the startup time of your application at the cost of increasing the size of your application. For more information, see [ReadyToRun](ready-to-run.md). +Publishing with ReadyToRun images improves the startup time of the application at the cost of increasing the size of the application. For more information, see [ReadyToRun](ready-to-run.md). ### Advantages From 4d2f6d68ef928dbea7ab6c9e5b0655e42337c098 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 2 Jul 2025 17:19:53 -0700 Subject: [PATCH 03/29] final updates --- docs/core/deploying/index.md | 38 ++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 3456bce715a78..2d6a3e15e1c59 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -6,18 +6,18 @@ ms.date: 07/01/2025 # .NET application publishing overview -INTRO PARA +This article explains the different ways to publish a .NET application. It covers publishing modes, how to produce executables and cross-platform binaries, and the impact of each approach on deployment and runtime environments. ## What is publishing -Publishing a .NET app means compiling source code to create an executable or binary, along with its dependencies and related files, for distribution. After publishing, you deploy the app to a server, distribution platform, container, or cloud environment. The publishing process prepares an app for deployment and use outside of your development environment. +Publishing a .NET app means compiling source code to create an executable or binary, along with its dependencies and related files, for distribution. After publishing, deploy the app to a server, distribution platform, container, or cloud environment. The publishing process prepares an app for deployment and use outside of a development environment. ## Publishing modes There are two primary ways to publish an app, and depending on how the app is deployed, one or the other is chosen. The choice largely depends on whether the deployment environment has the appropriate .NET Runtime installed. The two publishing modes are: - Publish *self-contained*\ -This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need to have the .NET runtime pre-installed. +This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need to have the .NET runtime preinstalled. - Publish *framework-dependent*\ This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, and any app dependencies. The environment that runs the app must have a version of the .NET runtime installed that the app can use. An optional platform-specific executable can be produced. @@ -54,10 +54,10 @@ Cross-platform binaries are created when the app is published as [framework-depe Cross-platform binaries can run on any operating system as long as the targeted .NET runtime is already installed. If the targeted .NET runtime isn't installed, the app might run using a newer runtime if configured to roll-forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). -Choose to run the app as a platform-specific executable or as a cross-platform binary via the `dotnet` command. There should be no app behavior difference when launching the platform-specific executable versus the `dotnet` command. Launching via a platform-specific executable gives better integration with the underlying OS. For example: +You can choose to run the app as a platform-specific executable or as a cross-platform binary via the `dotnet` command. There should be no app behavior difference when launching the platform-specific executable versus the `dotnet` command. Launching via a platform-specific executable gives you better integration with the underlying OS. For example: -- The application executable name appears in the process list instead of `dotnet`, which could be confusing if there's more than one. -- The platform-specific executable can be customized with OS-specific features. For example, see [this discussion about configuring default stack size on Windows](https://github.com/dotnet/runtime/issues/96347#issuecomment-1981470713). +- You'll see the app executable name in your process list instead of `dotnet`, which could be confusing if there's more than one. +- You can customize the platform-specific executable with OS-specific features. For more information, see [this discussion about configuring default stack size on Windows](https://github.com/dotnet/runtime/issues/96347#issuecomment-1981470713). The following command produces a cross-platform binary: @@ -67,38 +67,38 @@ The following command produces a cross-platform binary: ## Publish framework-dependent -Apps published as framework-dependent are cross-platform and don't include the .NET runtime. The user is required to install the .NET runtime. +Apps published as framework-dependent are cross-platform and don't include the .NET runtime. The environment where the app runs must have the .NET runtime installed. Publishing as framework-dependent produces a [cross-platform binary](#produce-a-cross-platform-binary) as a *dll* file, and a [platform-specific executable](#produce-an-executable) that targets the current platform. The *dll* is cross-platform while the executable isn't. For example, if the app is named **word_reader** and targets Windows, a *word_reader.exe* executable is created along with *word_reader.dll*. When targeting Linux or macOS, a *word_reader* executable is created along with *word_reader.dll*. If the app uses a NuGet package that has platform-specific implementations, dependencies for all platforms are copied to the *publish\\runtimes\\{platform}* folder. -The cross-platform binary can be run with the `dotnet ` command, and can run on any platform. +The cross-platform binary can be run with the `dotnet ` command, and can run on any environment. ### Platform-specific and framework-dependent Publish a framework-dependent app that's platform-specific by passing the `-r ` parameters to the [`dotnet publish`](../tools/dotnet-publish.md) command. Publishing in this way is the same as [publish framework-dependent](#publish-framework-dependent), except that platform-specific dependencies are handled differently. If the app uses a NuGet package that has platform-specific implementations, only the targeted platform's dependencies are copied. These dependencies are copied directly to the *publish* folder. -While technically the binary produced is cross-platform, by targeting a specific platform, the app isn't guaranteed to run cross-platform. The app can be run with `dotnet `, but it might crash when it tries to access platform-specific dependencies that are missing. +While technically the binary produced is cross-platform, by targeting a specific environment, the app isn't guaranteed to run cross-platform. The app can be run with `dotnet `, but it might crash when it tries to access platform-specific dependencies that are missing. For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). ### Advantages - **Small deployment**\ -Only the app and its dependencies are distributed. The .NET runtime and libraries are installed by the user and all apps share the runtime. +Only the app and its dependencies are distributed. The environment where the app is run must already have the .NET runtime installed. - **Cross-platform**\ The app and any .NET-based library runs on other operating systems. There's no need to define a target platform for the app. For information about the .NET file format, see [.NET Assembly File Format](../../standard/assembly/file-format.md). - **Uses the latest patched runtime**\ -The app uses the latest runtime (within the targeted major-minor family of .NET) installed on the target system. This means the app automatically uses the latest patched version of the .NET runtime. This default behavior can be overridden. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +The app uses the latest runtime (within the targeted major-minor family of .NET) installed in the environment. This means the app automatically uses the latest patched version of the .NET runtime. This default behavior can be overridden. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). ### Disadvantages - **Requires pre-installing the runtime**\ -The app can run only if the version of .NET it targets is already installed on the enviornment running the app. Configure roll-forward behavior for the app to either require a specific version of .NET or allow a newer version of .NET. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +The app can run only if the version of .NET it targets is already installed in the environment running the app. Configure roll-forward behavior for the app to either require a specific version of .NET or allow a newer version of .NET. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). - **.NET may change**\ -It's possible that the environment where the app is run is using a newer .NET runtime. In rare cases, this might change the behavior of the app if it uses the .NET libraries, which most apps do. You can configure how an app uses newer versions of .NET, known as rolling forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +It's possible that the environment where the app is run is using a newer .NET runtime. In rare cases, this might change the behavior of the app if it uses the .NET libraries, which most apps do. Configure how an app uses newer versions of .NET, known as rolling forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). ### Examples @@ -116,9 +116,9 @@ dotnet publish -r linux-x64 ## Publish self-contained -Publishing as self-contained produces a platform-specific executable. The output publishing folder contains all components of the app, including the .NET libraries and target runtime. The app is isolated from other .NET apps and doesn't use a locally installed shared runtime. The user isn't required to download and install .NET. +Publishing as self-contained produces a platform-specific executable. The output publishing folder contains all components of the app, including the .NET libraries and target runtime. The app is isolated from other .NET apps and doesn't use a locally installed shared runtime. The environment running the app isn't required to have a .NET runtime installed. -Publish a self-contained app by passing the `--self-contained` parameter to the [`dotnet publish`](../tools/dotnet-publish.md) command. The executable binary is produced for the specified target platform. For example, if the app is named **word_reader**, and a self-contained executable is published for Windows, a *word_reader.exe* file is created. Publishing for Linux or macOS, a *word_reader* file is created. The target platform and architecture is specified with the `-r ` parameter for the [`dotnet publish`](../tools/dotnet-publish.md) command. For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). +Publish a self-contained app by passing the `--self-contained` parameter to the [`dotnet publish`](../tools/dotnet-publish.md) command. The executable binary is produced for the specified target environment. For example, if your app is named **word_reader**, and you publish a self-contained executable for Windows, a *word_reader.exe* file is created. If you publish for Linux or macOS, a *word_reader* file is created. Specify the target environment and architecture with the `-r ` parameter for the [`dotnet publish`](../tools/dotnet-publish.md) command. For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). If the app has platform-specific dependencies, such as a NuGet package containing platform-specific dependencies, these are copied to the publish folder along with the app. @@ -136,7 +136,7 @@ Because the app must be published for each platform, it's clear where the app ru Because the app includes the .NET runtime and all dependencies, the download size and hard drive space required is greater than a [framework-dependent](#publish-framework-dependent) version. > [!TIP] - > Reduce the size of the deployment on Linux systems by approximately 28 MB by using .NET [*globalization invariant mode*](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). This forces the app to treat all cultures like the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType). + > Reduce the size of the deployment on Linux environments by approximately 28 MB by using .NET [*globalization invariant mode*](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). This forces the app to treat all cultures like the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType). > > [IL trimming](trimming/trim-self-contained.md) can further reduce the size of the deployment. @@ -159,17 +159,17 @@ dotnet publish -r win-x64 --self-contained ## Publish with ReadyToRun images -Publishing with ReadyToRun images improves the startup time of the application at the cost of increasing the size of the application. For more information, see [ReadyToRun](ready-to-run.md). +Publishing with ReadyToRun images improves the startup time of the app at the cost of increasing the size of the app. For more information, see [ReadyToRun](ready-to-run.md). ### Advantages - **Improved startup time**\ -The application spends less time running the JIT. +The app spends less time running the JIT. ### Disadvantages - **Larger size**\ -The application is larger on disk. +The app is larger on disk. ### Examples From 1e98667899ecf37df512febb8a3da0cbf9bc3e0a Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 2 Jul 2025 19:36:45 -0700 Subject: [PATCH 04/29] Minor --- docs/core/deploying/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 2d6a3e15e1c59..60074d15a3cf3 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -56,8 +56,8 @@ Cross-platform binaries can run on any operating system as long as the targeted You can choose to run the app as a platform-specific executable or as a cross-platform binary via the `dotnet` command. There should be no app behavior difference when launching the platform-specific executable versus the `dotnet` command. Launching via a platform-specific executable gives you better integration with the underlying OS. For example: -- You'll see the app executable name in your process list instead of `dotnet`, which could be confusing if there's more than one. -- You can customize the platform-specific executable with OS-specific features. For more information, see [this discussion about configuring default stack size on Windows](https://github.com/dotnet/runtime/issues/96347#issuecomment-1981470713). +- The app executable name appears in the process list instead of `dotnet`, which could be confusing if there's more than one. +- The platform-specific executable can be customized with OS-specific features. For example, see [this discussion about configuring default stack size on Windows](https://github.com/dotnet/runtime/issues/96347#issuecomment-1981470713). The following command produces a cross-platform binary: From 3c469bf875864d81681a2c079ba7c3d94e64d108 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 8 Aug 2025 13:01:09 -0700 Subject: [PATCH 05/29] Rename and rewrite --- docs/core/deploying/deploy-with-cli.md | 175 -------------- docs/core/deploying/deploy-with-vs.md | 307 ------------------------ docs/core/deploying/publish-with-cli.md | 255 ++++++++++++++++++++ docs/core/deploying/publish-with-vs.md | 202 ++++++++++++++++ 4 files changed, 457 insertions(+), 482 deletions(-) delete mode 100644 docs/core/deploying/deploy-with-cli.md delete mode 100644 docs/core/deploying/deploy-with-vs.md create mode 100644 docs/core/deploying/publish-with-cli.md create mode 100644 docs/core/deploying/publish-with-vs.md diff --git a/docs/core/deploying/deploy-with-cli.md b/docs/core/deploying/deploy-with-cli.md deleted file mode 100644 index 7485645b780f2..0000000000000 --- a/docs/core/deploying/deploy-with-cli.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Publish apps with the .NET CLI -description: Learn to publish a .NET application using the .NET CLI commands. -author: adegeo -ms.author: adegeo -ms.date: 11/22/2024 -ms.custom: updateeachrelease -dev_langs: - - "csharp" - - "vb" ---- - -# Publish .NET apps with the .NET CLI - -This article demonstrates how you can publish your .NET application from the command line. .NET provides three ways to publish your applications. Framework-dependent deployment produces a cross-platform .dll file that uses the locally installed .NET runtime. Framework-dependent executable produces a platform-specific executable that uses the locally installed .NET runtime. Self-contained executable produces a platform-specific executable and includes a local copy of the .NET runtime. - -For an overview of these publishing modes, see [.NET Application Deployment](index.md). - -Looking for some quick help on using the CLI? The following table shows some examples of how to publish your app. You can specify the target framework with the `-f ` parameter or by editing the project file. For more information, see [Publishing basics](#publishing-basics). - -| Publish Mode | Command | -|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------| -| [Framework-dependent deployment](#framework-dependent-deployment) | `dotnet publish -c Release -p:UseAppHost=false` | -| [Framework-dependent executable](#framework-dependent-executable) | `dotnet publish -c Release -r --self-contained false`
`dotnet publish -c Release` | -| [Self-contained deployment](#self-contained-deployment) | `dotnet publish -c Release -r --self-contained true` | - -> [!NOTE] -> -> - The `-c Release` parameter isn't required. It's provided as a reminder to publish the **Release** build of your app. -> - In **.NET SDK 3.1** or higher, framework-dependent executable is the default publishing mode when running the basic `dotnet publish` command. - -## Publishing basics - -The `` setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. The TFM specified in this setting is the default target used by the [`dotnet publish`](../tools/dotnet-publish.md) command. - -If you want to target more than one framework, you can set the `` setting to multiple TFM values, separated by a semicolon. When you build your app, a build is produced for each target framework. However, when you publish your app, you must specify the target framework with the `dotnet publish -f ` command. - -The default **BUILD-CONFIGURATION** mode is **Release** unless changed with the `-c` parameter. - -The default output directory of the [`dotnet publish`](../tools/dotnet-publish.md) command is `./bin///publish/`. For example, `dotnet publish -c Release -f net9.0` publishes to `./bin/Release/net9.0/publish/`. However, you can opt in to a simplified output path and folder structure for all build outputs. For more information, see [Artifacts output layout](../sdk/artifacts-output.md). - -### Native dependencies - -If your app has native dependencies, it may not run on a different operating system. For example, if your app uses the native Windows API, it won't run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. - -Consider also, if a library you referenced has a native dependency, your app may not run on every platform. However, it's possible a NuGet package you're referencing has included platform-specific versions to handle the required native dependencies for you. - -When distributing an app with native dependencies, you may need to use the `dotnet publish -r ` switch to specify the target platform you want to publish for. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). - -More information about platform-specific binaries is covered in the [Framework-dependent executable](#framework-dependent-executable) and [Self-contained deployment](#self-contained-deployment) sections. - -## Sample app - -You can use the following app to explore the publishing commands. The app is created by running the following commands in your terminal: - -```dotnetcli -mkdir apptest1 -cd apptest1 -dotnet new console -dotnet add package Figgle -``` - -The `Program.cs` or `Program.vb` file that is generated by the console template needs to be changed to the following: - -```csharp -using System; - -namespace apptest1 -{ - class Program - { - static void Main(string[] args) - { - Console.WriteLine(Figgle.FiggleFonts.Standard.Render("Hello, World!")); - } - } -} -``` - -```vb -Module Program - Sub Main(args As String()) - Console.WriteLine(Figgle.FiggleFonts.Standard.Render("Hello, World!")) - End Sub -End Module -``` - -When you run the app ([`dotnet run`](../tools/dotnet-run.md)), the following output is displayed: - -```terminal - _ _ _ _ __ __ _ _ _ - | | | | ___| | | ___ \ \ / /__ _ __| | __| | | - | |_| |/ _ \ | |/ _ \ \ \ /\ / / _ \| '__| |/ _` | | - | _ | __/ | | (_) | \ V V / (_) | | | | (_| |_| - |_| |_|\___|_|_|\___( ) \_/\_/ \___/|_| |_|\__,_(_) - |/ -``` - -## Framework-dependent deployment - -When you publish your app as an FDD, a `.dll` file is created in the `./bin///publish/` folder. To run your app, navigate to the output folder and use the `dotnet .dll` command. - -Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. - -Publishing an FDD creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). - -| Publish Mode | Command | -|--------------------------------|-------------------------------------------------------------| -| Framework-dependent deployment | `dotnet publish -c Release -p:UseAppHost=false` | - -## Framework-dependent executable - -Framework-dependent executable (FDE) is the default mode for the basic `dotnet publish` command. You don't need to specify any other parameters, as long as you want to target the current operating system. - -In this mode, a platform-specific executable host is created to host your cross-platform app. This mode is similar to FDD, as FDD requires a host in the form of the `dotnet` command. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. - -Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. - -Publishing an FDE creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). - -| Publish Mode | Command | -|--------------------------------|-------------------------------------------------------------| -| Framework-dependent executable | `dotnet publish -c Release -r --self-contained false`
`dotnet publish -c Release` | - -Whenever you use the `-r` switch, the output folder path changes to: `./bin////publish/` - -If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 --self-contained false`. This command creates the following executable: `./bin/Debug/net9.0/win-x64/publish/apptest1.exe` - -> [!NOTE] -> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). - -### Configure .NET install search behavior - -In .NET 9 and later versions, you can configure the .NET installation search paths of the published executable via the [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch) and [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) properties. - -`AppHostDotNetSearch` allows specifying one or more locations where the executable will look for a .NET installation: - -- `AppLocal`: app executable's folder -- `AppRelative`: path relative to the app executable -- `EnvironmentVariables`: value of [`DOTNET_ROOT[_]`](../tools/dotnet-environment-variables.md#dotnet_root-dotnet_rootx86-dotnet_root_x86-dotnet_root_x64) environment variables -- `Global`: [registered](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-custom-location) and [default](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-default-location) global install locations - -`AppHostRelativeDotNet` specifies the path relative to the executable that will be searched when `AppHostDotNetSearch` contains `AppRelative`. - -For more information, see [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch), [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) and [install location options in apphost](https://github.com/dotnet/designs/blob/main/proposed/apphost-embed-install-location.md). - -## Self-contained deployment - -When you publish a self-contained deployment (SCD), the .NET SDK creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the native dependencies of .NET (for example, for [.NET 8 on Linux](https://github.com/dotnet/core/blob/main/release-notes/8.0/linux-packages.md)). These dependencies must be present on the system before the app runs. - -Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). - -You must use the following switches with the `dotnet publish` command to publish an SCD: - -- `-r ` - - This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). - -- `--self-contained true` - - This switch tells the .NET SDK to create an executable as an SCD. - -| Publish Mode | Command | -|--------------------------------|-------------------------------------------------------------| -| Self-contained deployment | `dotnet publish -c Release -r --self-contained true` | - -> [!TIP] -> -> - In .NET 6 and later versions, you can reduce the total size of compatible self-contained apps by [publishing trimmed](trimming/trim-self-contained.md). This enables the trimmer to remove parts of the framework and referenced assemblies that are not on any code path or potentially referenced in [runtime reflection](../../csharp/advanced-topics/reflection-and-attributes/index.md). See [trimming incompatibilities](./trimming/incompatibilities.md) to determine if trimming makes sense for your application. -> - You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). - -## See also - -- [.NET Application Deployment Overview](index.md) -- [.NET Runtime IDentifier (RID) catalog](../rid-catalog.md) diff --git a/docs/core/deploying/deploy-with-vs.md b/docs/core/deploying/deploy-with-vs.md deleted file mode 100644 index 5e77c0f34cd73..0000000000000 --- a/docs/core/deploying/deploy-with-vs.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: Deploy .NET Core apps with Visual Studio -description: Learn to deploy a .NET Core app with Visual Studio. -ms.date: 09/03/2018 -dev_langs: - - "csharp" - - "vb" -ms.custom: vs-dotnet ---- -# Deploy .NET Core apps with Visual Studio - -You can deploy a .NET Core application either as a *framework-dependent deployment*, which includes your application binaries but depends on the presence of .NET Core on the target system, or as a *self-contained deployment*, which includes both your application and .NET Core binaries. For an overview of .NET Core application deployment, see [.NET Core Application Deployment](index.md). - -The following sections show how to use Microsoft Visual Studio to create the following kinds of deployments: - -- Framework-dependent deployment -- Framework-dependent deployment with third-party dependencies -- Self-contained deployment -- Self-contained deployment with third-party dependencies - -For information on using Visual Studio to develop .NET Core applications, see [.NET Core dependencies and requirements](../install/windows.md). - -## Framework-dependent deployment - -Deploying a framework-dependent deployment with no third-party dependencies simply involves building, testing, and publishing the app. A simple example written in C# illustrates the process. - -1. Create the project. - - Select **File** > **New** > **Project**. In the **New Project** dialog, expand your language's (C# or Visual Basic) project categories in the **Installed** project types pane, choose **.NET Core**, and then select the **Console App (.NET Core)** template in the center pane. Enter a project name, such as "FDD", in the **Name** text box. Select the **OK** button. - -1. Add the application's source code. - - Open the *Program.cs* or *Program.vb* file in the editor and replace the autogenerated code with the following code. It prompts the user to enter text and displays the individual words entered by the user. It uses the regular expression `\w+` to separate the words in the input text. - - [!code-csharp[deployment#1](./snippets/deploy-with-vs/csharp/deployment-example.cs)] - [!code-vb[deployment#1](./snippets/deploy-with-vs/vb/deployment-example.vb)] - -1. Create a Debug build of your app. - - Select **Build** > **Build Solution**. You can also compile and run the Debug build of your application by selecting **Debug** > **Start Debugging**. - -1. Deploy your app. - - After you've debugged and tested the program, create the files to be deployed with your app. To publish from Visual Studio, do the following: - - 1. Change the solution configuration from **Debug** to **Release** on the toolbar to build a Release (rather than a Debug) version of your app. - - 1. Right-click on the project (not the solution) in **Solution Explorer** and select **Publish**. - - 1. In the **Publish** tab, select **Publish**. Visual Studio writes the files that comprise your application to the local file system. - - 1. The **Publish** tab now shows a single profile, **FolderProfile**. The profile's configuration settings are shown in the **Summary** section of the tab. - - The resulting files are placed in a directory named `Publish` on Windows and `publish` on Unix systems that is in a subdirectory of your project's *.\bin\release\netcoreapp2.1* subdirectory. - -Along with your application's files, the publishing process emits a program database (.pdb) file that contains debugging information about your app. The file is useful primarily for debugging exceptions. You can choose not to package it with your application's files. You should, however, save it in the event that you want to debug the Release build of your app. - -Deploy the complete set of application files in any way you like. For example, you can package them in a Zip file, use a simple `copy` command, or deploy them with any installation package of your choice. Once installed, users can then execute your application by using the `dotnet` command and providing the application filename, such as `dotnet fdd.dll`. - -In addition to the application binaries, your installer should also either bundle the shared framework installer or check for it as a prerequisite as part of the application installation. Installation of the shared framework requires Administrator/root access since it is machine-wide. - -## Framework-dependent deployment with third-party dependencies - -Deploying a framework-dependent deployment with one or more third-party dependencies requires that any dependencies be available to your project. The following additional steps are required before you can build your app: - -1. Use the **NuGet Package Manager** to add a reference to a NuGet package to your project; and if the package is not already available on your system, install it. To open the package manager, select **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution**. - -1. Confirm that your third-party dependencies (for example, `Newtonsoft.Json`) are installed on your system and, if they aren't, install them. The **Installed** tab lists NuGet packages installed on your system. If `Newtonsoft.Json` is not listed there, select the **Browse** tab and enter "Newtonsoft.Json" in the search box. Select `Newtonsoft.Json` and, in the right pane, select your project before selecting **Install**. - -1. If `Newtonsoft.Json` is already installed on your system, add it to your project by selecting your project in the right pane of the **Manage Packages for Solution** tab. - -A framework-dependent deployment with third-party dependencies is only as portable as its third-party dependencies. For example, if a third-party library only supports macOS, the app isn't portable to Windows systems. This happens if the third-party dependency itself depends on native code. A good example of this is [Kestrel server](/aspnet/core/fundamentals/servers/kestrel), which requires a native dependency on [libuv](https://github.com/libuv/libuv). When an FDD is created for an application with this kind of third-party dependency, the published output contains a folder for each [Runtime Identifier (RID)](../rid-catalog.md) that the native dependency supports (and that exists in its NuGet package). - -## Self-contained deployment without third-party dependencies - -Deploying a self-contained deployment with no third-party dependencies involves creating the project, modifying the *csproj* file, building, testing, and publishing the app. A simple example written in C# illustrates the process. You begin by creating, coding, and testing your project just as you would a framework-dependent deployment: - -1. Create the project. - - Select **File** > **New** > **Project**. In the **New Project** dialog, expand your language's (C# or Visual Basic) project categories in the **Installed** project types pane, choose **.NET Core**, and then select the **Console App (.NET Core)** template in the center pane. Enter a project name, such as "SCD", in the **Name** text box, and select the **OK** button. - -1. Add the application's source code. - - Open the *Program.cs* or *Program.vb* file in your editor, and replace the autogenerated code with the following code. It prompts the user to enter text and displays the individual words entered by the user. It uses the regular expression `\w+` to separate the words in the input text. - - [!code-csharp[deployment#1](./snippets/deploy-with-vs/csharp/deployment-example.cs)] - [!code-vb[deployment#1](./snippets/deploy-with-vs/vb/deployment-example.vb)] - -1. Determine whether you want to use globalization invariant mode. - - Particularly if your app targets Linux, you can reduce the total size of your deployment by taking advantage of [globalization invariant mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). Globalization invariant mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). - - To enable invariant mode, right-click on your project (not the solution) in **Solution Explorer**, and select **Edit SCD.csproj** or **Edit SCD.vbproj**. Then add the following highlighted lines to the file: - - [!code-xml[globalization-invariant-mode](./snippets/deploy-with-vs/xml/invariant.csproj?highlight=7-9)] - -1. Create a Debug build of your application. - - Select **Build** > **Build Solution**. You can also compile and run the Debug build of your application by selecting **Debug** > **Start Debugging**. This debugging step lets you identify problems with your application when it's running on your host platform. You still will have to test it on each of your target platforms. - - If you've enabled globalization invariant mode, be particularly sure to test whether the absence of culture-sensitive data is suitable for your application. - -Once you've finished debugging, you can publish your self-contained deployment: - -# [Visual Studio 15.6 and earlier](#tab/vs156) - -After you've debugged and tested the program, create the files to be deployed with your app for each platform that it targets. - -To publish your app from Visual Studio, do the following: - -1. Define the platforms that your app will target. - - 1. Right-click on your project (not the solution) in **Solution Explorer** and select **Edit SCD.csproj**. - - 1. Create a `` tag in the `` section of your *csproj* file that defines the platforms your app targets, and specify the runtime identifier (RID) of each platform that you target. You also need to add a semicolon to separate the RIDs. See [Runtime identifier catalog](../rid-catalog.md) for a list of runtime identifiers. - - For example, the following example indicates that the app runs on 64-bit Windows operating systems and the 64-bit OS X operating system. - - ```xml - - win-x64;osx-x64 - - ``` - - The `` element can go into any `` that you have in your *csproj* file. A complete sample *csproj* file appears later in this section. - -1. Publish your app. - - After you've debugged and tested the program, create the files to be deployed with your app for each platform that it targets. - - To publish your app from Visual Studio, do the following: - - 1. Change the solution configuration from **Debug** to **Release** on the toolbar to build a Release (rather than a Debug) version of your app. - - 1. Right-click on the project (not the solution) in **Solution Explorer** and select **Publish**. - - 1. In the **Publish** tab, select **Publish**. Visual Studio writes the files that comprise your application to the local file system. - - 1. The **Publish** tab now shows a single profile, **FolderProfile**. The profile's configuration settings are shown in the **Summary** section of the tab. **Target Runtime** identifies which runtime has been published, and **Target Location** identifies where the files for the self-contained deployment were written. - - 1. Visual Studio by default writes all published files to a single directory. For convenience, it's best to create separate profiles for each target runtime and to place published files in a platform-specific directory. This involves creating a separate publishing profile for each target platform. So now rebuild the application for each platform by doing the following: - - 1. Select **Create new profile** in the **Publish** dialog. - - 1. In the **Pick a publish target** dialog, change the **Choose a folder** location to *bin\Release\PublishOutput\win-x64*. Select **OK**. - - 1. Select the new profile (**FolderProfile1**) in the list of profiles, and make sure that the **Target Runtime** is `win-x64`. If it isn't, select **Settings**. In the **Profile Settings** dialog, change the **Target Runtime** to `win-x64` and select **Save**. Otherwise, select **Cancel**. - - 1. Select **Publish** to publish your app for 64-bit Windows 10 platforms. - - 1. Follow the previous steps again to create a profile for the `osx-x64` platform. The **Target Location** is *bin\Release\PublishOutput\osx-x64*, and the **Target Runtime** is `osx-x64`. The name that Visual Studio assigns to this profile is **FolderProfile2**. - - Each target location contains the complete set of files (both your app files and all .NET Core files) needed to launch your app. - -Along with your application's files, the publishing process emits a program database (.pdb) file that contains debugging information about your app. The file is useful primarily for debugging exceptions. You can choose not to package it with your application's files. You should, however, save it in the event that you want to debug the Release build of your app. - -Deploy the published files in any way you like. For example, you can package them in a Zip file, use a simple `copy` command, or deploy them with any installation package of your choice. - -The following is the complete *csproj* file for this project. - -```xml - - - Exe - netcoreapp2.1 - win-x64;osx-x64 - - -``` - -# [Visual Studio 15.7 and later](#tab/vs157) - -After you've debugged and tested the program, create the files to be deployed with your app for each platform that it targets. This involves creating a separate profile for each target platform. - -For each platform that your application targets, do the following: - -1. Create a profile for your target platform. - - If this is the first profile you've created, right-click on the project (not the solution) in **Solution Explorer** and select **Publish**. - - If you've already created a profile, right-click on the project to open the **Publish** dialog if it isn't already open. Then select **New Profile**. - - The **Pick a Publish Target** dialog box opens. - -1. Select the location where Visual Studio publishes your application. - - If you're only publishing to a single platform, you can accept the default value in the **Choose a folder** text box; this publishes the framework-dependent deployment of your application to the *\\bin\Release\netcoreapp2.1\publish* directory. - - If you're publishing to more than one platform, append a string that identifies the target platform. For example, if you append the string "linux" to the file path, Visual Studio publishes the framework-dependent deployment of your application to the *\\bin\Release\netcoreapp2.1\publish\linux* directory. - -1. Create the profile by selecting the drop-down list icon next to the **Publish** button and selecting **Create Profile**. Then select the **Create Profile** button to create the profile. - -1. Indicate that you are publishing a self-contained deployment and define a platform that your app will target. - - 1. In the **Publish** dialog, select the **Configure** link to open the **Profile Settings** dialog. - - 1. Select **Self-contained** in the **Deployment Mode** list box. - - 1. In the **Target Runtime** list box, select one of the platforms that your application targets. - - 1. Select **Save** to accept your changes and close the dialog. - -1. Name your profile. - - 1. Select **Actions** > **Rename Profile** to name your profile. - - 2. Assign your profile a name that identifies the target platform, then select **Save*. - -Repeat these steps to define any additional target platforms that your application targets. - -You've configured your profiles and are now ready to publish your app. To do this: - - 1. If the **Publish** window isn't currently open, right-click on the project (not the solution) in **Solution Explorer** and select **Publish**. - - 2. Select the profile that you'd like to publish, then select **Publish**. Do this for each profile to be published. - - Each target location (in the case of our example, bin\release\netcoreapp2.1\publish\\*profile-name*) contains the complete set of files (both your app files and all .NET Core files) needed to launch your app. - -Along with your application's files, the publishing process emits a program database (.pdb) file that contains debugging information about your app. The file is useful primarily for debugging exceptions. You can choose not to package it with your application's files. You should, however, save it in the event that you want to debug the Release build of your app. - -Deploy the published files in any way you like. For example, you can package them in a Zip file, use a simple `copy` command, or deploy them with any installation package of your choice. - -The following is the complete *csproj* file for this project. - -```xml - - - Exe - netcoreapp2.1 - - -``` - -In addition, Visual Studio creates a separate publishing profile (\*.pubxml) for each platform that you target. For example, the file for our linux profile (linux.pubxml) appears as follows: - -```xml - - - - - FileSystem - Release - Any CPU - netcoreapp2.1 - bin\Release\netcoreapp2.1\publish\linux - win-x86 - true - <_IsPortable>false - - -``` - ---- - -## Self-contained deployment with third-party dependencies - -Deploying a self-contained deployment with one or more third-party dependencies involves adding the dependencies. The following additional steps are required before you can build your app: - -1. Use the **NuGet Package Manager** to add a reference to a NuGet package to your project; and if the package is not already available on your system, install it. To open the package manager, select **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution**. - -1. Confirm that your third-party dependencies (for example, `Newtonsoft.Json`) are installed on your system and, if they aren't, install them. The **Installed** tab lists NuGet packages installed on your system. If `Newtonsoft.Json` is not listed there, select the **Browse** tab and enter "Newtonsoft.Json" in the search box. Select `Newtonsoft.Json` and, in the right pane, select your project before selecting **Install**. - -1. If `Newtonsoft.Json` is already installed on your system, add it to your project by selecting your project in the right pane of the **Manage Packages for Solution** tab. - -The following is the complete *csproj* file for this project: - -# [Visual Studio 15.6 and earlier](#tab/vs156) - -```xml - - - Exe - netcoreapp2.1 - win-x64;osx-x64 - - - - - -``` - -# [Visual Studio 15.7 and later](#tab/vs157) - -```xml - - - Exe - netcoreapp2.1 - - - - - -``` - ---- - -When you deploy your application, any third-party dependencies used in your app are also contained with your application files. Third-party libraries aren't required on the system on which the app is running. - -You can only deploy a self-contained deployment with a third-party library to platforms supported by that library. This is similar to having third-party dependencies with native dependencies in your framework-dependent deployment, where the native dependencies won't exist on the target platform unless they were previously installed there. - -## See also - -- [.NET Core Application Deployment](index.md) -- [.NET Core Runtime Identifier (RID) catalog](../rid-catalog.md) diff --git a/docs/core/deploying/publish-with-cli.md b/docs/core/deploying/publish-with-cli.md new file mode 100644 index 0000000000000..58db106812094 --- /dev/null +++ b/docs/core/deploying/publish-with-cli.md @@ -0,0 +1,255 @@ +--- +title: Publish apps with the .NET CLI +description: Learn to publish a .NET application using the .NET CLI commands. +author: adegeo +ms.author: adegeo +ms.date: 08/07/2025 +ms.custom: updateeachrelease +dev_langs: + - "csharp" + - "vb" +--- + +# Publish .NET apps with the .NET CLI + +This article demonstrates how you can publish your .NET application from the command line. .NET provides several ways to publish your applications. Framework-dependent deployment produces a cross-platform .dll file that uses the locally installed .NET runtime. Framework-dependent executable produces a platform-specific executable that uses the locally installed .NET runtime. Self-contained executable produces a platform-specific executable and includes a local copy of the .NET runtime. + +For an overview of these publishing modes, see [.NET Application Deployment](index.md). + +Looking for some quick help on using the CLI? The following table shows some examples of how to publish your app. You can specify the target framework with the `-f ` parameter or by editing the project file. For more information, see [Publishing basics](#publishing-basics). + +| Publish Mode | Command | +|-------------------------------------------------------------------|----------------------------------------------------------------| +| [Framework-dependent deployment](#framework-dependent-deployment) | `dotnet publish -c Release [-r ] -p:UseAppHost=false` | +| [Framework-dependent executable](#framework-dependent-executable) | `dotnet publish -c Release [-r ]`
`dotnet publish -c Release [-r ] --self-contained false`
| +| [Self-contained deployment](#self-contained-deployment) | `dotnet publish -c Release [-r ] --self-contained true` | +| [Single-file deployment](#single-file-deployment) | `dotnet publish -c Release [-r ] -p:PublishSingleFile=true` | +| [Native AOT deployment](#native-aot-deployment) | `dotnet publish -c Release [-r ] -p:PublishAot=true` | +| [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | + +> [!NOTE] +> The `-c Release` parameter isn't required and is only provided as a reminder to publish the **Release** build of your app. + +## Publishing basics + +The [``](../project-sdk/msbuild-props.md#targetframework) setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. The TFM specified in this setting is the default target used by the [`dotnet publish`](../tools/dotnet-publish.md) command. + +If you want to target more than one framework, you can set the [``](../project-sdk/msbuild-props.md#targetframeworks) setting to multiple TFM values, separated by a semicolon. When you build your app, a build is produced for each target framework. However, when you publish your app, you must specify the target framework with the `dotnet publish -f ` command. + +The default **BUILD-CONFIGURATION** mode is **Release** unless changed with the `-c` parameter. + +The default output directory of the [`dotnet publish`](../tools/dotnet-publish.md) command is `./bin///publish/`. For example, `dotnet publish -c Release -f net9.0` publishes to `./bin/Release/net9.0/publish/`. However, you can opt in to a simplified output path and folder structure for all build outputs. For more information, see [Artifacts output layout](../sdk/artifacts-output.md). + +### Native dependencies + +If your app has native dependencies, it might not run on a different operating system. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. + +Consider also, if a library you referenced has a native dependency, your app might not run on every platform. However, it's possible a NuGet package you're referencing includes platform-specific versions to handle the required native dependencies for you. + +To insure that your app is published with its native dependencies, use the `dotnet publish -r ` switch to publish your app for a specific platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + +More information about platform-specific binaries is covered in the [Framework-dependent executable](#framework-dependent-executable) and [Self-contained deployment](#self-contained-deployment) sections. + +## Sample app + +You can use the following app to explore the publishing commands. The app is created by running the following commands in your terminal: + +```dotnetcli +dotnet new console -o apptest1 +cd apptest1 +dotnet add package Figgle.Fonts +``` + +Change the `Program.cs` or `Program.vb` code to the following snippet: + +```csharp +using Figgle.Fonts; + +Console.WriteLine(FiggleFonts.Standard.Render("Hello, World!")); +``` + +```vb +Imports System +Imports Figgle.Fonts + +Module Program + Sub Main(args As String()) + Console.WriteLine(FiggleFonts.Standard.Render("Hello World!")) + End Sub +End Module +``` + +When you run the app ([`dotnet run`](../tools/dotnet-run.md)), the following output is displayed: + +```terminal + _ _ _ _ __ __ _ _ _ + | | | | ___| | | ___ \ \ / /__ _ __| | __| | | + | |_| |/ _ \ | |/ _ \ \ \ /\ / / _ \| '__| |/ _` | | + | _ | __/ | | (_) | \ V V / (_) | | | | (_| |_| + |_| |_|\___|_|_|\___( ) \_/\_/ \___/|_| |_|\__,_(_) + |/ +``` + +## Framework-dependent deployment + +When you publish your app as a framework-dependent deployment (FDD), a `.dll` file is created in the `./bin///publish/` folder. To run your app, navigate to the output folder and use the `dotnet .dll` command. + +Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. + +Publishing an FDD creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). + +| Publish Mode | Command | +|--------------------------------|-------------------------------------------------------------| +| Framework-dependent deployment | `dotnet publish -c Release -p:UseAppHost=false` | + +## Framework-dependent executable + +Framework-dependent executable (FDE) is the default mode for the basic `dotnet publish` command. You don't need to specify any other parameters, as long as you want to target the current operating system. + +In this mode, a platform-specific executable host is created to host your cross-platform app. This mode is similar to FDD, as FDD requires a host in the form of the `dotnet` command. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. + +Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. + +Publishing an FDE creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). + +| Publish Mode | Command | +|--------------------------------|-------------------------------------------------------------| +| Framework-dependent executable | `dotnet publish -c Release -r --self-contained false`
`dotnet publish -c Release` | + +Whenever you use the `-r` switch, the output folder path changes to: `./bin////publish/` + +If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 --self-contained false`. This command creates the following executable: `./bin/Debug/net9.0/win-x64/publish/apptest1.exe` + +> [!NOTE] +> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). + +### Configure .NET install search behavior + +In .NET 9 and later versions, you can configure the .NET installation search paths of the published executable via the [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch) and [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) properties. + +`AppHostDotNetSearch` allows specifying one or more locations where the executable looks for a .NET installation: + +- `AppLocal`: app executable's folder +- `AppRelative`: path relative to the app executable +- `EnvironmentVariables`: value of [`DOTNET_ROOT[_]`](../tools/dotnet-environment-variables.md#dotnet_root-dotnet_rootx86-dotnet_root_x86-dotnet_root_x64) environment variables +- `Global`: [registered](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-custom-location) and [default](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-default-location) global install locations + +`AppHostRelativeDotNet` specifies the path relative to the executable that's searched when `AppHostDotNetSearch` contains `AppRelative`. + +For more information, see [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch), [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) and [install location options in apphost](https://github.com/dotnet/designs/blob/main/proposed/apphost-embed-install-location.md). + +## Self-contained deployment + +When you publish a self-contained deployment (SCD), the .NET SDK creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the native dependencies of .NET (for example, for [.NET 8 on Linux](https://github.com/dotnet/core/blob/main/release-notes/8.0/linux-packages.md)). These dependencies must be present on the system before the app runs. + +Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). + +You must use the following switches with the `dotnet publish` command to publish an SCD: + +- `-r ` + + This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. + +- `--self-contained true` + + This switch tells the .NET SDK to create an executable as an SCD. + +| Publish Mode | Command | +|--------------------------------|-------------------------------------------------------------| +| Self-contained deployment | `dotnet publish -c Release -r --self-contained true` | + +> [!TIP] +> +> - You can reduce the total size of compatible self-contained apps by [publishing trimmed](trimming/trim-self-contained.md). This enables the trimmer to remove parts of the framework and referenced assemblies that aren't on any code path or potentially referenced in [runtime reflection](../../csharp/advanced-topics/reflection-and-attributes/index.md). See [trimming incompatibilities](./trimming/incompatibilities.md) to determine if trimming makes sense for your application. +> - You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). + +## Single-file deployment + +When you publish your app as a single-file deployment, all application-dependent files are bundled into a single binary. This deployment model is available for both framework-dependent and self-contained applications, providing an attractive option to deploy and distribute your application as a single file. + +Single-file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth. Runtime configuration files, such as _\*.runtimeconfig.json_ and _\*.deps.json_, are included in the single file. + +The size of a single file in a self-contained application is large since it includes the runtime and framework libraries. You can combine single-file deployment with other publish options like [trimming](trimming/trim-self-contained.md) and [ReadyToRun](#readytorun-deployment) to optimize the deployment. + +You must use the following switches with the `dotnet publish` command to publish a single-file app: + +- `-r ` + + This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. + +- `-p:PublishSingleFile=true` + + This switch tells the .NET SDK to bundle the app into a single file. + +| Publish Mode | Command | +|-----------------------|-------------------------------------------------------------| +| Single-file deployment | `dotnet publish -c Release -r -p:PublishSingleFile=true` | + +If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 -p:PublishSingleFile=true`. This command creates a single executable file in the `./bin/Debug/net9.0/win-x64/publish/` folder. + +For more information about single-file deployment, see [Single-file deployment](single-file/overview.md). + +## Native AOT deployment + +When you publish your app as Native AOT, your application is ahead-of-time (AOT) compiled to native code. Native AOT apps are [self-contained](index.md#publish-self-contained) and have faster startup time and smaller memory footprints. These apps can run on machines that don't have the .NET runtime installed. + +Native AOT apps don't use a just-in-time (JIT) compiler when the application runs. The ahead-of-time compiler compiles IL to native code at publish time. Native AOT applications target a specific runtime environment, such as Linux x64 or Windows x64. + +The benefit of Native AOT is most significant for workloads with a high number of deployed instances, such as cloud infrastructure and hyper-scale services. + +You must use the following switches with the `dotnet publish` command to publish a Native AOT app: + +- `-r ` + + This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. + +- `-p:PublishAot=true` + + This switch tells the .NET SDK to compile the app with Native AOT. + +| Publish Mode | Command | +|-----------------------|-------------------------------------------------------------| +| Native AOT deployment | `dotnet publish -c Release -r -p:PublishAot=true` | + +> [!NOTE] +> Native AOT has specific requirements and limitations. Not all .NET features are supported in Native AOT. For detailed information about prerequisites, limitations, and compatibility, see [Native AOT deployment](native-aot/index.md). + +If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 -p:PublishAot=true`. This command creates a native executable in the `./bin/Debug/net9.0/win-x64/publish/` folder. + +For more information about Native AOT deployment, see [Native AOT deployment overview](native-aot/index.md). + +## ReadyToRun deployment + +When you publish your app with ReadyToRun compilation, your application assemblies are compiled as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation that improves startup performance by reducing the amount of work the just-in-time (JIT) compiler needs to do as your application loads. + +ReadyToRun binaries contain both intermediate language (IL) code and the native version of the same code. While R2R binaries are larger than regular assemblies, they provide better startup performance. ReadyToRun is only available when you publish an app that targets specific runtime environments (RID) such as Linux x64 or Windows x64. + +The startup improvement applies not only to application startup, but also to the first use of any code in the application. For instance, ReadyToRun can reduce the response latency of the first use of Web API in an ASP.NET application. + +You must use the following switches with the `dotnet publish` command to publish a ReadyToRun app: + +- `-r ` + + This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. + +- `-p:PublishReadyToRun=true` + + This switch tells the .NET SDK to compile assemblies with ReadyToRun. + +| Publish Mode | Command | +|-----------------------|-------------------------------------------------------------| +| ReadyToRun deployment | `dotnet publish -c Release -r -p:PublishReadyToRun=true` | + +> [!NOTE] +> ReadyToRun compilation increases the size of your assemblies. The size of an assembly typically grows to between two to three times larger. This increase in physical size might reduce performance of loading the assembly from disk and increase working set of the process. + +If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 -p:PublishReadyToRun=true`. This command creates ReadyToRun compiled assemblies in the `./bin/Debug/net9.0/win-x64/publish/` folder. + +ReadyToRun can be combined with other publish options like [single-file deployment](#single-file-deployment) and [trimming](trimming/trim-self-contained.md) for more optimizations. + +For more information about ReadyToRun deployment, see [ReadyToRun compilation](ready-to-run.md). + +## See also + +- [.NET Application Deployment Overview](index.md)y +- [.NET Runtime Identifier (RID) catalog](../rid-catalog.md) diff --git a/docs/core/deploying/publish-with-vs.md b/docs/core/deploying/publish-with-vs.md new file mode 100644 index 0000000000000..c908e8947bda3 --- /dev/null +++ b/docs/core/deploying/publish-with-vs.md @@ -0,0 +1,202 @@ +--- +title: Publish apps with Visual Studio +description: Learn to publish a .NET application using Visual Studio. +author: adegeo +ms.author: adegeo +ms.date: 08/08/2025 +ms.custom: vs-dotnet, updateeachrelease +dev_langs: + - "csharp" + - "vb" +--- + +# Publish .NET apps with Visual Studio + +This article demonstrates how you can publish your .NET application using Visual Studio. .NET provides several ways to publish your applications. Framework-dependent deployment produces a cross-platform .dll file that uses the locally installed .NET runtime. Framework-dependent executable produces a platform-specific executable that uses the locally installed .NET runtime. Self-contained executable produces a platform-specific executable and includes a local copy of the .NET runtime. + +For an overview of these publishing modes, see [.NET Application Deployment](index.md). + +Looking for some quick help on using Visual Studio? The following table shows some examples of how to publish your app using Visual Studio publishing profiles: + +| Publish Mode | Visual Studio Configuration | +|-------------------------------------------------------------------|----------------------------------------------------------------| +| [Framework-dependent deployment](#framework-dependent-deployment) | Set **Deployment Mode** to **Framework-dependent** and **Produce single file** to unchecked | +| [Framework-dependent executable](#framework-dependent-executable) | Set **Deployment Mode** to **Framework-dependent** (default) | +| [Self-contained deployment](#self-contained-deployment) | Set **Deployment Mode** to **Self-contained** | +| [Single-file deployment](#single-file-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Produce single file** to checked | +| [ReadyToRun deployment](#readytorun-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Enable ReadyToRun compilation** to checked | + +## Publishing basics + +The [``](../project-sdk/msbuild-props.md#targetframework) setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. The TFM specified in this setting is the default target used when you publish from Visual Studio. + +If you want to target more than one framework, you can set the [``](../project-sdk/msbuild-props.md#targetframeworks) setting to multiple TFM values, separated by a semicolon. When you build your app, a build is produced for each target framework. However, when you publish your app from Visual Studio, you must create separate publishing profiles for each target framework. + +The default **BUILD-CONFIGURATION** mode is **Release** when publishing from Visual Studio. + +### Native dependencies + +If your app has native dependencies, it might not run on a different operating system. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. + +Consider also, if a library you referenced has a native dependency, your app might not run on every platform. However, it's possible a NuGet package you're referencing includes platform-specific versions to handle the required native dependencies for you. + +To ensure that your app is published with its native dependencies, use the **Target Runtime** setting in Visual Studio to publish your app for a specific platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + +More information about platform-specific binaries is covered in the [Framework-dependent executable](#framework-dependent-executable) and [Self-contained deployment](#self-contained-deployment) sections. + +## Sample app + +You can use the following app to explore the publishing options in Visual Studio. The app is created by doing the following in Visual Studio: + +01. Select **File** > **New** > **Project**. +01. In the **Create a new project** dialog, search for "console" and select **Console App**. +01. Select **Next**. +01. Enter a project name, such as "AppTest1", and select **Next**. +01. Choose the latest framework version and select **Create**. +01. In **Solution Explorer**, right-click on the project and select **Manage NuGet Packages**. +01. Search for "Figgle.Fonts" and install the package. + +Change the `Program.cs` or `Program.vb` code to the following snippet: + +```csharp +using Figgle.Fonts; + +Console.WriteLine(FiggleFonts.Standard.Render("Hello, World!")); +``` + +```vb +Imports System +Imports Figgle.Fonts + +Module Program + Sub Main(args As String()) + Console.WriteLine(FiggleFonts.Standard.Render("Hello World!")) + End Sub +End Module +``` + +When you run the app (**Debug** > **Start Debugging** or press **F5**), the following output is displayed: + +```terminal + _ _ _ _ __ __ _ _ _ + | | | | ___| | | ___ \ \ / /__ _ __| | __| | | + | |_| |/ _ \ | |/ _ \ \ \ /\ / / _ \| '__| |/ _` | | + | _ | __/ | | (_) | \ V V / (_) | | | | (_| |_| + |_| |_|\___|_|_|\___( ) \_/\_/ \___/|_| |_|\__,_(_) + |/ +``` + +## Framework-dependent deployment + +When you publish your app as a framework-dependent deployment (FDD), a `.dll` file is created in the publish output folder. To run your app, navigate to the output folder and use the `dotnet .dll` command. + +Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. + +Publishing an FDD creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). + +To publish a framework-dependent deployment from Visual Studio: + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Framework-dependent**. +01. Uncheck **Produce single file**. +01. Set **Target Runtime** to **Portable** (or leave blank). +01. Click **Save** and then **Publish**. + +## Framework-dependent executable + +Framework-dependent executable (FDE) is the default mode when you publish from Visual Studio. You don't need to specify any other parameters, as long as you want to target the current operating system. + +In this mode, a platform-specific executable host is created to host your cross-platform app. This mode is similar to FDD, as FDD requires a host in the form of the `dotnet` command. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. + +Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. + +Publishing an FDE creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). + +To publish a framework-dependent executable from Visual Studio: + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Framework-dependent** (this is the default). +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Click **Save** and then **Publish**. + +> [!NOTE] +> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). + +## Self-contained deployment + +When you publish a self-contained deployment (SCD), Visual Studio creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the native dependencies of .NET. These dependencies must be present on the system before the app runs. + +Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). + +To publish a self-contained deployment from Visual Studio: + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Click **Save** and then **Publish**. + +> [!TIP] +> +> - You can reduce the total size of compatible self-contained apps by [publishing trimmed](trimming/trim-self-contained.md). This enables the trimmer to remove parts of the framework and referenced assemblies that aren't on any code path or potentially referenced in [runtime reflection](../../csharp/advanced-topics/reflection-and-attributes/index.md). See [trimming incompatibilities](trimming/incompatibilities.md) to determine if trimming makes sense for your application. +> - You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). + +## Single-file deployment + +When you publish your app as a single-file deployment, all application-dependent files are bundled into a single binary. This deployment model is available for both framework-dependent and self-contained applications, providing an attractive option to deploy and distribute your application as a single file. + +Single-file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth. Runtime configuration files, such as *\*.runtimeconfig.json* and *\*.deps.json*, are included in the single file. + +The size of a single file in a self-contained application is large since it includes the runtime and framework libraries. You can combine single-file deployment with other publish options like [trimming](trimming/trim-self-contained.md) and [ReadyToRun](#readytorun-deployment) to optimize the deployment. + +To publish a single-file deployment from Visual Studio: + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Check **Produce single file**. +01. Click **Save** and then **Publish**. + +For more information about single-file deployment, see [Single-file deployment](single-file/overview.md). + +## ReadyToRun deployment + +When you publish your app with ReadyToRun compilation, your application assemblies are compiled as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation that improves startup performance by reducing the amount of work the just-in-time (JIT) compiler needs to do as your application loads. + +ReadyToRun binaries contain both intermediate language (IL) code and the native version of the same code. While R2R binaries are larger than regular assemblies, they provide better startup performance. ReadyToRun is only available when you publish an app that targets specific runtime environments (RID) such as Linux x64 or Windows x64. + +The startup improvement applies not only to application startup, but also to the first use of any code in the application. For instance, ReadyToRun can reduce the response latency of the first use of Web API in an ASP.NET application. + +To publish a ReadyToRun deployment from Visual Studio: + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Check **Enable ReadyToRun compilation**. +01. Click **Save** and then **Publish**. + +> [!NOTE] +> ReadyToRun compilation increases the size of your assemblies. The size of an assembly typically grows to between two to three times larger. This increase in physical size might reduce performance of loading the assembly from disk and increase working set of the process. + +ReadyToRun can be combined with other publish options like [single-file deployment](#single-file-deployment) and [trimming](trimming/trim-self-contained.md) for more optimizations. + +For more information about ReadyToRun deployment, see [ReadyToRun compilation](ready-to-run.md). + +## See also + +- [.NET Application Deployment](index.md) +- [.NET Runtime Identifier (RID) catalog](../rid-catalog.md) From 62c36ba2a551f3ae1a25c3406bea9ca0cbfd00c2 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 8 Aug 2025 13:01:37 -0700 Subject: [PATCH 06/29] Redirect, TOC, links --- .openpublishing.redirection.core.json | 8 ++++++++ docs/core/deploying/index.md | 4 ++-- docs/core/deploying/single-file/overview.md | 8 ++++---- docs/core/deploying/trimming/trim-self-contained.md | 8 ++++---- docs/core/tools/dotnet-publish.md | 8 ++++---- docs/core/tutorials/publishing-with-visual-studio-code.md | 6 +++--- docs/core/tutorials/publishing-with-visual-studio.md | 6 +++--- docs/core/whats-new/dotnet-9/runtime.md | 2 +- docs/navigate/devops-testing/toc.yml | 6 +++--- docs/navigate/tools-diagnostics/index.yml | 2 +- 10 files changed, 33 insertions(+), 25 deletions(-) diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index f2867967dd53f..e9dad536c1222 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -386,6 +386,14 @@ "source_path_from_root": "/docs/core/deploying/applications.md", "redirect_url": "/dotnet/core/deploying/index" }, + { + "source_path_from_root": "docs/core/deploying/deploy-with-cli.md", + "redirect_url": "/dotnet/core/deploying/publish-with-cli" + }, + { + "source_path_from_root": "docs/core/deploying/deploy-with-vs.md", + "redirect_url": "/dotnet/core/deploying/publish-with-vs" + }, { "source_path_from_root": "/docs/core/deploying/fixing-warnings.md", "redirect_url": "/dotnet/core/deploying/trimming/fixing-warnings", diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 60074d15a3cf3..c2c9393e4fb4b 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -187,7 +187,7 @@ dotnet publish -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true ## See also -- [Deploying .NET Apps with .NET CLI.](deploy-with-cli.md) -- [Deploying .NET Apps with Visual Studio.](deploy-with-vs.md) +- [Deploying .NET Apps with .NET CLI.](publish-with-cli.md) +- [Deploying .NET Apps with Visual Studio.](publish-with-vs.md) - [.NET Runtime Identifier (RID) catalog.](../rid-catalog.md) - [Select the .NET version to use.](../versions/selection.md) diff --git a/docs/core/deploying/single-file/overview.md b/docs/core/deploying/single-file/overview.md index 2034c312ad644..6a384628cd513 100644 --- a/docs/core/deploying/single-file/overview.md +++ b/docs/core/deploying/single-file/overview.md @@ -75,7 +75,7 @@ Publish a single file application using the [dotnet publish](../../tools/dotnet- dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained false ``` -For more information, see [Publish .NET Core apps with .NET CLI](../deploy-with-cli.md). +For more information, see [Publish .NET Core apps with .NET CLI](../publish-with-cli.md). # [Visual Studio](#tab/vs) @@ -105,7 +105,7 @@ Visual Studio creates reusable publishing profiles that control how your applica 1. Choose **Publish** to publish your app as a single file. -For more information, see [Publish .NET Core apps with Visual Studio](../deploy-with-vs.md). +For more information, see [Publish .NET Core apps with Visual Studio](../publish-with-vs.md). --- @@ -236,6 +236,6 @@ Single file apps can be inspected using the [ILSpy tool](https://ilspy.net/). Th ## See also - [.NET Core application deployment](../index.md) -- [Publish .NET apps with .NET CLI](../deploy-with-cli.md) -- [Publish .NET Core apps with Visual Studio](../deploy-with-vs.md) +- [Publish .NET apps with .NET CLI](../publish-with-cli.md) +- [Publish .NET Core apps with Visual Studio](../publish-with-vs.md) - [`dotnet publish` command](../../tools/dotnet-publish.md) diff --git a/docs/core/deploying/trimming/trim-self-contained.md b/docs/core/deploying/trimming/trim-self-contained.md index 2328573774638..12aa2d7d6f89e 100644 --- a/docs/core/deploying/trimming/trim-self-contained.md +++ b/docs/core/deploying/trimming/trim-self-contained.md @@ -51,7 +51,7 @@ Trimming is only supported for self-contained apps. `dotnet publish -r win-x64 -p:PublishTrimmed=true` -For more information, see [Publish .NET apps with .NET CLI](../deploy-with-cli.md). +For more information, see [Publish .NET apps with .NET CLI](../publish-with-cli.md). ### Publish with Visual Studio @@ -67,11 +67,11 @@ For more information, see [Publish .NET apps with .NET CLI](../deploy-with-cli.m :::image type="content" source="../media/trim-self-contained/vs-publish-trimmed.png" alt-text="Visual studio publish page with Publish Trimmed selected."::: -For more information, see [Publish .NET Core apps with Visual Studio](../deploy-with-vs.md). +For more information, see [Publish .NET Core apps with Visual Studio](../publish-with-vs.md). ## See also - [.NET Core application deployment](../index.md). -- [Publish .NET apps with .NET CLI](../deploy-with-cli.md). -- [Publish .NET Core apps with Visual Studio](../deploy-with-vs.md). +- [Publish .NET apps with .NET CLI](../publish-with-cli.md). +- [Publish .NET Core apps with Visual Studio](../publish-with-vs.md). - [dotnet publish command](../../tools/dotnet-publish.md). diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index ea8e7a14f3342..fc38e34a42683 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -38,7 +38,7 @@ dotnet publish -h|--help - A *.runtimeconfig.json* file that specifies the shared runtime that the application expects, as well as other configuration options for the runtime (for example, garbage collection type). - The application's dependencies, which are copied from the NuGet cache into the output folder. -The `dotnet publish` command's output is ready for deployment to a hosting system (for example, a server, PC, Mac, laptop) for execution. It's the only officially supported way to prepare the application for deployment. Depending on the type of deployment that the project specifies, the hosting system may or may not have the .NET shared runtime installed on it. For more information, see [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md). +The `dotnet publish` command's output is ready for deployment to a hosting system (for example, a server, PC, Mac, laptop) for execution. It's the only officially supported way to prepare the application for deployment. Depending on the type of deployment that the project specifies, the hosting system may or may not have the .NET shared runtime installed on it. For more information, see [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md). ### Implicit restore @@ -196,7 +196,7 @@ For more information, see the following resources: - **`--sc|--self-contained [true|false]`** - Publishes the .NET runtime with your application so the runtime doesn't need to be installed on the target machine. Default is `true` if a runtime identifier is specified and the project is an executable project (not a library project). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md). + Publishes the .NET runtime with your application so the runtime doesn't need to be installed on the target machine. Default is `true` if a runtime identifier is specified and the project is an executable project (not a library project). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md). If this option is used without specifying `true` or `false`, the default is `true`. In that case, don't put the solution or project argument immediately after `--self-contained`, because `true` or `false` is expected in that position. @@ -210,7 +210,7 @@ For more information, see the following resources: - **`-r|--runtime `** - Publishes the application for a given runtime. For a list of Runtime Identifiers (RIDs), see the [RID catalog](../rid-catalog.md). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md). If you use this option, use `--self-contained` or `--no-self-contained` also. + Publishes the application for a given runtime. For a list of Runtime Identifiers (RIDs), see the [RID catalog](../rid-catalog.md). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md). If you use this option, use `--self-contained` or `--no-self-contained` also. [!INCLUDE [tl](../../../includes/cli-tl.md)] @@ -271,7 +271,7 @@ For more information, see the following resources: ## See also - [.NET application publishing overview](../deploying/index.md) -- [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md) +- [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md) - [Target frameworks](../../standard/frameworks.md) - [Runtime Identifier (RID) catalog](../rid-catalog.md) - [Containerize a .NET app with dotnet publish](../containers/sdk-publish.md) diff --git a/docs/core/tutorials/publishing-with-visual-studio-code.md b/docs/core/tutorials/publishing-with-visual-studio-code.md index e724d0e997a16..40757b129fc33 100644 --- a/docs/core/tutorials/publishing-with-visual-studio-code.md +++ b/docs/core/tutorials/publishing-with-visual-studio-code.md @@ -62,11 +62,11 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.dll* - This is the [framework-dependent deployment](../deploying/deploy-with-cli.md#framework-dependent-deployment) version of the application. To run this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. + This is the [framework-dependent deployment](../deploying/publish-with-cli.md#framework-dependent-deployment) version of the application. To run this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. - *HelloWorld.exe* (*HelloWorld* on Linux or macOS.) - This is the [framework-dependent executable](../deploying/deploy-with-cli.md#framework-dependent-executable) version of the application. The file is operating-system-specific. + This is the [framework-dependent executable](../deploying/publish-with-cli.md#framework-dependent-executable) version of the application. The file is operating-system-specific. - *HelloWorld.pdb* (optional for deployment) @@ -99,7 +99,7 @@ In the following steps, you'll look at the files created by the publish process. ## Additional resources - [.NET application deployment](../deploying/index.md) -- [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md) +- [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md) - [`dotnet publish`](../tools/dotnet-publish.md) - [Use the .NET SDK in continuous integration (CI) environments](../../devops/dotnet-cli-and-continuous-integration.md) diff --git a/docs/core/tutorials/publishing-with-visual-studio.md b/docs/core/tutorials/publishing-with-visual-studio.md index d25531e3a53fd..07990fbde32d5 100644 --- a/docs/core/tutorials/publishing-with-visual-studio.md +++ b/docs/core/tutorials/publishing-with-visual-studio.md @@ -64,11 +64,11 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.dll* - This is the [framework-dependent deployment](../deploying/deploy-with-cli.md#framework-dependent-deployment) version of the application. To execute this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. + This is the [framework-dependent deployment](../deploying/publish-with-cli.md#framework-dependent-deployment) version of the application. To execute this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. - *HelloWorld.exe* - This is the [framework-dependent executable](../deploying/deploy-with-cli.md#framework-dependent-executable) version of the application. To run it, enter `HelloWorld.exe` at a command prompt. The file is operating-system-specific. + This is the [framework-dependent executable](../deploying/publish-with-cli.md#framework-dependent-executable) version of the application. To run it, enter `HelloWorld.exe` at a command prompt. The file is operating-system-specific. - *HelloWorld.pdb* (optional for deployment) @@ -103,7 +103,7 @@ In the following steps, you'll look at the files created by the publish process. ## Additional resources - [.NET application deployment](../deploying/index.md) -- [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md) +- [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md) - [`dotnet publish`](../tools/dotnet-publish.md) - [Tutorial: Publish a .NET console application using Visual Studio Code](publishing-with-visual-studio-code.md) - [Use the .NET SDK in continuous integration (CI) environments](../../devops/dotnet-cli-and-continuous-integration.md) diff --git a/docs/core/whats-new/dotnet-9/runtime.md b/docs/core/whats-new/dotnet-9/runtime.md index c23d90899ee93..3e6c57bd0616c 100644 --- a/docs/core/whats-new/dotnet-9/runtime.md +++ b/docs/core/whats-new/dotnet-9/runtime.md @@ -74,7 +74,7 @@ CET imposes some limitations on CET-enabled processes and can result in a small ## .NET install search behavior -.NET apps can now be configured for how they should [search for the .NET runtime](../../deploying/deploy-with-cli.md#configure-net-install-search-behavior). This capability can be used with private runtime installations or to more strongly control the execution environment. +.NET apps can now be configured for how they should [search for the .NET runtime](../../deploying/publish-with-cli.md#configure-net-install-search-behavior). This capability can be used with private runtime installations or to more strongly control the execution environment. ## Performance improvements diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml index a2b48a204ac31..b7af5402187a2 100644 --- a/docs/navigate/devops-testing/toc.yml +++ b/docs/navigate/devops-testing/toc.yml @@ -275,14 +275,14 @@ items: href: ../../core/testing/unit-testing-code-coverage.md - name: Live unit test with Visual Studio href: /visualstudio/test/live-unit-testing-start?toc=/dotnet/navigate/devops-testing/toc.json&bc=/dotnet/breadcrumb/toc.json - - name: Deployment models + - name: Publishing items: - name: Overview href: ../../core/deploying/index.md - name: Deploy apps with Visual Studio - href: ../../core/deploying/deploy-with-vs.md + href: ../../core/deploying/publish-with-vs.md - name: Publish apps with the CLI - href: ../../core/deploying/deploy-with-cli.md + href: ../../core/deploying/publish-with-cli.md - name: Create a NuGet package with the CLI href: ../../core/deploying/creating-nuget-packages.md - name: Self-contained deployment runtime roll forward diff --git a/docs/navigate/tools-diagnostics/index.yml b/docs/navigate/tools-diagnostics/index.yml index 7baf8b595fe8e..d0a7bf9c18896 100644 --- a/docs/navigate/tools-diagnostics/index.yml +++ b/docs/navigate/tools-diagnostics/index.yml @@ -67,7 +67,7 @@ landingContent: - linkListType: deploy links: - text: Publish apps - url: ../../core/deploying/deploy-with-cli.md + url: ../../core/deploying/publish-with-cli.md # Card - title: Global and local tools From 533a5c6e86ebc6579825ca9227305b09ae092a4e Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 07:00:11 -0700 Subject: [PATCH 07/29] Temp --- .github/copilot-instructions.md | 98 ++++++++++++++----------- docs/core/deploying/publish-with-cli.md | 18 +---- docs/core/deploying/publish-with-vs.md | 23 ++---- 3 files changed, 66 insertions(+), 73 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c48ae856aeb87..eccc7c1c61c77 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,41 +1,57 @@ -When writing documentation, follow the following guidelines: - -Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework). - -Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/). - -Headings should be in sentence case, not title case. Don't use gerunds in titles. - -Use the active voice whenever possible, and second person to address the reader directly. - -Use a conversational tone with contractions. - -Be concise. - -Break up long sentences. - -Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value." - -Do not use "we" or "our" to refer to the authors of the documentation. - -Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method." - -Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception." - -Use the Oxford comma in lists of three or more items. - -Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists. - -Use **bold** when referring to UI elements. Use `code style` for file names and folders, custom types, and other text that should never be localized. - -Put raw URLs within angle brackets. - -Include links to related topics and resources where appropriate. Use relative links if the target file lives in this repo. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link. - -When mentioning APIs, use cross-references to the API documentation. These links are formatted as . You can find the API doc ID in the XML files in the https://github.com/dotnet/dotnet-api-docs repository. For types, the doc ID is the value of the `Value` attribute of the `` element where the `Language` attribute value is `DocId`. For other (member) APIs, the doc ID is the value of the `Value` attribute of the `` element where the `Language` attribute value is `DocId`. Omit the first two characters of the DocId. For example, the xref link for System.String is . - -If you're assigned a GitHub issue that's labeled "breaking-change", include the prompt directions in the .github/prompts/breaking-change.md file in this repo. - -If you include a code snippet that's more than 6 lines long, put it in a separate .cs file in a folder named "snippets" in the same folder as the document. Within the "snippets" folder, add a new directory with the name of the document. For example, if the document is named "my-doc.md", create a folder named "snippets/my-doc" folder. Also add a simple .csproj file to the same directory that targets the latest version of .NET. It can be a library or executable project. - -If you're adding a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name. +# .NET Documentation Guidelines + +## Terminology +- All .NET content refers to modern .NET (not .NET Framework). + +## Writing Style +Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics: + +### Voice and Tone +- Active voice, second person addressing reader directly +- Conversational tone with contractions +- Present tense for instructions/descriptions +- Imperative mood for instructions ("Call the method" not "You should call the method") +- Use "might" instead of "may" for possibility +- Avoid "we"/"our" referring to documentation authors + +### Structure and Format +- Sentence case headings (no gerunds in titles) +- Be concise, break up long sentences +- Oxford comma in lists +- Number all ordered list items as "01." (not sequential numbering like "1.", "2.", "3.", etc.) +- Complete sentences with proper punctuation in all list items +- Avoid "etc." or "and so on" - provide complete lists or use "for example" +- No consecutive headings without content between them + +### Formatting Conventions +- **Bold** for UI elements +- `Code style` for file names, folders, custom types, non-localizable text +- Raw URLs in angle brackets +- Use relative links for files in this repo +- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links + +## API References +Use cross-references: `` + +To find API doc IDs: +1. Check XML files in https://github.com/dotnet/dotnet-api-docs +2. For types: `Value` attribute of `` where `Language="DocId"` (omit first 2 characters) +3. For members: `Value` attribute of `` where `Language="DocId"` (omit first 2 characters) + +If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` + +Use the `url` value from results for manual links. + +## Code Snippets +For snippets >6 lines: +1. Create `./snippets/my-doc/language` folder in same directory as document (for a document named `my-doc.md`) where language is either vb (for visual basic) or cs (for c#) +1. Add snippet as separate code file +1. Include simple project file targeting latest .NET +1. All code should use the latest stable versions/features +1. Create examples in both C# and Visual Basic + +## File Naming +New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.) + +## Special Cases +- Breaking changes: Include directions from `.github/prompts/breaking-change.md` diff --git a/docs/core/deploying/publish-with-cli.md b/docs/core/deploying/publish-with-cli.md index 58db106812094..e7d9cfbe8b347 100644 --- a/docs/core/deploying/publish-with-cli.md +++ b/docs/core/deploying/publish-with-cli.md @@ -5,6 +5,7 @@ author: adegeo ms.author: adegeo ms.date: 08/07/2025 ms.custom: updateeachrelease +ai-usage: ai-assisted dev_langs: - "csharp" - "vb" @@ -62,22 +63,9 @@ dotnet add package Figgle.Fonts Change the `Program.cs` or `Program.vb` code to the following snippet: -```csharp -using Figgle.Fonts; +:::code language="csharp" source="./snippets/shared/publish/csharp/Program.cs"::: -Console.WriteLine(FiggleFonts.Standard.Render("Hello, World!")); -``` - -```vb -Imports System -Imports Figgle.Fonts - -Module Program - Sub Main(args As String()) - Console.WriteLine(FiggleFonts.Standard.Render("Hello World!")) - End Sub -End Module -``` +:::code language="vb" source="./snippets/shared/publish/vb/Program.vb"::: When you run the app ([`dotnet run`](../tools/dotnet-run.md)), the following output is displayed: diff --git a/docs/core/deploying/publish-with-vs.md b/docs/core/deploying/publish-with-vs.md index c908e8947bda3..fcfd552a87ab3 100644 --- a/docs/core/deploying/publish-with-vs.md +++ b/docs/core/deploying/publish-with-vs.md @@ -5,6 +5,7 @@ author: adegeo ms.author: adegeo ms.date: 08/08/2025 ms.custom: vs-dotnet, updateeachrelease +ai-usage: ai-generated dev_langs: - "csharp" - "vb" @@ -53,29 +54,17 @@ You can use the following app to explore the publishing options in Visual Studio 01. Select **Next**. 01. Enter a project name, such as "AppTest1", and select **Next**. 01. Choose the latest framework version and select **Create**. -01. In **Solution Explorer**, right-click on the project and select **Manage NuGet Packages**. +01. In **Solution Explorer**, right-click on the project and select **Manage NuGet Packages...**. +01. Select the **Browse** tab. 01. Search for "Figgle.Fonts" and install the package. Change the `Program.cs` or `Program.vb` code to the following snippet: -```csharp -using Figgle.Fonts; +:::code language="csharp" source="./snippets/shared/publish/csharp/Program.cs"::: -Console.WriteLine(FiggleFonts.Standard.Render("Hello, World!")); -``` - -```vb -Imports System -Imports Figgle.Fonts - -Module Program - Sub Main(args As String()) - Console.WriteLine(FiggleFonts.Standard.Render("Hello World!")) - End Sub -End Module -``` +:::code language="vb" source="./snippets/shared/publish/vb/Program.vb"::: -When you run the app (**Debug** > **Start Debugging** or press **F5**), the following output is displayed: +When you run the app ([`dotnet run`](../tools/dotnet-run.md)), the following output is displayed: ```terminal _ _ _ _ __ __ _ _ _ From 4c0928b3f2128d95f805485e40a0e462411b06e2 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 13:58:45 -0700 Subject: [PATCH 08/29] Almost final draft of rewriting the publishing intro article. --- docs/core/deploying/index.md | 369 ++++++++++++++++++++++++++--------- 1 file changed, 276 insertions(+), 93 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index c2c9393e4fb4b..5ca37afb02c8b 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -1,12 +1,17 @@ --- -title: Application publishing +title: .NET application publishing overview description: Learn about the ways to publish a .NET application. .NET can publish platform-specific or cross-platform apps. You can publish an app as self-contained or as framework-dependent. Each mode affects how a user runs your app. -ms.date: 07/01/2025 +author: adegeo +ms.author: adegeo +ms.date: 08/11/2025 +ms.custom: updateeachrelease +ai-usage: ai-assisted +zone_pivot_groups: development-environment-one --- # .NET application publishing overview -This article explains the different ways to publish a .NET application. It covers publishing modes, how to produce executables and cross-platform binaries, and the impact of each approach on deployment and runtime environments. +This article explains the different ways to publish a .NET application. It covers publishing modes, how to produce executables and cross-platform binaries, and the impact of each approach on deployment and runtime environments. You can publish .NET applications using either the .NET CLI or Visual Studio. ## What is publishing @@ -14,180 +19,358 @@ Publishing a .NET app means compiling source code to create an executable or bin ## Publishing modes -There are two primary ways to publish an app, and depending on how the app is deployed, one or the other is chosen. The choice largely depends on whether the deployment environment has the appropriate .NET Runtime installed. The two publishing modes are: +There are two primary ways to publish an app. The choice depends on both the deployment environment and the compilation options you want to use. Some factors that influence this decision include whether the deployment environment has the appropriate .NET Runtime installed and whether you need specific compilation features that require bundling the runtime with your app. The two publishing modes are: -- Publish *self-contained*\ +- **Publish self-contained**\ This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need to have the .NET runtime preinstalled. -- Publish *framework-dependent*\ +- **Publish framework-dependent**\ This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, and any app dependencies. The environment that runs the app must have a version of the .NET runtime installed that the app can use. An optional platform-specific executable can be produced. > [!IMPORTANT] > You specify the target platform with a runtime identifier (RID). For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). -The following table outlines the commands used to publish an app as framework-dependent or self-contained: +## Portable binaries -| Type | Command | -|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| -| [framework-dependent executable](#publish-framework-dependent) for the current platform. | [`dotnet publish`](../tools/dotnet-publish.md) | -| [framework-dependent executable](#publish-framework-dependent) for a specific platform. | [`dotnet publish -r `](../tools/dotnet-publish.md) | -| [framework-dependent binary](#publish-framework-dependent). | [`dotnet publish`](../tools/dotnet-publish.md) | -| [self-contained executable](#publish-self-contained). | [`dotnet publish -r --self-contained`](../tools/dotnet-publish.md) | +When you publish a .NET app, you can target a specific platform or create a portable binary. By default, even when creating a portable binary, .NET publishes a platform-specific executable alongside the portable DLL unless you explicitly disable this behavior. -For more information, see [.NET dotnet publish command](../tools/dotnet-publish.md). +The platform-specific executable is created because of the `UseAppHost` property, which defaults to `true`. To publish only the portable DLL without the platform-specific executable, set `UseAppHost` to `false` either on the command line (`-p:UseAppHost=false`) or as a project property. -## Produce an executable +The benefit of targeting a specific platform is that it can handle [native dependencies](#native-dependencies) that your app might require, ensuring compatibility with the target platform's specific requirements. -Executables aren't cross-platform; they're specific to an operating system and CPU architecture. Executables are produced as either [self-contained](#publish-self-contained) or [framework-dependent](#publish-framework-dependent). Publishing as self-contained includes the .NET runtime with the app, so users don't have to install .NET before running it. Publishing as framework-dependent doesn't include the .NET runtime; only the app and third-party dependencies are included. +## Quick reference -The following commands produce an executable: +The following table provides quick examples of how to publish your app. -| Type | Command | +::: zone pivot="cli,vscode" + +### Commands + +| Publish Mode | Command | |--|--| -| [framework-dependent executable](#publish-framework-dependent) for the current platform. | [`dotnet publish`](../tools/dotnet-publish.md) | -| [framework-dependent executable](#publish-framework-dependent) for a specific platform. | [`dotnet publish -r `](../tools/dotnet-publish.md) | -| [self-contained executable](#publish-self-contained). | [`dotnet publish -r --self-contained`](../tools/dotnet-publish.md) | +| [Framework-dependent deployment](#framework-dependent-deployment) | `dotnet publish -c Release [-r ]` | +| [Framework-dependent deployment (DLL)](#framework-dependent-deployment) | `dotnet publish -c Release -p:UseAppHost=false` | +| [Self-contained deployment](#self-contained-deployment) | `dotnet publish -c Release [-r ] --self-contained true` | +| [Single-file deployment](#single-file-deployment) | `dotnet publish -c Release [-r ] -p:PublishSingleFile=true` | +| [Native AOT deployment](#native-aot-deployment) | `dotnet publish -c Release [-r ] -p:PublishAot=true` | +| [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | -## Produce a cross-platform binary +::: zone-end -Cross-platform binaries are created when the app is published as [framework-dependent](#publish-framework-dependent), in the form of a *dll* file. The *dll* file is named after the project. For example, if you have an app named **word_reader**, a file named *word_reader.dll* is created. Apps published in this way are run with the `dotnet ` command. +::: zone pivot="visualstudio" -Cross-platform binaries can run on any operating system as long as the targeted .NET runtime is already installed. If the targeted .NET runtime isn't installed, the app might run using a newer runtime if configured to roll-forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +### Configurations -You can choose to run the app as a platform-specific executable or as a cross-platform binary via the `dotnet` command. There should be no app behavior difference when launching the platform-specific executable versus the `dotnet` command. Launching via a platform-specific executable gives you better integration with the underlying OS. For example: +| Publish Mode | Visual Studio Configuration | +|--|--| +| [Framework-dependent deployment](#framework-dependent-deployment) | Set **Deployment Mode** to **Framework-dependent** (default) | +| [Framework-dependent deployment (DLL)](#framework-dependent-deployment) | Set **Deployment Mode** to **Framework-dependent** and **Produce single file** to unchecked | +| [Self-contained deployment](#self-contained-deployment) | Set **Deployment Mode** to **Self-contained** | +| [Single-file deployment](#single-file-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Produce single file** to checked | +| [Native AOT deployment](#native-aot-deployment) | Requires `true` in project file and **Deployment Mode** set to **Self-contained** | +| [ReadyToRun deployment](#readytorun-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Enable ReadyToRun compilation** to checked | -- The app executable name appears in the process list instead of `dotnet`, which could be confusing if there's more than one. -- The platform-specific executable can be customized with OS-specific features. For example, see [this discussion about configuring default stack size on Windows](https://github.com/dotnet/runtime/issues/96347#issuecomment-1981470713). +::: zone-end -The following command produces a cross-platform binary: +## Publishing basics -| Type | Command | -|--|--| -| [framework-dependent cross-platform binary](#publish-framework-dependent). | [`dotnet publish`](../tools/dotnet-publish.md) | +The [``](../project-sdk/msbuild-props.md#targetframework) setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. -## Publish framework-dependent +If you want to target more than one framework, you can set the [``](../project-sdk/msbuild-props.md#targetframeworks) setting to multiple TFM values, separated by a semicolon. When you build your app, a build is produced for each target framework. However, when you publish your app, you must specify the target framework: -Apps published as framework-dependent are cross-platform and don't include the .NET runtime. The environment where the app runs must have the .NET runtime installed. +::: zone pivot="cli,vscode" -Publishing as framework-dependent produces a [cross-platform binary](#produce-a-cross-platform-binary) as a *dll* file, and a [platform-specific executable](#produce-an-executable) that targets the current platform. The *dll* is cross-platform while the executable isn't. For example, if the app is named **word_reader** and targets Windows, a *word_reader.exe* executable is created along with *word_reader.dll*. When targeting Linux or macOS, a *word_reader* executable is created along with *word_reader.dll*. If the app uses a NuGet package that has platform-specific implementations, dependencies for all platforms are copied to the *publish\\runtimes\\{platform}* folder. +Use `dotnet publish -f ` -The cross-platform binary can be run with the `dotnet ` command, and can run on any environment. +::: zone-end -### Platform-specific and framework-dependent +::: zone pivot="visualstudio" -Publish a framework-dependent app that's platform-specific by passing the `-r ` parameters to the [`dotnet publish`](../tools/dotnet-publish.md) command. Publishing in this way is the same as [publish framework-dependent](#publish-framework-dependent), except that platform-specific dependencies are handled differently. If the app uses a NuGet package that has platform-specific implementations, only the targeted platform's dependencies are copied. These dependencies are copied directly to the *publish* folder. +Create separate publishing profiles for each target framework -While technically the binary produced is cross-platform, by targeting a specific environment, the app isn't guaranteed to run cross-platform. The app can be run with `dotnet `, but it might crash when it tries to access platform-specific dependencies that are missing. +::: zone-end -For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). +### Native dependencies -### Advantages +If your app has native dependencies, it might not run on a different operating system. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. + +Consider also, if a library you referenced has a native dependency, your app might not run on every platform. However, it's possible a NuGet package you're referencing includes platform-specific versions to handle the required native dependencies for you. + +To ensure that your app is published with its native dependencies: + +::: zone pivot="cli,vscode" + +Use `dotnet publish -r ` to publish for a specific platform + +::: zone-end -- **Small deployment**\ -Only the app and its dependencies are distributed. The environment where the app is run must already have the .NET runtime installed. +::: zone pivot="visualstudio" -- **Cross-platform**\ -The app and any .NET-based library runs on other operating systems. There's no need to define a target platform for the app. For information about the .NET file format, see [.NET Assembly File Format](../../standard/assembly/file-format.md). +Set **Target Runtime** to your desired platform -- **Uses the latest patched runtime**\ -The app uses the latest runtime (within the targeted major-minor family of .NET) installed in the environment. This means the app automatically uses the latest patched version of the .NET runtime. This default behavior can be overridden. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +::: zone-end + +For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + +## Framework-dependent deployment + +Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable host is created to host your cross-platform app. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. + +Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on the environment where your app runs. For example, if your app targets .NET 9, any environment that your app runs on must have the .NET 9 runtime installed. + +Publishing a framework-dependent deployment creates an app that automatically rolls-forward to the latest .NET security patch available on the environment that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). + +### Advantages + +- **Small deployment**: Only the app and its dependencies are distributed. The environment where the app is run must already have the .NET runtime installed. +- **Cross-platform**: The app and any .NET-based library runs on other operating systems. +- **Uses the latest patched runtime**: The app uses the latest runtime installed in the environment. ### Disadvantages -- **Requires pre-installing the runtime**\ -The app can run only if the version of .NET it targets is already installed in the environment running the app. Configure roll-forward behavior for the app to either require a specific version of .NET or allow a newer version of .NET. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +- **Requires pre-installing the runtime**: The app can run only if the version of .NET it targets is already installed in the environment. +- **.NET might change**: The environment where the app is run might use a newer .NET runtime, which could change app behavior. -- **.NET may change**\ -It's possible that the environment where the app is run is using a newer .NET runtime. In rare cases, this might change the behavior of the app if it uses the .NET libraries, which most apps do. Configure how an app uses newer versions of .NET, known as rolling forward. For more information, see [framework-dependent apps roll forward](../versions/selection.md#framework-dependent-apps-roll-forward). +### Publish -### Examples +::: zone pivot="cli,vscode" -Publish an app as cross-platform and framework-dependent. An executable that targets the current platform is created along with the *dll* file. Any platform-specific dependencies are published with the app. +```dotnetcli +dotnet publish -c Release [-r ] +``` + +Or explicitly: ```dotnetcli -dotnet publish +dotnet publish -c Release [-r ] --self-contained false ``` -Publish an app as platform-specific and framework-dependent. A Linux 64-bit executable is created along with the *dll* file. Only the targeted platform's dependencies are published with the app. +::: zone-end + +::: zone pivot="visualstudio" + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Framework-dependent** (this is the default). +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Click **Save** and then **Publish**. + +::: zone-end + +### Cross-platform DLL deployment + +Alternatively, you can publish your app as a cross-platform DLL without a platform-specific executable. In this mode, a `.dll` file is created in the publish output folder. To run your app, navigate to the output folder and use the `dotnet .dll` command. + +To publish as a cross-platform DLL: + +::: zone pivot="cli,vscode" ```dotnetcli -dotnet publish -r linux-x64 +dotnet publish -c Release -p:UseAppHost=false ``` -## Publish self-contained +::: zone-end -Publishing as self-contained produces a platform-specific executable. The output publishing folder contains all components of the app, including the .NET libraries and target runtime. The app is isolated from other .NET apps and doesn't use a locally installed shared runtime. The environment running the app isn't required to have a .NET runtime installed. +::: zone pivot="visualstudio" -Publish a self-contained app by passing the `--self-contained` parameter to the [`dotnet publish`](../tools/dotnet-publish.md) command. The executable binary is produced for the specified target environment. For example, if your app is named **word_reader**, and you publish a self-contained executable for Windows, a *word_reader.exe* file is created. If you publish for Linux or macOS, a *word_reader* file is created. Specify the target environment and architecture with the `-r ` parameter for the [`dotnet publish`](../tools/dotnet-publish.md) command. For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Framework-dependent**. +01. Uncheck **Produce single file**. +01. Set **Target Runtime** to **Portable** (or leave blank). +01. Click **Save** and then **Publish**. -If the app has platform-specific dependencies, such as a NuGet package containing platform-specific dependencies, these are copied to the publish folder along with the app. +::: zone-end -### Advantages +## Self-contained deployment -- **Control .NET version**\ -Control which version of .NET is deployed with the app. +When you publish a self-contained deployment (SCD), the publishing process creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the native dependencies of .NET. These dependencies must be present on the environment before the app runs. -- **Platform-specific targeting**\ -Because the app must be published for each platform, it's clear where the app runs. If .NET introduces a new platform, users can't run the app on that platform until a version targeting that platform is released. Test the app for compatibility problems before users run it on the new platform. +Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). -### Disadvantages +### Advantages + +- **Control .NET version**: Control which version of .NET is deployed with the app. +- **Platform-specific targeting**: Because the app must be published for each platform, it's clear where the app runs. -- **Larger deployments**\ -Because the app includes the .NET runtime and all dependencies, the download size and hard drive space required is greater than a [framework-dependent](#publish-framework-dependent) version. +### Disadvantages - > [!TIP] - > Reduce the size of the deployment on Linux environments by approximately 28 MB by using .NET [*globalization invariant mode*](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). This forces the app to treat all cultures like the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType). - > - > [IL trimming](trimming/trim-self-contained.md) can further reduce the size of the deployment. +- **Larger deployments**: Because the app includes the .NET runtime and all dependencies, the download size and hard drive space required is greater than a **framework-dependent deployment**. +- **Harder to update the .NET version**: The .NET Runtime can only be upgraded by releasing a new version of the app. -- **Harder to update the .NET version**\ -The .NET Runtime (distributed with the app) can only be upgraded by releasing a new version of the app. +> [!TIP] +> You can reduce the total size of compatible self-contained apps by [publishing trimmed](trimming/trim-self-contained.md) or by enabling **globalization invariant mode**. For more information about globalization invariant mode, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). -### Examples +### Publish -Publish an app self-contained. A macOS 64-bit executable is created. +::: zone pivot="cli,vscode" ```dotnetcli -dotnet publish -r osx-x64 --self-contained +dotnet publish -c Release -r --self-contained true ``` -Publish an app self-contained. A Windows 64-bit executable is created. +::: zone-end + +::: zone pivot="visualstudio" + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Click **Save** and then **Publish**. + +::: zone-end + +## Single-file deployment + +When you publish your app as a single-file deployment, all application-dependent files are bundled into a single binary. This deployment model is available for both framework-dependent and self-contained applications, providing an attractive option to deploy and distribute your application as a single file. + +Single-file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth. + +### Advantages + +- **Simplified distribution**: Deploy and distribute your application as a single executable file. +- **Reduced file clutter**: All dependencies are bundled, eliminating the need to manage multiple files. +- **Easy deployment**: Copy a single file to deploy the application. + +### Disadvantages + +- **Larger file size**: The single file includes all dependencies, making it larger than individual files. +- **Slower startup**: Files must be extracted at runtime, which can impact startup performance. +- **Platform-specific**: Must publish separate files for each target platform. + +Single-file deployment can be combined with other optimizations like [trimming](trimming/trim-self-contained.md) and [ReadyToRun compilation](#readytorun-deployment) for further optimization. + +For more information about single-file deployment, see [Single-file deployment](single-file/overview.md). + +### Publish + +::: zone pivot="cli,vscode" ```dotnetcli -dotnet publish -r win-x64 --self-contained +dotnet publish -c Release -r -p:PublishSingleFile=true ``` -## Publish with ReadyToRun images +::: zone-end -Publishing with ReadyToRun images improves the startup time of the app at the cost of increasing the size of the app. For more information, see [ReadyToRun](ready-to-run.md). +::: zone pivot="visualstudio" + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Check **Produce single file**. +01. Click **Save** and then **Publish**. + +::: zone-end + +## Native AOT deployment + +Native AOT deployment compiles your app directly to native code, eliminating the need for a runtime. This publishing option uses **self-contained deployment** mode, as the compiled native code must include everything needed to run the application. This results in faster startup times and reduced memory usage, but comes with some limitations on supported features. ### Advantages -- **Improved startup time**\ -The app spends less time running the JIT. +- **Fast startup**: No JIT compilation needed at runtime, leading to faster application startup. +- **Reduced memory usage**: Lower memory footprint compared to traditional .NET applications. +- **No runtime dependency**: The application runs without requiring .NET runtime installation. +- **Smaller deployment size**: Often smaller than **self-contained deployment** with the full runtime. ### Disadvantages -- **Larger size**\ -The app is larger on disk. +- **Limited framework support**: Not all .NET features and libraries are compatible with Native AOT. +- **Longer build times**: Compilation to native code takes significantly longer than regular builds. +- **Platform-specific**: Must compile separately for each target platform and architecture. +- **Debugging limitations**: More complex debugging experience compared to regular .NET applications. + +For more information about Native AOT deployment, see [Native AOT deployment](native-aot/index.md). -### Examples +### Publish -Publish an app self-contained and ReadyToRun. A macOS 64-bit executable is created. +::: zone pivot="cli,vscode" ```dotnetcli -dotnet publish -c Release -r osx-x64 --self-contained -p:PublishReadyToRun=true +dotnet publish -c Release -r -p:PublishAot=true ``` -Publish an app self-contained and ReadyToRun. A Windows 64-bit executable is created. +::: zone-end + +::: zone pivot="visualstudio" + +Native AOT publishing must be configured in the project file. You cannot enable it through the Visual Studio publishing UI. + +01. In **Solution Explorer**, right-click on your project and select **Edit Project File**. +01. Add the following property to a ``: + + ```xml + true + ``` + +01. Save the project file. +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Click **Save** and then **Publish**. + +For more information about the `PublishAot` property, see [MSBuild properties for Microsoft.NET.Sdk](../project-sdk/msbuild-props.md#publishaot). + +::: zone-end + +## ReadyToRun deployment + +When you publish your app with ReadyToRun compilation, your application assemblies are compiled as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation that improves startup performance by reducing the amount of work the just-in-time (JIT) compiler needs to do as your application loads. This publishing option can be used with both **framework-dependent** and **self-contained** deployment modes. + +ReadyToRun binaries contain both intermediate language (IL) code and the native version of the same code. While R2R binaries are larger than regular assemblies, they provide better startup performance. + +### Advantages + +- **Improved startup time**: The app spends less time running the JIT compiler during startup. +- **Better first-use performance**: Reduced latency for first-time execution of code paths. +- **Compatible with existing code**: Works with most .NET libraries and frameworks without modification. +- **Flexible deployment**: Can be combined with both **framework-dependent deployment** and **self-contained deployment** modes. + +### Disadvantages + +- **Larger size**: The app is larger on disk due to including both IL and native code. +- **Longer build times**: Compilation takes more time than standard publishing. +- **Platform-specific optimizations**: Best performance gains require targeting specific platforms. + +### Publish + +::: zone pivot="cli,vscode" ```dotnetcli -dotnet publish -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true +dotnet publish -c Release -r -p:PublishReadyToRun=true ``` +::: zone-end + +::: zone pivot="visualstudio" + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Check **Enable ReadyToRun compilation**. +01. Click **Save** and then **Publish**. + +::: zone-end + +For more information about ReadyToRun deployment, see [ReadyToRun compilation](ready-to-run.md). + ## See also -- [Deploying .NET Apps with .NET CLI.](publish-with-cli.md) -- [Deploying .NET Apps with Visual Studio.](publish-with-vs.md) -- [.NET Runtime Identifier (RID) catalog.](../rid-catalog.md) -- [Select the .NET version to use.](../versions/selection.md) +- [.NET Runtime Identifier (RID) catalog](../rid-catalog.md) +- [Select the .NET version to use](../versions/selection.md) From 393b2cdb3de9d092f9a04f5d22351e48137c4306 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 15:25:28 -0700 Subject: [PATCH 09/29] Reset copilot --- .github/copilot-instructions.md | 98 ++++++++++++++------------------- 1 file changed, 41 insertions(+), 57 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index eccc7c1c61c77..c48ae856aeb87 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,57 +1,41 @@ -# .NET Documentation Guidelines - -## Terminology -- All .NET content refers to modern .NET (not .NET Framework). - -## Writing Style -Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics: - -### Voice and Tone -- Active voice, second person addressing reader directly -- Conversational tone with contractions -- Present tense for instructions/descriptions -- Imperative mood for instructions ("Call the method" not "You should call the method") -- Use "might" instead of "may" for possibility -- Avoid "we"/"our" referring to documentation authors - -### Structure and Format -- Sentence case headings (no gerunds in titles) -- Be concise, break up long sentences -- Oxford comma in lists -- Number all ordered list items as "01." (not sequential numbering like "1.", "2.", "3.", etc.) -- Complete sentences with proper punctuation in all list items -- Avoid "etc." or "and so on" - provide complete lists or use "for example" -- No consecutive headings without content between them - -### Formatting Conventions -- **Bold** for UI elements -- `Code style` for file names, folders, custom types, non-localizable text -- Raw URLs in angle brackets -- Use relative links for files in this repo -- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links - -## API References -Use cross-references: `` - -To find API doc IDs: -1. Check XML files in https://github.com/dotnet/dotnet-api-docs -2. For types: `Value` attribute of `` where `Language="DocId"` (omit first 2 characters) -3. For members: `Value` attribute of `` where `Language="DocId"` (omit first 2 characters) - -If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` - -Use the `url` value from results for manual links. - -## Code Snippets -For snippets >6 lines: -1. Create `./snippets/my-doc/language` folder in same directory as document (for a document named `my-doc.md`) where language is either vb (for visual basic) or cs (for c#) -1. Add snippet as separate code file -1. Include simple project file targeting latest .NET -1. All code should use the latest stable versions/features -1. Create examples in both C# and Visual Basic - -## File Naming -New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.) - -## Special Cases -- Breaking changes: Include directions from `.github/prompts/breaking-change.md` +When writing documentation, follow the following guidelines: + +Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework). + +Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/). + +Headings should be in sentence case, not title case. Don't use gerunds in titles. + +Use the active voice whenever possible, and second person to address the reader directly. + +Use a conversational tone with contractions. + +Be concise. + +Break up long sentences. + +Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value." + +Do not use "we" or "our" to refer to the authors of the documentation. + +Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method." + +Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception." + +Use the Oxford comma in lists of three or more items. + +Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists. + +Use **bold** when referring to UI elements. Use `code style` for file names and folders, custom types, and other text that should never be localized. + +Put raw URLs within angle brackets. + +Include links to related topics and resources where appropriate. Use relative links if the target file lives in this repo. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link. + +When mentioning APIs, use cross-references to the API documentation. These links are formatted as . You can find the API doc ID in the XML files in the https://github.com/dotnet/dotnet-api-docs repository. For types, the doc ID is the value of the `Value` attribute of the `` element where the `Language` attribute value is `DocId`. For other (member) APIs, the doc ID is the value of the `Value` attribute of the `` element where the `Language` attribute value is `DocId`. Omit the first two characters of the DocId. For example, the xref link for System.String is . + +If you're assigned a GitHub issue that's labeled "breaking-change", include the prompt directions in the .github/prompts/breaking-change.md file in this repo. + +If you include a code snippet that's more than 6 lines long, put it in a separate .cs file in a folder named "snippets" in the same folder as the document. Within the "snippets" folder, add a new directory with the name of the document. For example, if the document is named "my-doc.md", create a folder named "snippets/my-doc" folder. Also add a simple .csproj file to the same directory that targets the latest version of .NET. It can be a library or executable project. + +If you're adding a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name. From 556fd9a42be2b023f32cc465305b7eae4bacf4be Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 17:10:50 -0700 Subject: [PATCH 10/29] Extra descriptions --- docs/core/deploying/index.md | 113 +++++++++++++++++++++++++++++++---- 1 file changed, 101 insertions(+), 12 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 5ca37afb02c8b..2a1c0041ff218 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -30,14 +30,6 @@ This mode produces a publishing folder that includes a platform-specific executa > [!IMPORTANT] > You specify the target platform with a runtime identifier (RID). For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). -## Portable binaries - -When you publish a .NET app, you can target a specific platform or create a portable binary. By default, even when creating a portable binary, .NET publishes a platform-specific executable alongside the portable DLL unless you explicitly disable this behavior. - -The platform-specific executable is created because of the `UseAppHost` property, which defaults to `true`. To publish only the portable DLL without the platform-specific executable, set `UseAppHost` to `false` either on the command line (`-p:UseAppHost=false`) or as a project property. - -The benefit of targeting a specific platform is that it can handle [native dependencies](#native-dependencies) that your app might require, ensuring compatibility with the target platform's specific requirements. - ## Quick reference The following table provides quick examples of how to publish your app. @@ -80,16 +72,30 @@ If you want to target more than one framework, you can set the [`` +The default build configuration mode is **Release**, unless changed with the `-c` parameter. + +```dotnet +dotnet publish -c Release -f net9.0 +``` + +The default output directory of the [`dotnet publish`](../tools/dotnet-publish.md) command is `./bin///publish/`. For example, `dotnet publish -c Release -f net9.0` publishes to `./bin/Release/net9.0/publish/`. However, you can opt in to a simplified output path and folder structure for all build outputs. For more information, see [Artifacts output layout](../sdk/artifacts-output.md). ::: zone-end ::: zone pivot="visualstudio" -Create separate publishing profiles for each target framework +In Visual Studio, create separate publishing profiles for each target framework. ::: zone-end +### Portable binaries + +When you publish a .NET app, you can target a specific platform or create a portable binary. By default, even when creating a portable binary, .NET publishes a platform-specific executable alongside the portable DLL unless you explicitly disable this behavior. + +The platform-specific executable is created because of the `UseAppHost` property, which defaults to `true`. To publish only the portable DLL without the platform-specific executable, set `UseAppHost` to `false` either on the command line (`-p:UseAppHost=false`) or as a project property. + +The benefit of targeting a specific platform is that it can handle [native dependencies](#native-dependencies) that your app might require, ensuring compatibility with the target platform's specific requirements. + ### Native dependencies If your app has native dependencies, it might not run on a different operating system. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. @@ -100,13 +106,28 @@ To ensure that your app is published with its native dependencies: ::: zone pivot="cli,vscode" -Use `dotnet publish -r ` to publish for a specific platform +```dotnetcli +dotnet publish -c Release -r +``` + +- `-c Release` + + This switch sets the build configuration to Release, which is optimized for production deployment. + +- `-r ` + + This switch uses a runtime identifier (RID) to specify the target platform and ensures native dependencies are included. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). ::: zone-end ::: zone pivot="visualstudio" -Set **Target Runtime** to your desired platform +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. +01. Choose a folder location or accept the default, then click **Finish**. +01. In the publish profile, click **Show all settings**. +01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). +01. Click **Save** and then **Publish**. ::: zone-end @@ -139,12 +160,24 @@ Publishing a framework-dependent deployment creates an app that automatically ro dotnet publish -c Release [-r ] ``` +- `-c Release` + + This switch sets the build configuration to Release, which is optimized for production deployment. + +- `-r ` (optional) + + This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + Or explicitly: ```dotnetcli dotnet publish -c Release [-r ] --self-contained false ``` +- `--self-contained false` + + This switch explicitly tells the .NET SDK to create a framework-dependent deployment. + ::: zone-end ::: zone pivot="visualstudio" @@ -171,6 +204,14 @@ To publish as a cross-platform DLL: dotnet publish -c Release -p:UseAppHost=false ``` +- `-c Release` + + This switch sets the build configuration to Release, which is optimized for production deployment. + +- `-p:UseAppHost=false` + + This property disables the creation of a platform-specific executable, producing only the portable DLL. + ::: zone-end ::: zone pivot="visualstudio" @@ -213,6 +254,18 @@ Publishing an SCD creates an app that doesn't roll forward to the latest availab dotnet publish -c Release -r --self-contained true ``` +- `-c Release` + + This switch sets the build configuration to Release, which is optimized for production deployment. + +- `-r ` + + This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + +- `--self-contained true` + + This switch tells the .NET SDK to create an executable as a self-contained deployment (SCD). + ::: zone-end ::: zone pivot="visualstudio" @@ -257,6 +310,18 @@ For more information about single-file deployment, see [Single-file deployment]( dotnet publish -c Release -r -p:PublishSingleFile=true ``` +- `-c Release` + + This switch sets the build configuration to Release, which is optimized for production deployment. + +- `-r ` + + This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + +- `-p:PublishSingleFile=true` + + This property bundles all application-dependent files into a single binary. + ::: zone-end ::: zone pivot="visualstudio" @@ -300,6 +365,18 @@ For more information about Native AOT deployment, see [Native AOT deployment](na dotnet publish -c Release -r -p:PublishAot=true ``` +- `-c Release` + + This switch sets the build configuration to Release, which is optimized for production deployment. + +- `-r ` + + This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + +- `-p:PublishAot=true` + + This property enables Native AOT compilation, which compiles the app directly to native code. + ::: zone-end ::: zone pivot="visualstudio" @@ -353,6 +430,18 @@ ReadyToRun binaries contain both intermediate language (IL) code and the native dotnet publish -c Release -r -p:PublishReadyToRun=true ``` +- `-c Release` + + This switch sets the build configuration to Release, which is optimized for production deployment. + +- `-r ` + + This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). + +- `-p:PublishReadyToRun=true` + + This property enables ReadyToRun compilation, which improves startup performance by pre-compiling assemblies. + ::: zone-end ::: zone pivot="visualstudio" From 7ca336d8549d2bd8051c72f8df5f19ba34b2cc09 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 17:40:27 -0700 Subject: [PATCH 11/29] Move cli parameters to include --- docs/core/deploying/includes/cli-c-release.md | 3 + .../deploying/includes/cli-r-rid-optional.md | 3 + docs/core/deploying/includes/cli-r-rid.md | 3 + docs/core/deploying/index.md | 64 ++++++------------- 4 files changed, 28 insertions(+), 45 deletions(-) create mode 100644 docs/core/deploying/includes/cli-c-release.md create mode 100644 docs/core/deploying/includes/cli-r-rid-optional.md create mode 100644 docs/core/deploying/includes/cli-r-rid.md diff --git a/docs/core/deploying/includes/cli-c-release.md b/docs/core/deploying/includes/cli-c-release.md new file mode 100644 index 0000000000000..4d80bb2cc0d9e --- /dev/null +++ b/docs/core/deploying/includes/cli-c-release.md @@ -0,0 +1,3 @@ +`-c Release` + +This switch sets the build configuration to Release, which is optimized for production deployment. diff --git a/docs/core/deploying/includes/cli-r-rid-optional.md b/docs/core/deploying/includes/cli-r-rid-optional.md new file mode 100644 index 0000000000000..6adcfa1157e8c --- /dev/null +++ b/docs/core/deploying/includes/cli-r-rid-optional.md @@ -0,0 +1,3 @@ +`-r ` (optional) + +This switch uses a runtime identifier (RID) to specify the target platform and ensures native dependencies are included (if required). For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../../rid-catalog.md). diff --git a/docs/core/deploying/includes/cli-r-rid.md b/docs/core/deploying/includes/cli-r-rid.md new file mode 100644 index 0000000000000..f14f6300ae168 --- /dev/null +++ b/docs/core/deploying/includes/cli-r-rid.md @@ -0,0 +1,3 @@ +`-r ` + +This switch uses a runtime identifier (RID) to specify the target platform and ensures native dependencies are included (if required). For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../../rid-catalog.md). diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 2a1c0041ff218..aa02e19f3e02c 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -110,13 +110,9 @@ To ensure that your app is published with its native dependencies: dotnet publish -c Release -r ``` -- `-c Release` +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] - This switch sets the build configuration to Release, which is optimized for production deployment. - -- `-r ` - - This switch uses a runtime identifier (RID) to specify the target platform and ensures native dependencies are included. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). +- [!INCLUDE [cli-r-rid-native-deps](includes/cli-r-rid-native-deps.md)] ::: zone-end @@ -160,13 +156,9 @@ Publishing a framework-dependent deployment creates an app that automatically ro dotnet publish -c Release [-r ] ``` -- `-c Release` - - This switch sets the build configuration to Release, which is optimized for production deployment. - -- `-r ` (optional) +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] - This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). +- [!INCLUDE [cli-r-rid](includes/cli-r-rid.md)] Or explicitly: @@ -176,7 +168,7 @@ dotnet publish -c Release [-r ] --self-contained false - `--self-contained false` - This switch explicitly tells the .NET SDK to create a framework-dependent deployment. +This switch explicitly tells the .NET SDK to create a framework-dependent deployment. ::: zone-end @@ -204,13 +196,11 @@ To publish as a cross-platform DLL: dotnet publish -c Release -p:UseAppHost=false ``` -- `-c Release` - - This switch sets the build configuration to Release, which is optimized for production deployment. +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] - `-p:UseAppHost=false` - This property disables the creation of a platform-specific executable, producing only the portable DLL. +This property disables the creation of a platform-specific executable, producing only the portable DLL. ::: zone-end @@ -254,17 +244,13 @@ Publishing an SCD creates an app that doesn't roll forward to the latest availab dotnet publish -c Release -r --self-contained true ``` -- `-c Release` - - This switch sets the build configuration to Release, which is optimized for production deployment. - -- `-r ` +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] - This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). +- [!INCLUDE [cli-r-rid](includes/cli-r-rid.md)] - `--self-contained true` - This switch tells the .NET SDK to create an executable as a self-contained deployment (SCD). +This switch tells the .NET SDK to create an executable as a self-contained deployment (SCD). ::: zone-end @@ -310,17 +296,13 @@ For more information about single-file deployment, see [Single-file deployment]( dotnet publish -c Release -r -p:PublishSingleFile=true ``` -- `-c Release` +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] - This switch sets the build configuration to Release, which is optimized for production deployment. - -- `-r ` - - This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). +- [!INCLUDE [cli-r-rid](includes/cli-r-rid.md)] - `-p:PublishSingleFile=true` - This property bundles all application-dependent files into a single binary. +This property bundles all application-dependent files into a single binary. ::: zone-end @@ -365,17 +347,13 @@ For more information about Native AOT deployment, see [Native AOT deployment](na dotnet publish -c Release -r -p:PublishAot=true ``` -- `-c Release` - - This switch sets the build configuration to Release, which is optimized for production deployment. +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] -- `-r ` - - This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). +- [!INCLUDE [cli-r-rid](includes/cli-r-rid.md)] - `-p:PublishAot=true` - This property enables Native AOT compilation, which compiles the app directly to native code. +This property enables Native AOT compilation, which compiles the app directly to native code. ::: zone-end @@ -430,17 +408,13 @@ ReadyToRun binaries contain both intermediate language (IL) code and the native dotnet publish -c Release -r -p:PublishReadyToRun=true ``` -- `-c Release` - - This switch sets the build configuration to Release, which is optimized for production deployment. - -- `-r ` +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] - This switch uses a runtime identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). +- [!INCLUDE [cli-r-rid](includes/cli-r-rid.md)] - `-p:PublishReadyToRun=true` - This property enables ReadyToRun compilation, which improves startup performance by pre-compiling assemblies. +This property enables ReadyToRun compilation, which improves startup performance by pre-compiling assemblies. ::: zone-end From 6fe7a63f7c93dd0ffab5213b3121f2f1bdea921f Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 18:03:57 -0700 Subject: [PATCH 12/29] move table --- docs/core/deploying/index.md | 51 ++++++++++++------------------------ 1 file changed, 17 insertions(+), 34 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index aa02e19f3e02c..7432b6e9bafa4 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -30,40 +30,6 @@ This mode produces a publishing folder that includes a platform-specific executa > [!IMPORTANT] > You specify the target platform with a runtime identifier (RID). For more information about RIDs, see [.NET RID Catalog](../rid-catalog.md). -## Quick reference - -The following table provides quick examples of how to publish your app. - -::: zone pivot="cli,vscode" - -### Commands - -| Publish Mode | Command | -|--|--| -| [Framework-dependent deployment](#framework-dependent-deployment) | `dotnet publish -c Release [-r ]` | -| [Framework-dependent deployment (DLL)](#framework-dependent-deployment) | `dotnet publish -c Release -p:UseAppHost=false` | -| [Self-contained deployment](#self-contained-deployment) | `dotnet publish -c Release [-r ] --self-contained true` | -| [Single-file deployment](#single-file-deployment) | `dotnet publish -c Release [-r ] -p:PublishSingleFile=true` | -| [Native AOT deployment](#native-aot-deployment) | `dotnet publish -c Release [-r ] -p:PublishAot=true` | -| [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | - -::: zone-end - -::: zone pivot="visualstudio" - -### Configurations - -| Publish Mode | Visual Studio Configuration | -|--|--| -| [Framework-dependent deployment](#framework-dependent-deployment) | Set **Deployment Mode** to **Framework-dependent** (default) | -| [Framework-dependent deployment (DLL)](#framework-dependent-deployment) | Set **Deployment Mode** to **Framework-dependent** and **Produce single file** to unchecked | -| [Self-contained deployment](#self-contained-deployment) | Set **Deployment Mode** to **Self-contained** | -| [Single-file deployment](#single-file-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Produce single file** to checked | -| [Native AOT deployment](#native-aot-deployment) | Requires `true` in project file and **Deployment Mode** set to **Self-contained** | -| [ReadyToRun deployment](#readytorun-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Enable ReadyToRun compilation** to checked | - -::: zone-end - ## Publishing basics The [``](../project-sdk/msbuild-props.md#targetframework) setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. @@ -129,6 +95,23 @@ dotnet publish -c Release -r For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). +::: zone pivot="cli,vscode" + +## Quick reference + +The following table provides quick examples of how to publish your app. + +| Publish Mode | Command | +|--|--| +| [Framework-dependent deployment](#framework-dependent-deployment) | `dotnet publish -c Release [-r ]` | +| [Framework-dependent deployment (DLL)](#framework-dependent-deployment) | `dotnet publish -c Release -p:UseAppHost=false` | +| [Self-contained deployment](#self-contained-deployment) | `dotnet publish -c Release [-r ] --self-contained true` | +| [Single-file deployment](#single-file-deployment) | `dotnet publish -c Release [-r ] -p:PublishSingleFile=true` | +| [Native AOT deployment](#native-aot-deployment) | `dotnet publish -c Release [-r ] -p:PublishAot=true` | +| [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | + +::: zone-end + ## Framework-dependent deployment Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable host is created to host your cross-platform app. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. From f69d0325c9fd1792775ecbd98d2f048b02f6d745 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 18:16:25 -0700 Subject: [PATCH 13/29] Change header to bold --- docs/core/deploying/index.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 7432b6e9bafa4..e223f110d86c6 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -120,13 +120,13 @@ Your app is configured to target a specific version of .NET. That targeted .NET Publishing a framework-dependent deployment creates an app that automatically rolls-forward to the latest .NET security patch available on the environment that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). -### Advantages +**Advantages** - **Small deployment**: Only the app and its dependencies are distributed. The environment where the app is run must already have the .NET runtime installed. - **Cross-platform**: The app and any .NET-based library runs on other operating systems. - **Uses the latest patched runtime**: The app uses the latest runtime installed in the environment. -### Disadvantages +**Disadvantages** - **Requires pre-installing the runtime**: The app can run only if the version of .NET it targets is already installed in the environment. - **.NET might change**: The environment where the app is run might use a newer .NET runtime, which could change app behavior. @@ -206,12 +206,12 @@ When you publish a self-contained deployment (SCD), the publishing process creat Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). -### Advantages +**Advantages** - **Control .NET version**: Control which version of .NET is deployed with the app. - **Platform-specific targeting**: Because the app must be published for each platform, it's clear where the app runs. -### Disadvantages +**Disadvantages** - **Larger deployments**: Because the app includes the .NET runtime and all dependencies, the download size and hard drive space required is greater than a **framework-dependent deployment**. - **Harder to update the .NET version**: The .NET Runtime can only be upgraded by releasing a new version of the app. @@ -255,13 +255,13 @@ When you publish your app as a single-file deployment, all application-dependent Single-file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth. -### Advantages +**Advantages** - **Simplified distribution**: Deploy and distribute your application as a single executable file. - **Reduced file clutter**: All dependencies are bundled, eliminating the need to manage multiple files. - **Easy deployment**: Copy a single file to deploy the application. -### Disadvantages +**Disadvantages** - **Larger file size**: The single file includes all dependencies, making it larger than individual files. - **Slower startup**: Files must be extracted at runtime, which can impact startup performance. @@ -306,14 +306,14 @@ This property bundles all application-dependent files into a single binary. Native AOT deployment compiles your app directly to native code, eliminating the need for a runtime. This publishing option uses **self-contained deployment** mode, as the compiled native code must include everything needed to run the application. This results in faster startup times and reduced memory usage, but comes with some limitations on supported features. -### Advantages +**Advantages** - **Fast startup**: No JIT compilation needed at runtime, leading to faster application startup. - **Reduced memory usage**: Lower memory footprint compared to traditional .NET applications. - **No runtime dependency**: The application runs without requiring .NET runtime installation. - **Smaller deployment size**: Often smaller than **self-contained deployment** with the full runtime. -### Disadvantages +**Disadvantages** - **Limited framework support**: Not all .NET features and libraries are compatible with Native AOT. - **Longer build times**: Compilation to native code takes significantly longer than regular builds. @@ -370,14 +370,14 @@ When you publish your app with ReadyToRun compilation, your application assembli ReadyToRun binaries contain both intermediate language (IL) code and the native version of the same code. While R2R binaries are larger than regular assemblies, they provide better startup performance. -### Advantages +**Advantages** - **Improved startup time**: The app spends less time running the JIT compiler during startup. - **Better first-use performance**: Reduced latency for first-time execution of code paths. - **Compatible with existing code**: Works with most .NET libraries and frameworks without modification. - **Flexible deployment**: Can be combined with both **framework-dependent deployment** and **self-contained deployment** modes. -### Disadvantages +**Disadvantages** - **Larger size**: The app is larger on disk due to including both IL and native code. - **Longer build times**: Compilation takes more time than standard publishing. From 25dc695925c6ef652f4a539d8931a5166ec0e3b6 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 11 Aug 2025 19:03:31 -0700 Subject: [PATCH 14/29] Fix bugs --- docs/core/deploying/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index e223f110d86c6..4674cc041af3c 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -78,7 +78,7 @@ dotnet publish -c Release -r - [!INCLUDE [cli-c-release](includes/cli-c-release.md)] -- [!INCLUDE [cli-r-rid-native-deps](includes/cli-r-rid-native-deps.md)] +- [!INCLUDE [cli-r-rid](includes/cli-r-rid.md)] ::: zone-end @@ -360,7 +360,7 @@ Native AOT publishing must be configured in the project file. You cannot enable 01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). 01. Click **Save** and then **Publish**. -For more information about the `PublishAot` property, see [MSBuild properties for Microsoft.NET.Sdk](../project-sdk/msbuild-props.md#publishaot). +For more information about Native AOT deployment, see [Native AOT deployment](native-aot/index.md). ::: zone-end From 23801e663a52f620d6d1142f374daf28780ebd6a Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 11:03:11 -0700 Subject: [PATCH 15/29] Add info about FDD lookups --- docs/core/deploying/index.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 4674cc041af3c..3617113765085 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -111,7 +111,7 @@ The following table provides quick examples of how to publish your app. | [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | ::: zone-end - +[](#framework-dependent-deployment) ## Framework-dependent deployment Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable host is created to host your cross-platform app. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. @@ -167,6 +167,21 @@ This switch explicitly tells the .NET SDK to create a framework-dependent deploy ::: zone-end +### Configure .NET install search behavior + +In .NET 9 and later versions, you can configure the .NET installation search paths of the published executable via the [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch) and [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) properties. + +`AppHostDotNetSearch` allows specifying one or more locations where the executable will look for a .NET installation: + +- `AppLocal`: app executable's folder +- `AppRelative`: path relative to the app executable +- `EnvironmentVariable`: value of [`DOTNET_ROOT[_]`](../tools/dotnet-environment-variables.md#dotnet_root-dotnet_rootx86-dotnet_root_x86-dotnet_root_x64) environment variables +- `Global`: [registered](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-custom-location) and [default](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-default-location) global install locations + +`AppHostRelativeDotNet` specifies the path relative to the executable that will be searched when `AppHostDotNetSearch` contains `AppRelative`. + +For more information, see [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch), [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) and [install location options in apphost](https://github.com/dotnet/designs/blob/main/proposed/apphost-embed-install-location.md). + ### Cross-platform DLL deployment Alternatively, you can publish your app as a cross-platform DLL without a platform-specific executable. In this mode, a `.dll` file is created in the publish output folder. To run your app, navigate to the output folder and use the `dotnet .dll` command. From 51b410cae6fdd91eb318c7a1af1ff057f9115e2a Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 11:11:27 -0700 Subject: [PATCH 16/29] Remove my temp code --- docs/core/deploying/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 3617113765085..89528620cbad4 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -111,7 +111,7 @@ The following table provides quick examples of how to publish your app. | [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | ::: zone-end -[](#framework-dependent-deployment) + ## Framework-dependent deployment Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable host is created to host your cross-platform app. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. From 323789c926b67899b9231446b632e51eb0316842 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 16:16:48 -0700 Subject: [PATCH 17/29] Fix indentation --- docs/core/deploying/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 89528620cbad4..f5aceb63b1773 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -151,7 +151,7 @@ dotnet publish -c Release [-r ] --self-contained false - `--self-contained false` -This switch explicitly tells the .NET SDK to create a framework-dependent deployment. + This switch explicitly tells the .NET SDK to create a framework-dependent deployment. ::: zone-end @@ -198,7 +198,7 @@ dotnet publish -c Release -p:UseAppHost=false - `-p:UseAppHost=false` -This property disables the creation of a platform-specific executable, producing only the portable DLL. + This property disables the creation of a platform-specific executable, producing only the portable DLL. ::: zone-end @@ -248,7 +248,7 @@ dotnet publish -c Release -r --self-contained true - `--self-contained true` -This switch tells the .NET SDK to create an executable as a self-contained deployment (SCD). + This switch tells the .NET SDK to create an executable as a self-contained deployment (SCD). ::: zone-end @@ -300,7 +300,7 @@ dotnet publish -c Release -r -p:PublishSingleFile=true - `-p:PublishSingleFile=true` -This property bundles all application-dependent files into a single binary. + This property bundles all application-dependent files into a single binary. ::: zone-end @@ -351,7 +351,7 @@ dotnet publish -c Release -r -p:PublishAot=true - `-p:PublishAot=true` -This property enables Native AOT compilation, which compiles the app directly to native code. + This property enables Native AOT compilation, which compiles the app directly to native code. ::: zone-end @@ -412,7 +412,7 @@ dotnet publish -c Release -r -p:PublishReadyToRun=true - `-p:PublishReadyToRun=true` -This property enables ReadyToRun compilation, which improves startup performance by pre-compiling assemblies. + This property enables ReadyToRun compilation, which improves startup performance by pre-compiling assemblies. ::: zone-end From 79fb61903acdd9d0fd890818fc0c4ab2af1119f1 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 16:33:43 -0700 Subject: [PATCH 18/29] Add container --- docs/core/deploying/index.md | 69 ++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index f5aceb63b1773..c75cc2b8b4a61 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -109,6 +109,7 @@ The following table provides quick examples of how to publish your app. | [Single-file deployment](#single-file-deployment) | `dotnet publish -c Release [-r ] -p:PublishSingleFile=true` | | [Native AOT deployment](#native-aot-deployment) | `dotnet publish -c Release [-r ] -p:PublishAot=true` | | [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | +| [Container deployment](#container-deployment) | `dotnet publish -c Release [-r ] -t:PublishContainer` | ::: zone-end @@ -431,6 +432,74 @@ dotnet publish -c Release -r -p:PublishReadyToRun=true For more information about ReadyToRun deployment, see [ReadyToRun compilation](ready-to-run.md). +## Container deployment + +When you publish your app as a container, the .NET SDK packages your application and its dependencies into a container image without requiring a separate Dockerfile. This deployment mode creates a complete container image that can be run on any container runtime, such as Docker or Podman. Container deployment simplifies the containerization process by eliminating the need to write and maintain Dockerfiles while providing optimized base images. + +Starting with .NET SDK 8.0.200, container support is included by default and doesn't require additional NuGet packages. For console applications, you might need to enable container support explicitly by setting the `EnableSdkContainerSupport` property to `true`. + +> [!TIP] +> For more information about project settings related to containers, see [Containerize a .NET app reference](../containers/publish-configuration.md). + +**Advantages** + +- **Simplified containerization**: No need to write or maintain Dockerfiles for basic scenarios. +- **Optimized base images**: Uses Microsoft-provided, optimized base images with the latest security updates. +- **Consistent environment**: Ensures consistent runtime environment across development, testing, and production. +- **Easy distribution**: Container images can be easily shared and deployed across different environments. +- **Platform isolation**: Applications run in isolated containers, reducing conflicts between applications. + +**Disadvantages** + +- **Container runtime dependency**: The target environment must have a container runtime installed. +- **Image size**: Container images are typically larger than other deployment methods. +- **Learning curve**: Requires understanding of container concepts and tooling. +- **Limited customization**: Less flexibility compared to custom Dockerfiles for complex scenarios. + +### Publish + +::: zone pivot="cli,vscode" + +```dotnetcli +dotnet publish -c Release [-r ] /t:PublishContainer +``` + +- [!INCLUDE [cli-c-release](includes/cli-c-release.md)] + +- [!INCLUDE [cli-r-rid](includes/cli-r-rid.md)] + +- `-t:PublishContainer` + + This target publishes the application as a container image. + +You can also use the publish profile approach: + +```dotnetcli +dotnet publish -c Release [-r ] -p:PublishProfile=DefaultContainer +``` + +- `-p:PublishProfile=DefaultContainer` + + This profile triggers the container publishing process. + +::: zone-end + +::: zone pivot="visualstudio" + +01. Right-click on the project in **Solution Explorer** and select **Publish**. +01. Select **Container Registry** as the publish target and click **Next**. +01. Choose your target container registry (such as **Azure Container Registry**, **Docker Hub**, or **Generic Registry**) and click **Next**. +01. Configure the registry connection details and authentication. +01. In the publish profile, click **Show all settings**. +01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent** based on your needs. +01. Set **Target Runtime** to your desired platform (for example, **linux-x64** for Linux containers). +01. Configure container-specific settings like image name and tags. +01. Click **Save** and then **Publish**. + +::: zone-end + +For more information about container deployment, see [.NET SDK container creation overview](../containers/overview.md). + ## See also - [.NET Runtime Identifier (RID) catalog](../rid-catalog.md) From 569fc6b7de68718887140dcf4eef3df696f454ef Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 16:38:45 -0700 Subject: [PATCH 19/29] Handle what acro I can... --- docs/core/deploying/index.md | 70 ++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index c75cc2b8b4a61..2cec60b1d6f3a 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -85,11 +85,11 @@ dotnet publish -c Release -r ::: zone pivot="visualstudio" 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. +01. If this is your first time publishing, select **Folder** as the publish target and select **Next**. +01. Choose a folder location or accept the default, then select **Finish**. +01. In the publish profile, select **Show all settings**. 01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. ::: zone-end @@ -159,12 +159,12 @@ dotnet publish -c Release [-r ] --self-contained false ::: zone pivot="visualstudio" 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. +01. If this is your first time publishing, select **Folder** as the publish target and select **Next**. +01. Choose a folder location or accept the default, then select **Finish**. +01. In the publish profile, select **Show all settings**. 01. Set **Deployment Mode** to **Framework-dependent** (this is the default). 01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. ::: zone-end @@ -206,13 +206,13 @@ dotnet publish -c Release -p:UseAppHost=false ::: zone pivot="visualstudio" 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. +01. If this is your first time publishing, select **Folder** as the publish target and select **Next**. +01. Choose a folder location or accept the default, then select **Finish**. +01. In the publish profile, select **Show all settings**. 01. Set **Deployment Mode** to **Framework-dependent**. 01. Uncheck **Produce single file**. 01. Set **Target Runtime** to **Portable** (or leave blank). -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. ::: zone-end @@ -256,12 +256,12 @@ dotnet publish -c Release -r --self-contained true ::: zone pivot="visualstudio" 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. +01. If this is your first time publishing, select **Folder** as the publish target and select **Next**. +01. Choose a folder location or accept the default, then select **Finish**. +01. In the publish profile, select **Show all settings**. 01. Set **Deployment Mode** to **Self-contained**. 01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. ::: zone-end @@ -308,13 +308,13 @@ dotnet publish -c Release -r -p:PublishSingleFile=true ::: zone pivot="visualstudio" 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. +01. If this is your first time publishing, select **Folder** as the publish target and select **Next**. +01. Choose a folder location or accept the default, then select **Finish**. +01. In the publish profile, select **Show all settings**. 01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. 01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). 01. Check **Produce single file**. -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. ::: zone-end @@ -332,7 +332,7 @@ Native AOT deployment compiles your app directly to native code, eliminating the **Disadvantages** - **Limited framework support**: Not all .NET features and libraries are compatible with Native AOT. -- **Longer build times**: Compilation to native code takes significantly longer than regular builds. +- **Longer build times**: Compilation to native code takes longer than regular builds. - **Platform-specific**: Must compile separately for each target platform and architecture. - **Debugging limitations**: More complex debugging experience compared to regular .NET applications. @@ -358,7 +358,7 @@ dotnet publish -c Release -r -p:PublishAot=true ::: zone pivot="visualstudio" -Native AOT publishing must be configured in the project file. You cannot enable it through the Visual Studio publishing UI. +Native AOT publishing must be configured in the project file. You can't enable it through the Visual Studio publishing UI. 01. In **Solution Explorer**, right-click on your project and select **Edit Project File**. 01. Add the following property to a ``: @@ -369,12 +369,12 @@ Native AOT publishing must be configured in the project file. You cannot enable 01. Save the project file. 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. +01. If this is your first time publishing, select **Folder** as the publish target and select **Next**. +01. Choose a folder location or accept the default, then select **Finish**. +01. In the publish profile, select **Show all settings**. 01. Set **Deployment Mode** to **Self-contained**. 01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. For more information about Native AOT deployment, see [Native AOT deployment](native-aot/index.md). @@ -420,13 +420,13 @@ dotnet publish -c Release -r -p:PublishReadyToRun=true ::: zone pivot="visualstudio" 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. +01. If this is your first time publishing, select **Folder** as the publish target and select **Next**. +01. Choose a folder location or accept the default, then select **Finish**. +01. In the publish profile, select **Show all settings**. 01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. 01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). 01. Check **Enable ReadyToRun compilation**. -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. ::: zone-end @@ -436,7 +436,7 @@ For more information about ReadyToRun deployment, see [ReadyToRun compilation](r When you publish your app as a container, the .NET SDK packages your application and its dependencies into a container image without requiring a separate Dockerfile. This deployment mode creates a complete container image that can be run on any container runtime, such as Docker or Podman. Container deployment simplifies the containerization process by eliminating the need to write and maintain Dockerfiles while providing optimized base images. -Starting with .NET SDK 8.0.200, container support is included by default and doesn't require additional NuGet packages. For console applications, you might need to enable container support explicitly by setting the `EnableSdkContainerSupport` property to `true`. +Starting with .NET SDK 8.0.200, container support is included by default and doesn't require extra NuGet packages. For console applications, you might need to enable container support explicitly by setting the `EnableSdkContainerSupport` property to `true`. > [!TIP] > For more information about project settings related to containers, see [Containerize a .NET app reference](../containers/publish-configuration.md). @@ -487,14 +487,14 @@ dotnet publish -c Release [-r ] -p:PublishProfile=DefaultContainer ::: zone pivot="visualstudio" 01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. Select **Container Registry** as the publish target and click **Next**. -01. Choose your target container registry (such as **Azure Container Registry**, **Docker Hub**, or **Generic Registry**) and click **Next**. +01. Select **Container Registry** as the publish target and select **Next**. +01. Choose your target container registry (such as **Azure Container Registry**, **Docker Hub**, or **Generic Registry**) and select **Next**. 01. Configure the registry connection details and authentication. -01. In the publish profile, click **Show all settings**. +01. In the publish profile, select **Show all settings**. 01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent** based on your needs. 01. Set **Target Runtime** to your desired platform (for example, **linux-x64** for Linux containers). 01. Configure container-specific settings like image name and tags. -01. Click **Save** and then **Publish**. +01. Select **Save** and then **Publish**. ::: zone-end From 921c79b10c38d13a33be6e44a26aaf51794e96d6 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 16:53:34 -0700 Subject: [PATCH 20/29] Fix cross links to publishing --- .../multi-container-applications-docker-compose.md | 2 +- docs/core/compatibility/sdk/8.0/arch-option.md | 2 +- .../compatibility/sdk/8.0/runtimespecific-app-default.md | 2 +- docs/core/deploying/index.md | 6 +++--- docs/core/deploying/native-aot/index.md | 6 +++--- docs/core/deploying/ready-to-run.md | 4 ++-- docs/core/deploying/runtime-store.md | 6 +++--- docs/core/deploying/single-file/overview.md | 2 +- docs/core/deploying/trimming/trim-self-contained.md | 2 +- docs/core/install/macos-notarization-issues.md | 2 +- docs/core/native-interop/expose-components-to-com.md | 2 +- docs/core/project-sdk/msbuild-props.md | 4 ++-- docs/core/rid-catalog.md | 2 +- docs/core/runtime-discovery/troubleshoot-app-launch.md | 4 ++-- docs/core/tools/dotnet-clean.md | 2 +- docs/core/tools/dotnet-publish.md | 8 ++++---- docs/core/tools/sdk-errors/netsdk1071.md | 2 +- docs/core/tools/troubleshoot-usage-issues.md | 2 +- docs/core/versions/selection.md | 4 ++-- docs/core/whats-new/dotnet-core-2-2.md | 2 +- docs/core/whats-new/dotnet-core-3-0.md | 6 +++--- docs/core/whats-new/dotnet-core-3-1.md | 2 +- docs/standard/glossary.md | 6 +++--- docs/standard/runtime-libraries-overview.md | 2 +- 24 files changed, 41 insertions(+), 41 deletions(-) diff --git a/docs/architecture/microservices/multi-container-microservice-net-applications/multi-container-applications-docker-compose.md b/docs/architecture/microservices/multi-container-microservice-net-applications/multi-container-applications-docker-compose.md index 4498df493267f..86308780fc78e 100644 --- a/docs/architecture/microservices/multi-container-microservice-net-applications/multi-container-applications-docker-compose.md +++ b/docs/architecture/microservices/multi-container-microservice-net-applications/multi-container-applications-docker-compose.md @@ -457,7 +457,7 @@ The .NET team provides some basic variants in [dotnet/](https://hub.docker.com/r - **sdk**: for development and build scenarios - **aspnet**: for ASP.NET production scenarios - **runtime**: for .NET production scenarios -- **runtime-deps**: for production scenarios of [self-contained applications](../../../core/deploying/index.md#publish-self-contained) +- **runtime-deps**: for production scenarios of [self-contained applications](../../../core/deploying/index.md#self-contained-deployment) For faster startup, runtime images also automatically set aspnetcore\_urls to port 80 and use Ngen to create a native image cache of assemblies. diff --git a/docs/core/compatibility/sdk/8.0/arch-option.md b/docs/core/compatibility/sdk/8.0/arch-option.md index 77bd6f6d00969..a67d780d6889a 100644 --- a/docs/core/compatibility/sdk/8.0/arch-option.md +++ b/docs/core/compatibility/sdk/8.0/arch-option.md @@ -5,7 +5,7 @@ ms.date: 10/05/2023 --- # --arch option doesn't imply self-contained -Up until now, the `--arch` option for `dotnet` CLI commands such as [dotnet publish](../../../tools/dotnet-publish.md) implied that the app was [self-contained](../../../deploying/index.md#publish-self-contained). The behavior of the `--arch` option has now been changed to match that of the `--runtime` option, and it no longer implies that an app is self-contained. +Up until now, the `--arch` option for `dotnet` CLI commands such as [dotnet publish](../../../tools/dotnet-publish.md) implied that the app was [self-contained](../../../deploying/index.md#self-contained-deployment). The behavior of the `--arch` option has now been changed to match that of the `--runtime` option, and it no longer implies that an app is self-contained. ## Previous behavior diff --git a/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md index 85d372f4b8217..4723b5916daaa 100644 --- a/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md +++ b/docs/core/compatibility/sdk/8.0/runtimespecific-app-default.md @@ -5,7 +5,7 @@ ms.date: 06/05/2023 --- # Runtime-specific apps no longer self-contained -Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#publish-self-contained) by default. Instead, they are [framework-dependent](../../../deploying/index.md#publish-framework-dependent) by default. +Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#self-contained-deployment) by default. Instead, they are [framework-dependent](../../../deploying/index.md#framework-dependent-deployment) by default. This is a breaking change in the following situations: diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 2cec60b1d6f3a..8263e25ee72c4 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -64,11 +64,11 @@ The benefit of targeting a specific platform is that it can handle [native depen ### Native dependencies -If your app has native dependencies, it might not run on a different operating system. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. +If your app has native dependencies, it might not run on a different operating system if published as a portable binary. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. -Consider also, if a library you referenced has a native dependency, your app might not run on every platform. However, it's possible a NuGet package you're referencing includes platform-specific versions to handle the required native dependencies for you. +Consider also, if a library you referenced provides platform-specific dependencies, your app might not run on every platform. However, when you publish and target a specific platform, the platform-specific dependencies of a NuGet package are copied to the publish folder. -To ensure that your app is published with its native dependencies: +To ensure that your app is published with its native dependencies, publish for a specific platform: ::: zone pivot="cli,vscode" diff --git a/docs/core/deploying/native-aot/index.md b/docs/core/deploying/native-aot/index.md index 8245269150b97..79c5b2c77edf0 100644 --- a/docs/core/deploying/native-aot/index.md +++ b/docs/core/deploying/native-aot/index.md @@ -7,11 +7,11 @@ ms.date: 06/12/2023 # Native AOT deployment -Publishing your app as *Native AOT* produces an app that's [self-contained](../index.md#publish-self-contained) and that has been ahead-of-time (AOT) compiled to native code. Native AOT apps have faster startup time and smaller memory footprints. These apps can run on machines that don't have the .NET runtime installed. +Publishing your app as *Native AOT* produces an app that's [self-contained](../index.md#self-contained-deployment) and that has been ahead-of-time (AOT) compiled to native code. Native AOT apps have faster startup time and smaller memory footprints. These apps can run on machines that don't have the .NET runtime installed. The benefit of Native AOT is most significant for workloads with a high number of deployed instances, such as cloud infrastructure and hyper-scale services. .NET 8 adds [ASP.NET Core support for native AOT](/aspnet/core/fundamentals/native-aot). -The Native AOT deployment model uses an ahead-of-time compiler to compile IL to native code at the time of publish. Native AOT apps don't use a just-in-time (JIT) compiler when the application runs. Native AOT apps can run in restricted environments where a JIT isn't allowed. Native AOT applications target a specific runtime environment, such as Linux x64 or Windows x64, just like publishing a [self-contained app](../index.md#publish-self-contained). +The Native AOT deployment model uses an ahead-of-time compiler to compile IL to native code at the time of publish. Native AOT apps don't use a just-in-time (JIT) compiler when the application runs. Native AOT apps can run in restricted environments where a JIT isn't allowed. Native AOT applications target a specific runtime environment, such as Linux x64 or Windows x64, just like publishing a [self-contained app](../index.md#self-contained-deployment). ## Prerequisites @@ -132,7 +132,7 @@ Native AOT apps have the following limitations: - Windows: No built-in COM. - Requires trimming, which has [limitations](../trimming/incompatibilities.md). - Implies compilation into a single file, which has known [incompatibilities](../single-file/overview.md#api-incompatibility). -- Apps include required runtime libraries (just like [self-contained apps](../index.md#publish-self-contained), increasing their size as compared to framework-dependent apps). +- Apps include required runtime libraries (just like [self-contained apps](../index.md#self-contained-deployment), increasing their size as compared to framework-dependent apps). - always use their interpreted form, which is slower than run-time generated compiled code. - Generic parameters substituted with struct type arguments will have specialized code generated for each instantiation. In the dynamic runtime, many instantiations are generated on-demand. In Native AOT, all instantiations are pre-generated. This can have significant impact to the disk size of the application. Generic virtual methods and generic instance methods will also have an instantiation for every implementing or overriding type. - Not all the runtime libraries are fully annotated to be Native AOT compatible. That is, some warnings in the runtime libraries aren't actionable by end developers. diff --git a/docs/core/deploying/ready-to-run.md b/docs/core/deploying/ready-to-run.md index 6e10c03466dad..c0e4f653f53b8 100644 --- a/docs/core/deploying/ready-to-run.md +++ b/docs/core/deploying/ready-to-run.md @@ -83,7 +83,7 @@ These symbols will be placed in the publish directory and for Windows will have ## Composite ReadyToRun -Normal ReadyToRun compilation produces binaries that can be serviced and manipulated individually. Starting in .NET 6, support for Composite ReadyToRun compilation has been added. Composite ReadyToRun compiles a set of assemblies that must be distributed together. This has the advantage that the compiler is able to perform better optimizations and reduces the set of methods that cannot be compiled via the ReadyToRun process. However, as a tradeoff, compilation speed is significantly decreased, and the overall file size of the application is significantly increased. Due to these tradeoffs, use of Composite ReadyToRun is only recommended for applications that disable [Tiered Compilation](../runtime-config/compilation.md#tiered-compilation) or applications running on Linux that are seeking the best startup time with [self-contained](index.md#publish-self-contained) deployment. To enable composite ReadyToRun compilation, specify the `` property. +Normal ReadyToRun compilation produces binaries that can be serviced and manipulated individually. Starting in .NET 6, support for Composite ReadyToRun compilation has been added. Composite ReadyToRun compiles a set of assemblies that must be distributed together. This has the advantage that the compiler is able to perform better optimizations and reduces the set of methods that cannot be compiled via the ReadyToRun process. However, as a tradeoff, compilation speed is significantly decreased, and the overall file size of the application is significantly increased. Due to these tradeoffs, use of Composite ReadyToRun is only recommended for applications that disable [Tiered Compilation](../runtime-config/compilation.md#tiered-compilation) or applications running on Linux that are seeking the best startup time with [self-contained](index.md#self-contained-deployment) deployment. To enable composite ReadyToRun compilation, specify the `` property. ```xml @@ -92,7 +92,7 @@ Normal ReadyToRun compilation produces binaries that can be serviced and manipul ``` > [!NOTE] -> In .NET 6, Composite ReadyToRun is only supported for [self-contained](index.md#publish-self-contained) deployment. +> In .NET 6, Composite ReadyToRun is only supported for [self-contained](index.md#self-contained-deployment) deployment. ## Cross platform/architecture restrictions diff --git a/docs/core/deploying/runtime-store.md b/docs/core/deploying/runtime-store.md index da0738b770650..99cace43004fd 100644 --- a/docs/core/deploying/runtime-store.md +++ b/docs/core/deploying/runtime-store.md @@ -122,11 +122,11 @@ Specify the target manifests in the project file only when the target environmen The ASP.NET Core implicit store applies only to ASP.NET Core 2.0. We strongly recommend applications use ASP.NET Core 2.1 and later, which does **not** use the implicit store. ASP.NET Core 2.1 and later use the shared framework. -For .NET Core 2.0, the runtime package store feature is used implicitly by an ASP.NET Core app when the app is deployed as a [framework-dependent deployment](index.md#publish-framework-dependent) app. The targets in [`Microsoft.NET.Sdk.Web`](https://github.com/aspnet/websdk) include manifests referencing the implicit package store on the target system. Additionally, any framework-dependent app that depends on the `Microsoft.AspNetCore.All` package results in a published app that contains only the app and its assets and not the packages listed in the `Microsoft.AspNetCore.All` metapackage. It's assumed that those packages are present on the target system. +For .NET Core 2.0, the runtime package store feature is used implicitly by an ASP.NET Core app when the app is deployed as a [framework-dependent deployment](index.md#framework-dependent-deployment) app. The targets in [`Microsoft.NET.Sdk.Web`](https://github.com/aspnet/websdk) include manifests referencing the implicit package store on the target system. Additionally, any framework-dependent app that depends on the `Microsoft.AspNetCore.All` package results in a published app that contains only the app and its assets and not the packages listed in the `Microsoft.AspNetCore.All` metapackage. It's assumed that those packages are present on the target system. The runtime package store is installed on the host when the .NET SDK is installed. Other installers may provide the runtime package store, including Zip/tarball installations of the .NET SDK, `apt-get`, Red Hat Yum, the .NET Core Windows Server Hosting bundle, and manual runtime package store installations. -When deploying a [framework-dependent deployment](index.md#publish-framework-dependent) app, make sure that the target environment has the .NET SDK installed. If the app is deployed to an environment that doesn't include ASP.NET Core, you can opt out of the implicit store by specifying **\** set to `false` in the project file as in the following example: +When deploying a [framework-dependent deployment](index.md#framework-dependent-deployment) app, make sure that the target environment has the .NET SDK installed. If the app is deployed to an environment that doesn't include ASP.NET Core, you can opt out of the implicit store by specifying **\** set to `false` in the project file as in the following example: ```xml @@ -135,7 +135,7 @@ When deploying a [framework-dependent deployment](index.md#publish-framework-dep ``` > [!NOTE] -> For [self-contained deployment](index.md#publish-self-contained) apps, it's assumed that the target system doesn't necessarily contain the required manifest packages. Therefore, **\** cannot be set to `true` for an self-contained app. +> For [self-contained deployment](index.md#self-contained-deployment) apps, it's assumed that the target system doesn't necessarily contain the required manifest packages. Therefore, **\** cannot be set to `true` for an self-contained app. ## See also diff --git a/docs/core/deploying/single-file/overview.md b/docs/core/deploying/single-file/overview.md index 6a384628cd513..c21497352a41c 100644 --- a/docs/core/deploying/single-file/overview.md +++ b/docs/core/deploying/single-file/overview.md @@ -8,7 +8,7 @@ ms.custom: kr2b-contr-experiment # Single-file deployment -Bundling all application-dependent files into a single binary provides an application developer with the attractive option to deploy and distribute the application as a single file. Single-file deployment is available for both the [framework-dependent deployment model](../index.md#publish-framework-dependent) and [self-contained applications](../index.md#publish-self-contained). +Bundling all application-dependent files into a single binary provides an application developer with the attractive option to deploy and distribute the application as a single file. Single-file deployment is available for both the [framework-dependent deployment model](../index.md#framework-dependent-deployment) and [self-contained applications](../index.md#self-contained-deployment). The size of the single file in a self-contained application is large since it includes the runtime and the framework libraries. In .NET 6, you can [publish trimmed](../trimming/trim-self-contained.md) to reduce the total size of trim-compatible applications. The single file deployment option can be combined with [ReadyToRun](../ready-to-run.md) and [Trim](../trimming/trim-self-contained.md) publish options. diff --git a/docs/core/deploying/trimming/trim-self-contained.md b/docs/core/deploying/trimming/trim-self-contained.md index 12aa2d7d6f89e..653032800cfa1 100644 --- a/docs/core/deploying/trimming/trim-self-contained.md +++ b/docs/core/deploying/trimming/trim-self-contained.md @@ -7,7 +7,7 @@ ms.date: 04/03/2020 --- # Trim self-contained deployments and executables -The [framework-dependent deployment model](../index.md#publish-framework-dependent) has been the most successful deployment model since the inception of .NET. In this scenario, the application developer bundles only the application and third-party assemblies with the expectation that the .NET runtime and runtime libraries will be available in the client machine. This deployment model continues to be the dominant one in the latest .NET release, however, there are some scenarios where the framework-dependent model is not the best choice. The alternative is to publish a [self-contained application](../index.md#publish-self-contained), where the .NET runtime and runtime libraries are bundled together with the application and third-party assemblies. +The [framework-dependent deployment model](../index.md#framework-dependent-deployment) has been the most successful deployment model since the inception of .NET. In this scenario, the application developer bundles only the application and third-party assemblies with the expectation that the .NET runtime and runtime libraries will be available in the client machine. This deployment model continues to be the dominant one in the latest .NET release, however, there are some scenarios where the framework-dependent model is not the best choice. The alternative is to publish a [self-contained application](../index.md#self-contained-deployment), where the .NET runtime and runtime libraries are bundled together with the application and third-party assemblies. The trim-self-contained deployment model is a specialized version of the self-contained deployment model that is optimized to reduce deployment size. Minimizing deployment size is a critical requirement for some client-side scenarios like Blazor applications. Depending on the complexity of the application, only a subset of the framework assemblies are referenced, and a subset of the code within each assembly is required to run the application. The unused parts of the libraries are unnecessary and can be trimmed from the packaged application. diff --git a/docs/core/install/macos-notarization-issues.md b/docs/core/install/macos-notarization-issues.md index c5fece0a78580..0ab0881543138 100644 --- a/docs/core/install/macos-notarization-issues.md +++ b/docs/core/install/macos-notarization-issues.md @@ -36,7 +36,7 @@ You can also distribute your app without the apphost and rely on users to run yo dotnet run -p:UseAppHost=false ``` -An **appHost** is required when you publish your app [self-contained](../deploying/index.md#publish-self-contained) and you cannot disable it. +An **appHost** is required when you publish your app [self-contained](../deploying/index.md#self-contained-deployment) and you cannot disable it. For more information about the `UseAppHost` setting, see [MSBuild properties for Microsoft.NET.Sdk](../project-sdk/msbuild-props.md#useapphost). diff --git a/docs/core/native-interop/expose-components-to-com.md b/docs/core/native-interop/expose-components-to-com.md index f419bf1181d44..0d05727041dd9 100644 --- a/docs/core/native-interop/expose-components-to-com.md +++ b/docs/core/native-interop/expose-components-to-com.md @@ -123,7 +123,7 @@ There is a fully functional [COM server sample](https://github.com/dotnet/sample > [!IMPORTANT] > In .NET Framework, an "Any CPU" assembly can be consumed by both 32-bit and 64-bit clients. By default, in .NET Core, .NET 5, and later versions, "Any CPU" assemblies are accompanied by a 64-bit *\*.comhost.dll*. Because of this, they can only be consumed by 64-bit clients. That is the default because that is what the SDK represents. This behavior is identical to how the "self-contained" feature is published: by default it uses what the SDK provides. The `NETCoreSdkRuntimeIdentifier` MSBuild property determines the bitness of *\*.comhost.dll*. The managed part is actually bitness agnostic as expected, but the accompanying native asset defaults to the targeted SDK. -[Self-contained deployments](../deploying/index.md#publish-self-contained) of COM components are not supported. Only [framework-dependent deployments](../deploying/index.md#publish-framework-dependent) of COM components are supported. +[Self-contained deployments](../deploying/index.md#self-contained-deployment) of COM components are not supported. Only [framework-dependent deployments](../deploying/index.md#framework-dependent-deployment) of COM components are supported. Exposing COM components from [C++/CLI projects](/cpp/dotnet/dotnet-programming-with-cpp-cli-visual-cpp) via the [EnableComHosting property](../project-sdk/msbuild-props.md#enablecomhosting) is not supported. diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index 2f566e6c9ce97..bfd54324fbd55 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -546,7 +546,7 @@ The `PublishRelease` property informs `dotnet publish` to use the `Release` conf ### PublishSelfContained -The `PublishSelfContained` property informs `dotnet publish` to publish an app as a [self-contained app](../deploying/index.md#publish-self-contained). This property is useful when you can't use the `--self-contained` argument for the [dotnet publish](../tools/dotnet-publish.md) command—for example, when you're publishing at the solution level. In that case, you can add the `PublishSelfContained` MSBuild property to a project or *Directory.Build.Props* file. +The `PublishSelfContained` property informs `dotnet publish` to publish an app as a [self-contained app](../deploying/index.md#self-contained-deployment). This property is useful when you can't use the `--self-contained` argument for the [dotnet publish](../tools/dotnet-publish.md) command—for example, when you're publishing at the solution level. In that case, you can add the `PublishSelfContained` MSBuild property to a project or *Directory.Build.Props* file. This property was introduced in .NET 7. It's similar to the [SelfContained](#selfcontained) property, except that it's specific to the `publish` verb. It's recommended to use `PublishSelfContained` instead of `SelfContained`. @@ -626,7 +626,7 @@ The `SatelliteResourceLanguages` property lets you specify which languages you w ### SelfContained -The `SelfContained` property informs `dotnet build` and `dotnet publish` to build or publish an app as a [self-contained app](../deploying/index.md#publish-self-contained). This property is useful when you can't use the `--self-contained` argument with the [dotnet](../tools/dotnet.md) command—for example, when you're publishing at the solution level. In that case, you can add the `SelfContained` MSBuild property to a project or *Directory.Build.Props* file. +The `SelfContained` property informs `dotnet build` and `dotnet publish` to build or publish an app as a [self-contained app](../deploying/index.md#self-contained-deployment). This property is useful when you can't use the `--self-contained` argument with the [dotnet](../tools/dotnet.md) command—for example, when you're publishing at the solution level. In that case, you can add the `SelfContained` MSBuild property to a project or *Directory.Build.Props* file. This property is similar to the [PublishSelfContained](#publishselfcontained) property. It's recommended to use `PublishSelfContained` instead of `SelfContained` when possible. diff --git a/docs/core/rid-catalog.md b/docs/core/rid-catalog.md index d703e4e83d6c1..dcd84c686cf70 100644 --- a/docs/core/rid-catalog.md +++ b/docs/core/rid-catalog.md @@ -84,7 +84,7 @@ There are some considerations about RIDs that you have to keep in mind when work To be able to use RIDs, you have to know which RIDs exist. For the latest and complete version, see the [PortableRuntimeIdentifierGraph.json](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.NETCore.Platforms/src/PortableRuntimeIdentifierGraph.json) in the [`dotnet/runtime`](https://github.com/dotnet/runtime) repository. -RIDs that are considered 'portable'—that is, aren't tied to a specific version or OS distribution—are the recommended choice. This means that portable RIDs should be used for both [building a platform-specific application](./deploying/index.md#platform-specific-and-framework-dependent) and [creating a NuGet package with RID-specific assets](/nuget/create-packages/supporting-multiple-target-frameworks#architecture-specific-folders). +RIDs that are considered 'portable'—that is, aren't tied to a specific version or OS distribution—are the recommended choice. This means that portable RIDs should be used for both [building a platform-specific application](./deploying/index.md#native-dependencies) and [creating a NuGet package with RID-specific assets](/nuget/create-packages/supporting-multiple-target-frameworks#architecture-specific-folders). Starting with .NET 8, the default behavior of the .NET SDK and runtime is to only consider non-version-specific and non-distro-specific RIDs. When restoring and building, the SDK [uses a smaller portable RID graph](./compatibility/sdk/8.0/rid-graph.md). The [returns the platform for which the runtime was built](./compatibility/core-libraries/8.0/runtimeidentifier.md). At run time, .NET finds [RID-specific assets using a known set of portable RIDs](./compatibility/deployment/8.0/rid-asset-list.md). When building an application with RID-specific assets that may be ignored at runtime, the SDK will emit a warning: [NETSDK1206](./tools/sdk-errors/netsdk1206.md). diff --git a/docs/core/runtime-discovery/troubleshoot-app-launch.md b/docs/core/runtime-discovery/troubleshoot-app-launch.md index 548a4f17ed960..592eeeaacc143 100644 --- a/docs/core/runtime-discovery/troubleshoot-app-launch.md +++ b/docs/core/runtime-discovery/troubleshoot-app-launch.md @@ -9,7 +9,7 @@ zone_pivot_groups: operating-systems-set-one # Troubleshoot app launch failures -This article describes some common reasons and possible solutions for application launch failures. It relates to [framework-dependent applications](../deploying/index.md#publish-framework-dependent), which rely on a .NET installation on your machine. +This article describes some common reasons and possible solutions for application launch failures. It relates to [framework-dependent applications](../deploying/index.md#framework-dependent-deployment), which rely on a .NET installation on your machine. If you already know which .NET version you need, you can download it from [.NET downloads](https://dotnet.microsoft.com/download/dotnet). @@ -295,4 +295,4 @@ For more information, see [Multi-level lookup is disabled](../compatibility/depl - [Install .NET](../install/index.yml) - [.NET install locations](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md) - [Check installed .NET versions](../install/how-to-detect-installed-versions.md) -- [Framework-dependent applications](../deploying/index.md#publish-framework-dependent) +- [Framework-dependent applications](../deploying/index.md#framework-dependent-deployment) diff --git a/docs/core/tools/dotnet-clean.md b/docs/core/tools/dotnet-clean.md index aaf3f2b5a1534..912e73e70ab15 100644 --- a/docs/core/tools/dotnet-clean.md +++ b/docs/core/tools/dotnet-clean.md @@ -62,7 +62,7 @@ The MSBuild project or solution to clean. If a project or solution file is not s * **`-r|--runtime `** - Cleans the output folder of the specified runtime. This is used when a [self-contained deployment](../deploying/index.md#publish-self-contained) was created. + Cleans the output folder of the specified runtime. This is used when a [self-contained deployment](../deploying/index.md#self-contained-deployment) was created. [!INCLUDE [tl](../../../includes/cli-tl.md)] diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index fc38e34a42683..b4dbddcb7602f 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -226,15 +226,15 @@ For more information, see the following resources: ## Examples -- Create a [framework-dependent cross-platform binary](../deploying/index.md#produce-a-cross-platform-binary) for the project in the current directory: +- Create a [framework-dependent cross-platform binary](../deploying/index.md#cross-platform-dll-deployment) for the project in the current directory: ```dotnetcli dotnet publish ``` - Starting with .NET Core 3.0 SDK, this example also creates a [framework-dependent executable](../deploying/index.md#publish-framework-dependent) for the current platform. + Starting with .NET Core 3.0 SDK, this example also creates a [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) for the current platform. -- Create a [self-contained executable](../deploying/index.md#publish-self-contained) for the project in the current directory, for a specific runtime: +- Create a [self-contained executable](../deploying/index.md#self-contained-deployment) for the project in the current directory, for a specific runtime: ```dotnetcli dotnet publish --runtime osx-x64 @@ -242,7 +242,7 @@ For more information, see the following resources: The RID must be in the project file. -- Create a [framework-dependent executable](../deploying/index.md#publish-framework-dependent) for the project in the current directory, for a specific platform: +- Create a [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) for the project in the current directory, for a specific platform: ```dotnetcli dotnet publish --runtime osx-x64 --self-contained false diff --git a/docs/core/tools/sdk-errors/netsdk1071.md b/docs/core/tools/sdk-errors/netsdk1071.md index e01bed73f07a3..2b85dbed857e6 100644 --- a/docs/core/tools/sdk-errors/netsdk1071.md +++ b/docs/core/tools/sdk-errors/netsdk1071.md @@ -24,7 +24,7 @@ Since the `TargetFramework` automatically brings in a version of the metapackage To resolve this: 1. When you target .NET Core or .NET Standard, consider avoiding explicit references to `Microsoft.NETCore.App` or `NETStandard.Library` in your project file. -2. If you need a specific version of the runtime when targeting .NET Core, use the ``property instead of referencing the metapackage directly. As an example, this could happen if you're using [self-contained deployments](../../deploying/index.md#publish-self-contained) and need a specific patch of the 1.0.0 LTS runtime. +2. If you need a specific version of the runtime when targeting .NET Core, use the ``property instead of referencing the metapackage directly. As an example, this could happen if you're using [self-contained deployments](../../deploying/index.md#self-contained-deployment) and need a specific patch of the 1.0.0 LTS runtime. 3. If you need a specific version of `NetStandard.Library` when targeting .NET Standard, you can use the `` property and set it to the version you need. 4. Don't explicitly add or update references to either `Microsoft.NETCore.App` or `NETSTandard.Library` in .NET Framework projects. NuGet automatically installs any version of `NETStandard.Library` you need when using a .NET Standard-based NuGet package. 5. Do not specify a version for `Microsoft.AspNetCore.App` or `Microsoft.AspNetCore.All` when using .NET Core 2.1+, as the .NET SDK automatically selects the appropriate version. (Note: This only works when targeting .NET Core 2.1 if the project also uses `Microsoft.NET.Sdk.Web`. This problem was resolved in the .NET Core 2.2 SDK.) diff --git a/docs/core/tools/troubleshoot-usage-issues.md b/docs/core/tools/troubleshoot-usage-issues.md index 809852ddf71f4..ba7fcd5fc23bb 100644 --- a/docs/core/tools/troubleshoot-usage-issues.md +++ b/docs/core/tools/troubleshoot-usage-issues.md @@ -69,7 +69,7 @@ If you're trying to run a .NET tool that was installed with a specified path, yo ### Runtime not found -.NET tools are [framework-dependent applications](../deploying/index.md#publish-framework-dependent), which means they rely on a .NET runtime installed on your machine. If the expected runtime isn't found, they follow normal .NET runtime roll-forward rules such as: +.NET tools are [framework-dependent applications](../deploying/index.md#framework-dependent-deployment), which means they rely on a .NET runtime installed on your machine. If the expected runtime isn't found, they follow normal .NET runtime roll-forward rules such as: - An application rolls forward to the highest patch release of the specified major and minor version. - If there's no matching runtime with a matching major and minor version number, the next higher minor version is used. diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 083e7a04f2a76..245c105ccf13b 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -81,7 +81,7 @@ For more information, see [.NET 5 and .NET Standard](../../standard/net-standard ## Framework-dependent apps roll-forward -When you run an application from source with [`dotnet run`](../tools/dotnet-run.md), from a [**framework-dependent deployment**](../deploying/index.md#publish-framework-dependent) with [`dotnet myapp.dll`](../tools/dotnet.md#description), or from a [**framework-dependent executable**](../deploying/index.md#publish-framework-dependent) with `myapp.exe`, the `dotnet` executable is the **host** for the application. +When you run an application from source with [`dotnet run`](../tools/dotnet-run.md), from a [**framework-dependent deployment**](../deploying/index.md#framework-dependent-deployment) with [`dotnet myapp.dll`](../tools/dotnet.md#description), or from a [**framework-dependent executable**](../deploying/index.md#framework-dependent-deployment) with `myapp.exe`, the `dotnet` executable is the **host** for the application. The host chooses the latest patch version installed on the machine. For example, if you specified `net5.0` in your project file, and `5.0.2` is the latest .NET runtime installed, the `5.0.2` runtime is used. @@ -173,7 +173,7 @@ Then the resolved version is as follows in each case: ## Self-contained deployments include the selected runtime -You can publish an application as a [**self-contained distribution**](../deploying/index.md#publish-self-contained). This approach bundles the .NET runtime and libraries with your application. Self-contained deployments don't have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run time. +You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployment). This approach bundles the .NET runtime and libraries with your application. Self-contained deployments don't have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run time. The *restore* event that occurs when publishing selects the latest patch version of the given runtime family. For example, `dotnet publish` will select .NET 5.0.3 if it's the latest patch version in the .NET 5 runtime family. The target framework (including the latest installed security patches) is packaged with the application. diff --git a/docs/core/whats-new/dotnet-core-2-2.md b/docs/core/whats-new/dotnet-core-2-2.md index 0d9c49d531114..e34f5eeee6018 100644 --- a/docs/core/whats-new/dotnet-core-2-2.md +++ b/docs/core/whats-new/dotnet-core-2-2.md @@ -12,7 +12,7 @@ ms.date: 12/04/2018 ## New deployment mode -Starting with .NET Core 2.2, you can deploy [framework-dependent executables](../deploying/index.md#publish-framework-dependent), which are **.exe** files instead of **.dll** files. Functionally similar to framework-dependent deployments, framework-dependent executables (FDE) still rely on the presence of a shared system-wide version of .NET Core to run. Your app contains only your code and any third-party dependencies. Unlike framework-dependent deployments, FDEs are platform-specific. +Starting with .NET Core 2.2, you can deploy [framework-dependent executables](../deploying/index.md#framework-dependent-deployment), which are **.exe** files instead of **.dll** files. Functionally similar to framework-dependent deployments, framework-dependent executables (FDE) still rely on the presence of a shared system-wide version of .NET Core to run. Your app contains only your code and any third-party dependencies. Unlike framework-dependent deployments, FDEs are platform-specific. This new deployment mode has the distinct advantage of building an executable instead of a library, which means you can run your app directly without invoking `dotnet` first. diff --git a/docs/core/whats-new/dotnet-core-3-0.md b/docs/core/whats-new/dotnet-core-3-0.md index 88a14598d26de..1282026525dd8 100644 --- a/docs/core/whats-new/dotnet-core-3-0.md +++ b/docs/core/whats-new/dotnet-core-3-0.md @@ -56,7 +56,7 @@ If you're using Visual Studio, you need [Visual Studio 2019](https://visualstudi ### Default executables -.NET Core now builds [framework-dependent executables](../deploying/index.md#publish-framework-dependent) by default. This behavior is new for applications that use a globally installed version of .NET Core. Previously, only [self-contained deployments](../deploying/index.md#publish-self-contained) would produce an executable. +.NET Core now builds [framework-dependent executables](../deploying/index.md#framework-dependent-deployment) by default. This behavior is new for applications that use a globally installed version of .NET Core. Previously, only [self-contained deployments](../deploying/index.md#self-contained-deployment) would produce an executable. During `dotnet build` or `dotnet publish`, an executable (known as the **appHost**) is created that matches the environment and platform of the SDK you're using. You can expect the same things with these executables as you would other native executables, such as: @@ -71,7 +71,7 @@ Starting with the notarized .NET Core SDK 3.0 for macOS, the setting to produce When the appHost setting is enabled, .NET Core generates a native Mach-O executable when you build or publish. Your app runs in the context of the appHost when it is run from source code with the `dotnet run` command, or by starting the Mach-O executable directly. -Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md#publish-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-self-contained). +Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md#framework-dependent-deployment) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#self-contained-deployment). You can either configure the appHost at the project level, or toggle the appHost for a specific `dotnet` command with the `-p:UseAppHost` parameter: @@ -328,7 +328,7 @@ Windows offers a rich native API in the form of flat C APIs, COM, and WinRT. Whi [MSIX](/windows/msix/) is a new Windows application package format. It can be used to deploy .NET Core 3.0 desktop applications to Windows 10. -The [Windows Application Packaging Project](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net), available in Visual Studio 2019, allows you to create MSIX packages with [self-contained](../deploying/index.md#publish-self-contained) .NET Core applications. +The [Windows Application Packaging Project](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net), available in Visual Studio 2019, allows you to create MSIX packages with [self-contained](../deploying/index.md#self-contained-deployment) .NET Core applications. The .NET Core project file must specify the supported runtimes in the `` property: diff --git a/docs/core/whats-new/dotnet-core-3-1.md b/docs/core/whats-new/dotnet-core-3-1.md index cffe958ce594f..b521930017199 100644 --- a/docs/core/whats-new/dotnet-core-3-1.md +++ b/docs/core/whats-new/dotnet-core-3-1.md @@ -39,7 +39,7 @@ Starting with the notarized .NET Core SDK 3.1 for macOS, the appHost setting is When the appHost setting is enabled, .NET Core generates a native Mach-O executable when you build or publish. Your app runs in the context of the appHost when it is run from source code with the `dotnet run` command, or by starting the Mach-O executable directly. -Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md#publish-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-self-contained). +Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md#framework-dependent-deployment) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#self-contained-deployment). You can either configure the appHost at the project level, or toggle the appHost for a specific `dotnet` command with the `-p:UseAppHost` parameter: diff --git a/docs/standard/glossary.md b/docs/standard/glossary.md index d436268246d73..dd7bb07d25da7 100644 --- a/docs/standard/glossary.md +++ b/docs/standard/glossary.md @@ -117,7 +117,7 @@ The word "framework" has a different meaning in the following terms: - [shared framework](#shared-framework) - [target framework](#target-framework) - [TFM (target framework moniker)](#tfm) -- [framework-dependent app](../core/deploying/index.md#publish-framework-dependent) +- [framework-dependent app](../core/deploying/index.md#framework-dependent-deployment) Sometimes "framework" refers to an [implementation of .NET](#implementation-of-net). @@ -291,7 +291,7 @@ The word "runtime" has a different meaning in some contexts: - *.NET runtime* on the [.NET 5 download page](https://dotnet.microsoft.com/download/dotnet/5.0). - You can download the *.NET runtime* or other runtimes, such as the *ASP.NET Core runtime*. A *runtime* in this usage is the set of components that must be installed on a machine to run a [framework-dependent](../core/deploying/index.md#publish-framework-dependent) app on the machine. The .NET runtime includes the [CLR](#clr) and the .NET [shared framework](#shared-framework), which provides the [BCL](#bcl). + You can download the *.NET runtime* or other runtimes, such as the *ASP.NET Core runtime*. A *runtime* in this usage is the set of components that must be installed on a machine to run a [framework-dependent](../core/deploying/index.md#framework-dependent-deployment) app on the machine. The .NET runtime includes the [CLR](#clr) and the .NET [shared framework](#shared-framework), which provides the [BCL](#bcl). - *.NET runtime libraries* @@ -312,7 +312,7 @@ Meaning depends on context. The *.NET shared framework* refers to the libraries There are other shared frameworks. The *ASP.NET Core shared framework* refers to the libraries included in the [ASP.NET Core runtime](#runtime), which includes the BCL plus additional APIs for use by web apps. -For [framework-dependent apps](../core/deploying/index.md#publish-framework-dependent), the shared framework consists of libraries that are contained in assemblies installed in a folder on the machine that runs the app. For [self-contained apps](../core/deploying/index.md#publish-self-contained), the shared framework assemblies are included with the app. +For [framework-dependent apps](../core/deploying/index.md#framework-dependent-deployment), the shared framework consists of libraries that are contained in assemblies installed in a folder on the machine that runs the app. For [self-contained apps](../core/deploying/index.md#self-contained-deployment), the shared framework assemblies are included with the app. For more information, see [Deep-dive into .NET Core primitives, part 2: the shared framework](https://natemcmaster.com/blog/2018/08/29/netcore-primitives-2/). diff --git a/docs/standard/runtime-libraries-overview.md b/docs/standard/runtime-libraries-overview.md index 05023f12d0bd0..1230de6cbc559 100644 --- a/docs/standard/runtime-libraries-overview.md +++ b/docs/standard/runtime-libraries-overview.md @@ -42,4 +42,4 @@ The following table shows some examples of package-provided libraries. * [Introduction to .NET](../core/introduction.md) * [Install .NET SDK or runtime](../core/install/index.yml) * [Select the installed .NET SDK or runtime version to use](../core/versions/selection.md) -* [Publish framework-dependent apps](../core/deploying/index.md#publish-framework-dependent) +* [Publish framework-dependent apps](../core/deploying/index.md#framework-dependent-deployment) From 8ac00e80d35b4b7c2991961b0fa0f10cef8578d3 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 16:54:12 -0700 Subject: [PATCH 21/29] Redirect deploy/publish articles --- .openpublishing.redirection.core.json | 4 +- docs/core/deploying/publish-with-cli.md | 243 ------------------------ docs/core/deploying/publish-with-vs.md | 191 ------------------- 3 files changed, 2 insertions(+), 436 deletions(-) delete mode 100644 docs/core/deploying/publish-with-cli.md delete mode 100644 docs/core/deploying/publish-with-vs.md diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index dbd7049a250cb..9454def34d3a5 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -388,11 +388,11 @@ }, { "source_path_from_root": "docs/core/deploying/deploy-with-cli.md", - "redirect_url": "/dotnet/core/deploying/publish-with-cli" + "redirect_url": "/dotnet/core/deploying/index" }, { "source_path_from_root": "docs/core/deploying/deploy-with-vs.md", - "redirect_url": "/dotnet/core/deploying/publish-with-vs" + "redirect_url": "/dotnet/core/deploying/index" }, { "source_path_from_root": "/docs/core/deploying/fixing-warnings.md", diff --git a/docs/core/deploying/publish-with-cli.md b/docs/core/deploying/publish-with-cli.md deleted file mode 100644 index e7d9cfbe8b347..0000000000000 --- a/docs/core/deploying/publish-with-cli.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: Publish apps with the .NET CLI -description: Learn to publish a .NET application using the .NET CLI commands. -author: adegeo -ms.author: adegeo -ms.date: 08/07/2025 -ms.custom: updateeachrelease -ai-usage: ai-assisted -dev_langs: - - "csharp" - - "vb" ---- - -# Publish .NET apps with the .NET CLI - -This article demonstrates how you can publish your .NET application from the command line. .NET provides several ways to publish your applications. Framework-dependent deployment produces a cross-platform .dll file that uses the locally installed .NET runtime. Framework-dependent executable produces a platform-specific executable that uses the locally installed .NET runtime. Self-contained executable produces a platform-specific executable and includes a local copy of the .NET runtime. - -For an overview of these publishing modes, see [.NET Application Deployment](index.md). - -Looking for some quick help on using the CLI? The following table shows some examples of how to publish your app. You can specify the target framework with the `-f ` parameter or by editing the project file. For more information, see [Publishing basics](#publishing-basics). - -| Publish Mode | Command | -|-------------------------------------------------------------------|----------------------------------------------------------------| -| [Framework-dependent deployment](#framework-dependent-deployment) | `dotnet publish -c Release [-r ] -p:UseAppHost=false` | -| [Framework-dependent executable](#framework-dependent-executable) | `dotnet publish -c Release [-r ]`
`dotnet publish -c Release [-r ] --self-contained false`
| -| [Self-contained deployment](#self-contained-deployment) | `dotnet publish -c Release [-r ] --self-contained true` | -| [Single-file deployment](#single-file-deployment) | `dotnet publish -c Release [-r ] -p:PublishSingleFile=true` | -| [Native AOT deployment](#native-aot-deployment) | `dotnet publish -c Release [-r ] -p:PublishAot=true` | -| [ReadyToRun deployment](#readytorun-deployment) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | - -> [!NOTE] -> The `-c Release` parameter isn't required and is only provided as a reminder to publish the **Release** build of your app. - -## Publishing basics - -The [``](../project-sdk/msbuild-props.md#targetframework) setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. The TFM specified in this setting is the default target used by the [`dotnet publish`](../tools/dotnet-publish.md) command. - -If you want to target more than one framework, you can set the [``](../project-sdk/msbuild-props.md#targetframeworks) setting to multiple TFM values, separated by a semicolon. When you build your app, a build is produced for each target framework. However, when you publish your app, you must specify the target framework with the `dotnet publish -f ` command. - -The default **BUILD-CONFIGURATION** mode is **Release** unless changed with the `-c` parameter. - -The default output directory of the [`dotnet publish`](../tools/dotnet-publish.md) command is `./bin///publish/`. For example, `dotnet publish -c Release -f net9.0` publishes to `./bin/Release/net9.0/publish/`. However, you can opt in to a simplified output path and folder structure for all build outputs. For more information, see [Artifacts output layout](../sdk/artifacts-output.md). - -### Native dependencies - -If your app has native dependencies, it might not run on a different operating system. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. - -Consider also, if a library you referenced has a native dependency, your app might not run on every platform. However, it's possible a NuGet package you're referencing includes platform-specific versions to handle the required native dependencies for you. - -To insure that your app is published with its native dependencies, use the `dotnet publish -r ` switch to publish your app for a specific platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). - -More information about platform-specific binaries is covered in the [Framework-dependent executable](#framework-dependent-executable) and [Self-contained deployment](#self-contained-deployment) sections. - -## Sample app - -You can use the following app to explore the publishing commands. The app is created by running the following commands in your terminal: - -```dotnetcli -dotnet new console -o apptest1 -cd apptest1 -dotnet add package Figgle.Fonts -``` - -Change the `Program.cs` or `Program.vb` code to the following snippet: - -:::code language="csharp" source="./snippets/shared/publish/csharp/Program.cs"::: - -:::code language="vb" source="./snippets/shared/publish/vb/Program.vb"::: - -When you run the app ([`dotnet run`](../tools/dotnet-run.md)), the following output is displayed: - -```terminal - _ _ _ _ __ __ _ _ _ - | | | | ___| | | ___ \ \ / /__ _ __| | __| | | - | |_| |/ _ \ | |/ _ \ \ \ /\ / / _ \| '__| |/ _` | | - | _ | __/ | | (_) | \ V V / (_) | | | | (_| |_| - |_| |_|\___|_|_|\___( ) \_/\_/ \___/|_| |_|\__,_(_) - |/ -``` - -## Framework-dependent deployment - -When you publish your app as a framework-dependent deployment (FDD), a `.dll` file is created in the `./bin///publish/` folder. To run your app, navigate to the output folder and use the `dotnet .dll` command. - -Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. - -Publishing an FDD creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). - -| Publish Mode | Command | -|--------------------------------|-------------------------------------------------------------| -| Framework-dependent deployment | `dotnet publish -c Release -p:UseAppHost=false` | - -## Framework-dependent executable - -Framework-dependent executable (FDE) is the default mode for the basic `dotnet publish` command. You don't need to specify any other parameters, as long as you want to target the current operating system. - -In this mode, a platform-specific executable host is created to host your cross-platform app. This mode is similar to FDD, as FDD requires a host in the form of the `dotnet` command. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. - -Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. - -Publishing an FDE creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). - -| Publish Mode | Command | -|--------------------------------|-------------------------------------------------------------| -| Framework-dependent executable | `dotnet publish -c Release -r --self-contained false`
`dotnet publish -c Release` | - -Whenever you use the `-r` switch, the output folder path changes to: `./bin////publish/` - -If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 --self-contained false`. This command creates the following executable: `./bin/Debug/net9.0/win-x64/publish/apptest1.exe` - -> [!NOTE] -> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). - -### Configure .NET install search behavior - -In .NET 9 and later versions, you can configure the .NET installation search paths of the published executable via the [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch) and [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) properties. - -`AppHostDotNetSearch` allows specifying one or more locations where the executable looks for a .NET installation: - -- `AppLocal`: app executable's folder -- `AppRelative`: path relative to the app executable -- `EnvironmentVariables`: value of [`DOTNET_ROOT[_]`](../tools/dotnet-environment-variables.md#dotnet_root-dotnet_rootx86-dotnet_root_x86-dotnet_root_x64) environment variables -- `Global`: [registered](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-custom-location) and [default](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md#global-install-to-default-location) global install locations - -`AppHostRelativeDotNet` specifies the path relative to the executable that's searched when `AppHostDotNetSearch` contains `AppRelative`. - -For more information, see [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch), [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) and [install location options in apphost](https://github.com/dotnet/designs/blob/main/proposed/apphost-embed-install-location.md). - -## Self-contained deployment - -When you publish a self-contained deployment (SCD), the .NET SDK creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the native dependencies of .NET (for example, for [.NET 8 on Linux](https://github.com/dotnet/core/blob/main/release-notes/8.0/linux-packages.md)). These dependencies must be present on the system before the app runs. - -Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). - -You must use the following switches with the `dotnet publish` command to publish an SCD: - -- `-r ` - - This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. - -- `--self-contained true` - - This switch tells the .NET SDK to create an executable as an SCD. - -| Publish Mode | Command | -|--------------------------------|-------------------------------------------------------------| -| Self-contained deployment | `dotnet publish -c Release -r --self-contained true` | - -> [!TIP] -> -> - You can reduce the total size of compatible self-contained apps by [publishing trimmed](trimming/trim-self-contained.md). This enables the trimmer to remove parts of the framework and referenced assemblies that aren't on any code path or potentially referenced in [runtime reflection](../../csharp/advanced-topics/reflection-and-attributes/index.md). See [trimming incompatibilities](./trimming/incompatibilities.md) to determine if trimming makes sense for your application. -> - You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). - -## Single-file deployment - -When you publish your app as a single-file deployment, all application-dependent files are bundled into a single binary. This deployment model is available for both framework-dependent and self-contained applications, providing an attractive option to deploy and distribute your application as a single file. - -Single-file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth. Runtime configuration files, such as _\*.runtimeconfig.json_ and _\*.deps.json_, are included in the single file. - -The size of a single file in a self-contained application is large since it includes the runtime and framework libraries. You can combine single-file deployment with other publish options like [trimming](trimming/trim-self-contained.md) and [ReadyToRun](#readytorun-deployment) to optimize the deployment. - -You must use the following switches with the `dotnet publish` command to publish a single-file app: - -- `-r ` - - This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. - -- `-p:PublishSingleFile=true` - - This switch tells the .NET SDK to bundle the app into a single file. - -| Publish Mode | Command | -|-----------------------|-------------------------------------------------------------| -| Single-file deployment | `dotnet publish -c Release -r -p:PublishSingleFile=true` | - -If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 -p:PublishSingleFile=true`. This command creates a single executable file in the `./bin/Debug/net9.0/win-x64/publish/` folder. - -For more information about single-file deployment, see [Single-file deployment](single-file/overview.md). - -## Native AOT deployment - -When you publish your app as Native AOT, your application is ahead-of-time (AOT) compiled to native code. Native AOT apps are [self-contained](index.md#publish-self-contained) and have faster startup time and smaller memory footprints. These apps can run on machines that don't have the .NET runtime installed. - -Native AOT apps don't use a just-in-time (JIT) compiler when the application runs. The ahead-of-time compiler compiles IL to native code at publish time. Native AOT applications target a specific runtime environment, such as Linux x64 or Windows x64. - -The benefit of Native AOT is most significant for workloads with a high number of deployed instances, such as cloud infrastructure and hyper-scale services. - -You must use the following switches with the `dotnet publish` command to publish a Native AOT app: - -- `-r ` - - This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. - -- `-p:PublishAot=true` - - This switch tells the .NET SDK to compile the app with Native AOT. - -| Publish Mode | Command | -|-----------------------|-------------------------------------------------------------| -| Native AOT deployment | `dotnet publish -c Release -r -p:PublishAot=true` | - -> [!NOTE] -> Native AOT has specific requirements and limitations. Not all .NET features are supported in Native AOT. For detailed information about prerequisites, limitations, and compatibility, see [Native AOT deployment](native-aot/index.md). - -If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 -p:PublishAot=true`. This command creates a native executable in the `./bin/Debug/net9.0/win-x64/publish/` folder. - -For more information about Native AOT deployment, see [Native AOT deployment overview](native-aot/index.md). - -## ReadyToRun deployment - -When you publish your app with ReadyToRun compilation, your application assemblies are compiled as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation that improves startup performance by reducing the amount of work the just-in-time (JIT) compiler needs to do as your application loads. - -ReadyToRun binaries contain both intermediate language (IL) code and the native version of the same code. While R2R binaries are larger than regular assemblies, they provide better startup performance. ReadyToRun is only available when you publish an app that targets specific runtime environments (RID) such as Linux x64 or Windows x64. - -The startup improvement applies not only to application startup, but also to the first use of any code in the application. For instance, ReadyToRun can reduce the response latency of the first use of Web API in an ASP.NET application. - -You must use the following switches with the `dotnet publish` command to publish a ReadyToRun app: - -- `-r ` - - This switch uses an identifier (RID) to specify the target platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). If this switch is omitted, the current platform is used. - -- `-p:PublishReadyToRun=true` - - This switch tells the .NET SDK to compile assemblies with ReadyToRun. - -| Publish Mode | Command | -|-----------------------|-------------------------------------------------------------| -| ReadyToRun deployment | `dotnet publish -c Release -r -p:PublishReadyToRun=true` | - -> [!NOTE] -> ReadyToRun compilation increases the size of your assemblies. The size of an assembly typically grows to between two to three times larger. This increase in physical size might reduce performance of loading the assembly from disk and increase working set of the process. - -If you use the [example app](#sample-app), run `dotnet publish -f net9.0 -r win-x64 -p:PublishReadyToRun=true`. This command creates ReadyToRun compiled assemblies in the `./bin/Debug/net9.0/win-x64/publish/` folder. - -ReadyToRun can be combined with other publish options like [single-file deployment](#single-file-deployment) and [trimming](trimming/trim-self-contained.md) for more optimizations. - -For more information about ReadyToRun deployment, see [ReadyToRun compilation](ready-to-run.md). - -## See also - -- [.NET Application Deployment Overview](index.md)y -- [.NET Runtime Identifier (RID) catalog](../rid-catalog.md) diff --git a/docs/core/deploying/publish-with-vs.md b/docs/core/deploying/publish-with-vs.md deleted file mode 100644 index fcfd552a87ab3..0000000000000 --- a/docs/core/deploying/publish-with-vs.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: Publish apps with Visual Studio -description: Learn to publish a .NET application using Visual Studio. -author: adegeo -ms.author: adegeo -ms.date: 08/08/2025 -ms.custom: vs-dotnet, updateeachrelease -ai-usage: ai-generated -dev_langs: - - "csharp" - - "vb" ---- - -# Publish .NET apps with Visual Studio - -This article demonstrates how you can publish your .NET application using Visual Studio. .NET provides several ways to publish your applications. Framework-dependent deployment produces a cross-platform .dll file that uses the locally installed .NET runtime. Framework-dependent executable produces a platform-specific executable that uses the locally installed .NET runtime. Self-contained executable produces a platform-specific executable and includes a local copy of the .NET runtime. - -For an overview of these publishing modes, see [.NET Application Deployment](index.md). - -Looking for some quick help on using Visual Studio? The following table shows some examples of how to publish your app using Visual Studio publishing profiles: - -| Publish Mode | Visual Studio Configuration | -|-------------------------------------------------------------------|----------------------------------------------------------------| -| [Framework-dependent deployment](#framework-dependent-deployment) | Set **Deployment Mode** to **Framework-dependent** and **Produce single file** to unchecked | -| [Framework-dependent executable](#framework-dependent-executable) | Set **Deployment Mode** to **Framework-dependent** (default) | -| [Self-contained deployment](#self-contained-deployment) | Set **Deployment Mode** to **Self-contained** | -| [Single-file deployment](#single-file-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Produce single file** to checked | -| [ReadyToRun deployment](#readytorun-deployment) | Set **Deployment Mode** to **Self-contained** or **Framework-dependent** and **Enable ReadyToRun compilation** to checked | - -## Publishing basics - -The [``](../project-sdk/msbuild-props.md#targetframework) setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. The TFM specified in this setting is the default target used when you publish from Visual Studio. - -If you want to target more than one framework, you can set the [``](../project-sdk/msbuild-props.md#targetframeworks) setting to multiple TFM values, separated by a semicolon. When you build your app, a build is produced for each target framework. However, when you publish your app from Visual Studio, you must create separate publishing profiles for each target framework. - -The default **BUILD-CONFIGURATION** mode is **Release** when publishing from Visual Studio. - -### Native dependencies - -If your app has native dependencies, it might not run on a different operating system. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform. - -Consider also, if a library you referenced has a native dependency, your app might not run on every platform. However, it's possible a NuGet package you're referencing includes platform-specific versions to handle the required native dependencies for you. - -To ensure that your app is published with its native dependencies, use the **Target Runtime** setting in Visual Studio to publish your app for a specific platform. For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid-catalog.md). - -More information about platform-specific binaries is covered in the [Framework-dependent executable](#framework-dependent-executable) and [Self-contained deployment](#self-contained-deployment) sections. - -## Sample app - -You can use the following app to explore the publishing options in Visual Studio. The app is created by doing the following in Visual Studio: - -01. Select **File** > **New** > **Project**. -01. In the **Create a new project** dialog, search for "console" and select **Console App**. -01. Select **Next**. -01. Enter a project name, such as "AppTest1", and select **Next**. -01. Choose the latest framework version and select **Create**. -01. In **Solution Explorer**, right-click on the project and select **Manage NuGet Packages...**. -01. Select the **Browse** tab. -01. Search for "Figgle.Fonts" and install the package. - -Change the `Program.cs` or `Program.vb` code to the following snippet: - -:::code language="csharp" source="./snippets/shared/publish/csharp/Program.cs"::: - -:::code language="vb" source="./snippets/shared/publish/vb/Program.vb"::: - -When you run the app ([`dotnet run`](../tools/dotnet-run.md)), the following output is displayed: - -```terminal - _ _ _ _ __ __ _ _ _ - | | | | ___| | | ___ \ \ / /__ _ __| | __| | | - | |_| |/ _ \ | |/ _ \ \ \ /\ / / _ \| '__| |/ _` | | - | _ | __/ | | (_) | \ V V / (_) | | | | (_| |_| - |_| |_|\___|_|_|\___( ) \_/\_/ \___/|_| |_|\__,_(_) - |/ -``` - -## Framework-dependent deployment - -When you publish your app as a framework-dependent deployment (FDD), a `.dll` file is created in the publish output folder. To run your app, navigate to the output folder and use the `dotnet .dll` command. - -Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. - -Publishing an FDD creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). - -To publish a framework-dependent deployment from Visual Studio: - -01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. -01. Set **Deployment Mode** to **Framework-dependent**. -01. Uncheck **Produce single file**. -01. Set **Target Runtime** to **Portable** (or leave blank). -01. Click **Save** and then **Publish**. - -## Framework-dependent executable - -Framework-dependent executable (FDE) is the default mode when you publish from Visual Studio. You don't need to specify any other parameters, as long as you want to target the current operating system. - -In this mode, a platform-specific executable host is created to host your cross-platform app. This mode is similar to FDD, as FDD requires a host in the form of the `dotnet` command. The host executable filename varies per platform and is named something similar to `.exe`. You can run this executable directly instead of calling `dotnet .dll`, which is still an acceptable way to run the app. - -Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on any machine where your app runs. For example, if your app targets .NET 9, any machine that your app runs on must have the .NET 9 runtime installed. As stated in the [Publishing basics](#publishing-basics) section, you can edit your project file to change the default target framework or to target more than one framework. - -Publishing an FDE creates an app that automatically rolls-forward to the latest .NET security patch available on the system that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). - -To publish a framework-dependent executable from Visual Studio: - -01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. -01. Set **Deployment Mode** to **Framework-dependent** (this is the default). -01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Click **Save** and then **Publish**. - -> [!NOTE] -> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). - -## Self-contained deployment - -When you publish a self-contained deployment (SCD), Visual Studio creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the native dependencies of .NET. These dependencies must be present on the system before the app runs. - -Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). - -To publish a self-contained deployment from Visual Studio: - -01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. -01. Set **Deployment Mode** to **Self-contained**. -01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Click **Save** and then **Publish**. - -> [!TIP] -> -> - You can reduce the total size of compatible self-contained apps by [publishing trimmed](trimming/trim-self-contained.md). This enables the trimmer to remove parts of the framework and referenced assemblies that aren't on any code path or potentially referenced in [runtime reflection](../../csharp/advanced-topics/reflection-and-attributes/index.md). See [trimming incompatibilities](trimming/incompatibilities.md) to determine if trimming makes sense for your application. -> - You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that aren't globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). - -## Single-file deployment - -When you publish your app as a single-file deployment, all application-dependent files are bundled into a single binary. This deployment model is available for both framework-dependent and self-contained applications, providing an attractive option to deploy and distribute your application as a single file. - -Single-file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth. Runtime configuration files, such as *\*.runtimeconfig.json* and *\*.deps.json*, are included in the single file. - -The size of a single file in a self-contained application is large since it includes the runtime and framework libraries. You can combine single-file deployment with other publish options like [trimming](trimming/trim-self-contained.md) and [ReadyToRun](#readytorun-deployment) to optimize the deployment. - -To publish a single-file deployment from Visual Studio: - -01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. -01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. -01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Check **Produce single file**. -01. Click **Save** and then **Publish**. - -For more information about single-file deployment, see [Single-file deployment](single-file/overview.md). - -## ReadyToRun deployment - -When you publish your app with ReadyToRun compilation, your application assemblies are compiled as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation that improves startup performance by reducing the amount of work the just-in-time (JIT) compiler needs to do as your application loads. - -ReadyToRun binaries contain both intermediate language (IL) code and the native version of the same code. While R2R binaries are larger than regular assemblies, they provide better startup performance. ReadyToRun is only available when you publish an app that targets specific runtime environments (RID) such as Linux x64 or Windows x64. - -The startup improvement applies not only to application startup, but also to the first use of any code in the application. For instance, ReadyToRun can reduce the response latency of the first use of Web API in an ASP.NET application. - -To publish a ReadyToRun deployment from Visual Studio: - -01. Right-click on the project in **Solution Explorer** and select **Publish**. -01. If this is your first time publishing, select **Folder** as the publish target and click **Next**. -01. Choose a folder location or accept the default, then click **Finish**. -01. In the publish profile, click **Show all settings**. -01. Set **Deployment Mode** to **Self-contained** or **Framework-dependent**. -01. Set **Target Runtime** to your desired platform (for example, **win-x64** for 64-bit Windows). -01. Check **Enable ReadyToRun compilation**. -01. Click **Save** and then **Publish**. - -> [!NOTE] -> ReadyToRun compilation increases the size of your assemblies. The size of an assembly typically grows to between two to three times larger. This increase in physical size might reduce performance of loading the assembly from disk and increase working set of the process. - -ReadyToRun can be combined with other publish options like [single-file deployment](#single-file-deployment) and [trimming](trimming/trim-self-contained.md) for more optimizations. - -For more information about ReadyToRun deployment, see [ReadyToRun compilation](ready-to-run.md). - -## See also - -- [.NET Application Deployment](index.md) -- [.NET Runtime Identifier (RID) catalog](../rid-catalog.md) From 1beeb09dc8b801805fc427328413af1f8b861d59 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 17:31:54 -0700 Subject: [PATCH 22/29] Fix other links --- docs/core/deploying/single-file/overview.md | 8 +++----- docs/core/deploying/trimming/trim-self-contained.md | 8 +++----- docs/core/tools/dotnet-publish.md | 7 +++---- docs/core/tutorials/publishing-with-visual-studio-code.md | 7 +++---- docs/core/tutorials/publishing-with-visual-studio.md | 3 +-- docs/core/whats-new/dotnet-9/runtime.md | 2 +- 6 files changed, 14 insertions(+), 21 deletions(-) diff --git a/docs/core/deploying/single-file/overview.md b/docs/core/deploying/single-file/overview.md index c21497352a41c..231548313ae64 100644 --- a/docs/core/deploying/single-file/overview.md +++ b/docs/core/deploying/single-file/overview.md @@ -75,7 +75,7 @@ Publish a single file application using the [dotnet publish](../../tools/dotnet- dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained false ``` -For more information, see [Publish .NET Core apps with .NET CLI](../publish-with-cli.md). +For more information, see [.NET application publishing overview](../../deploying/index.md). # [Visual Studio](#tab/vs) @@ -105,7 +105,7 @@ Visual Studio creates reusable publishing profiles that control how your applica 1. Choose **Publish** to publish your app as a single file. -For more information, see [Publish .NET Core apps with Visual Studio](../publish-with-vs.md). +For more information, see[.NET application publishing overview](../../deploying/index.md). --- @@ -235,7 +235,5 @@ Single file apps can be inspected using the [ILSpy tool](https://ilspy.net/). Th ## See also -- [.NET Core application deployment](../index.md) -- [Publish .NET apps with .NET CLI](../publish-with-cli.md) -- [Publish .NET Core apps with Visual Studio](../publish-with-vs.md) +- [.NET application publishing overview](../../deploying/index.md) - [`dotnet publish` command](../../tools/dotnet-publish.md) diff --git a/docs/core/deploying/trimming/trim-self-contained.md b/docs/core/deploying/trimming/trim-self-contained.md index 653032800cfa1..d33ca4a1f80ad 100644 --- a/docs/core/deploying/trimming/trim-self-contained.md +++ b/docs/core/deploying/trimming/trim-self-contained.md @@ -51,7 +51,7 @@ Trimming is only supported for self-contained apps. `dotnet publish -r win-x64 -p:PublishTrimmed=true` -For more information, see [Publish .NET apps with .NET CLI](../publish-with-cli.md). +For more information, see [.NET application publishing overview](../../deploying/index.md). ### Publish with Visual Studio @@ -67,11 +67,9 @@ For more information, see [Publish .NET apps with .NET CLI](../publish-with-cli. :::image type="content" source="../media/trim-self-contained/vs-publish-trimmed.png" alt-text="Visual studio publish page with Publish Trimmed selected."::: -For more information, see [Publish .NET Core apps with Visual Studio](../publish-with-vs.md). +For more information, see [.NET application publishing overview](../../deploying/index.md). ## See also -- [.NET Core application deployment](../index.md). -- [Publish .NET apps with .NET CLI](../publish-with-cli.md). -- [Publish .NET Core apps with Visual Studio](../publish-with-vs.md). +- [.NET application publishing overview](../../deploying/index.md). - [dotnet publish command](../../tools/dotnet-publish.md). diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index b4dbddcb7602f..94ffde8e5747a 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -38,7 +38,7 @@ dotnet publish -h|--help - A *.runtimeconfig.json* file that specifies the shared runtime that the application expects, as well as other configuration options for the runtime (for example, garbage collection type). - The application's dependencies, which are copied from the NuGet cache into the output folder. -The `dotnet publish` command's output is ready for deployment to a hosting system (for example, a server, PC, Mac, laptop) for execution. It's the only officially supported way to prepare the application for deployment. Depending on the type of deployment that the project specifies, the hosting system may or may not have the .NET shared runtime installed on it. For more information, see [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md). +The `dotnet publish` command's output is ready for deployment to a hosting system (for example, a server, PC, Mac, laptop) for execution. It's the only officially supported way to prepare the application for deployment. Depending on the type of deployment that the project specifies, the hosting system may or may not have the .NET shared runtime installed on it. For more information, see [.NET application publishing overview](../deploying/index.md). ### Implicit restore @@ -196,7 +196,7 @@ For more information, see the following resources: - **`--sc|--self-contained [true|false]`** - Publishes the .NET runtime with your application so the runtime doesn't need to be installed on the target machine. Default is `true` if a runtime identifier is specified and the project is an executable project (not a library project). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md). + Publishes the .NET runtime with your application so the runtime doesn't need to be installed on the target machine. Default is `true` if a runtime identifier is specified and the project is an executable project (not a library project). For more information, see [Self-contained deployment](../deploying/index.md#self-contained-deployment). If this option is used without specifying `true` or `false`, the default is `true`. In that case, don't put the solution or project argument immediately after `--self-contained`, because `true` or `false` is expected in that position. @@ -210,7 +210,7 @@ For more information, see the following resources: - **`-r|--runtime `** - Publishes the application for a given runtime. For a list of Runtime Identifiers (RIDs), see the [RID catalog](../rid-catalog.md). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md). If you use this option, use `--self-contained` or `--no-self-contained` also. + Publishes the application for a given runtime. For a list of Runtime Identifiers (RIDs), see the [RID catalog](../rid-catalog.md). For more information, see [.NET application publishing overview](../deploying/index.md). If you use this option, use `--self-contained` or `--no-self-contained` also. [!INCLUDE [tl](../../../includes/cli-tl.md)] @@ -271,7 +271,6 @@ For more information, see the following resources: ## See also - [.NET application publishing overview](../deploying/index.md) -- [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md) - [Target frameworks](../../standard/frameworks.md) - [Runtime Identifier (RID) catalog](../rid-catalog.md) - [Containerize a .NET app with dotnet publish](../containers/sdk-publish.md) diff --git a/docs/core/tutorials/publishing-with-visual-studio-code.md b/docs/core/tutorials/publishing-with-visual-studio-code.md index 40757b129fc33..1763c8e82c5a6 100644 --- a/docs/core/tutorials/publishing-with-visual-studio-code.md +++ b/docs/core/tutorials/publishing-with-visual-studio-code.md @@ -62,11 +62,11 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.dll* - This is the [framework-dependent deployment](../deploying/publish-with-cli.md#framework-dependent-deployment) version of the application. To run this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. + This is the [framework-dependent deployment](../deploying/index.md#cross-platform-dll-deployment) version of the application. To run this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. - *HelloWorld.exe* (*HelloWorld* on Linux or macOS.) - This is the [framework-dependent executable](../deploying/publish-with-cli.md#framework-dependent-executable) version of the application. The file is operating-system-specific. + This is the [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) version of the application. The file is operating-system-specific. - *HelloWorld.pdb* (optional for deployment) @@ -98,8 +98,7 @@ In the following steps, you'll look at the files created by the publish process. ## Additional resources -- [.NET application deployment](../deploying/index.md) -- [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md) +- [.NET application publishing overview](../deploying/index.md) - [`dotnet publish`](../tools/dotnet-publish.md) - [Use the .NET SDK in continuous integration (CI) environments](../../devops/dotnet-cli-and-continuous-integration.md) diff --git a/docs/core/tutorials/publishing-with-visual-studio.md b/docs/core/tutorials/publishing-with-visual-studio.md index ea7d2fcd77e99..06ca93e692d1c 100644 --- a/docs/core/tutorials/publishing-with-visual-studio.md +++ b/docs/core/tutorials/publishing-with-visual-studio.md @@ -104,8 +104,7 @@ In the following steps, you'll look at the files created by the publish process. ## Additional resources -- [.NET application deployment](../deploying/index.md) -- [Publish .NET apps with the .NET CLI](../deploying/publish-with-cli.md) +- [.NET application publishing overview](../deploying/index.md) - [`dotnet publish`](../tools/dotnet-publish.md) - [Tutorial: Publish a .NET console application using Visual Studio Code](publishing-with-visual-studio-code.md) - [Use the .NET SDK in continuous integration (CI) environments](../../devops/dotnet-cli-and-continuous-integration.md) diff --git a/docs/core/whats-new/dotnet-9/runtime.md b/docs/core/whats-new/dotnet-9/runtime.md index 3e6c57bd0616c..0f3013839c87b 100644 --- a/docs/core/whats-new/dotnet-9/runtime.md +++ b/docs/core/whats-new/dotnet-9/runtime.md @@ -74,7 +74,7 @@ CET imposes some limitations on CET-enabled processes and can result in a small ## .NET install search behavior -.NET apps can now be configured for how they should [search for the .NET runtime](../../deploying/publish-with-cli.md#configure-net-install-search-behavior). This capability can be used with private runtime installations or to more strongly control the execution environment. +.NET apps can now be configured for how they should [search for the .NET runtime](../../deploying/index.md#configure-net-install-search-behavior). This capability can be used with private runtime installations or to more strongly control the execution environment. ## Performance improvements From 125f652b28d1fa29eaf97039ca32d02943bc73c5 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 17:36:14 -0700 Subject: [PATCH 23/29] Remove sample code no longer unsed --- .../deploy-with-vs/csharp/deploy.csproj | 9 ----- .../csharp/deployment-example.cs | 35 ------------------- .../snippets/deploy-with-vs/vb/deploy.vbproj | 9 ----- .../deploy-with-vs/vb/deployment-example.vb | 30 ---------------- .../deploy-with-vs/xml/access-by-line.txt | 1 - .../deploy-with-vs/xml/invariant.csproj | 12 ------- 6 files changed, 96 deletions(-) delete mode 100644 docs/core/deploying/snippets/deploy-with-vs/csharp/deploy.csproj delete mode 100644 docs/core/deploying/snippets/deploy-with-vs/csharp/deployment-example.cs delete mode 100644 docs/core/deploying/snippets/deploy-with-vs/vb/deploy.vbproj delete mode 100644 docs/core/deploying/snippets/deploy-with-vs/vb/deployment-example.vb delete mode 100644 docs/core/deploying/snippets/deploy-with-vs/xml/access-by-line.txt delete mode 100644 docs/core/deploying/snippets/deploy-with-vs/xml/invariant.csproj diff --git a/docs/core/deploying/snippets/deploy-with-vs/csharp/deploy.csproj b/docs/core/deploying/snippets/deploy-with-vs/csharp/deploy.csproj deleted file mode 100644 index af31fefa23aa5..0000000000000 --- a/docs/core/deploying/snippets/deploy-with-vs/csharp/deploy.csproj +++ /dev/null @@ -1,9 +0,0 @@ - - - - Exe - net8.0 - enable - - - diff --git a/docs/core/deploying/snippets/deploy-with-vs/csharp/deployment-example.cs b/docs/core/deploying/snippets/deploy-with-vs/csharp/deployment-example.cs deleted file mode 100644 index a5950f1af797e..0000000000000 --- a/docs/core/deploying/snippets/deploy-with-vs/csharp/deployment-example.cs +++ /dev/null @@ -1,35 +0,0 @@ -using System; -using System.Text.RegularExpressions; - -namespace Applications.ConsoleApps -{ - public class ConsoleParser - { - public static void Main() - { - Console.WriteLine("Enter any text, followed by :\n"); - String? s = Console.ReadLine(); - ShowWords(s ?? "You didn't enter anything."); - Console.Write("\nPress any key to continue... "); - Console.ReadKey(); - } - - private static void ShowWords(String s) - { - String pattern = @"\w+"; - var matches = Regex.Matches(s, pattern); - if (matches.Count == 0) - { - Console.WriteLine("\nNo words were identified in your input."); - } - else - { - Console.WriteLine($"\nThere are {matches.Count} words in your string:"); - for (int ctr = 0; ctr < matches.Count; ctr++) - { - Console.WriteLine($" #{ctr,2}: '{matches[ctr].Value}' at position {matches[ctr].Index}"); - } - } - } - } -} diff --git a/docs/core/deploying/snippets/deploy-with-vs/vb/deploy.vbproj b/docs/core/deploying/snippets/deploy-with-vs/vb/deploy.vbproj deleted file mode 100644 index 9dbe63c02ba99..0000000000000 --- a/docs/core/deploying/snippets/deploy-with-vs/vb/deploy.vbproj +++ /dev/null @@ -1,9 +0,0 @@ - - - - Exe - deploy - net8.0 - - - diff --git a/docs/core/deploying/snippets/deploy-with-vs/vb/deployment-example.vb b/docs/core/deploying/snippets/deploy-with-vs/vb/deployment-example.vb deleted file mode 100644 index a34a381e3ebba..0000000000000 --- a/docs/core/deploying/snippets/deploy-with-vs/vb/deployment-example.vb +++ /dev/null @@ -1,30 +0,0 @@ -Imports System.Text.RegularExpressions - -Namespace Applications.ConsoleApps - Public Module ConsoleParser - Public Sub Main() - Console.WriteLine("Enter any text, followed by :") - Console.WriteLine() - Dim s = Console.ReadLine() - ShowWords(s) - Console.Write($"{vbCrLf}Press any key to continue... ") - Console.ReadKey() - End Sub - - Private Sub ShowWords(s As String) - Dim pattern = "\w+" - Dim matches = Regex.Matches(s, pattern) - Console.WriteLine() - If matches.Count = 0 Then - Console.WriteLine("No words were identified in your input.") - Else - Console.WriteLine($"There are {matches.Count} words in your string:") - For ctr = 0 To matches.Count - 1 - Console.WriteLine($" #{ctr,2}: '{matches(ctr).Value}' at position {matches(ctr).Index}") - Next - End If - Console.WriteLine() - End Sub - End Module -End Namespace - diff --git a/docs/core/deploying/snippets/deploy-with-vs/xml/access-by-line.txt b/docs/core/deploying/snippets/deploy-with-vs/xml/access-by-line.txt deleted file mode 100644 index dacd1697af3fb..0000000000000 --- a/docs/core/deploying/snippets/deploy-with-vs/xml/access-by-line.txt +++ /dev/null @@ -1 +0,0 @@ -invariant.csproj: ~/docs/core/deploying/deploy-with-vs.md diff --git a/docs/core/deploying/snippets/deploy-with-vs/xml/invariant.csproj b/docs/core/deploying/snippets/deploy-with-vs/xml/invariant.csproj deleted file mode 100644 index 5032be67883f8..0000000000000 --- a/docs/core/deploying/snippets/deploy-with-vs/xml/invariant.csproj +++ /dev/null @@ -1,12 +0,0 @@ - - - - net8.0 - enable - - - - - - - From 290e1d85bdd2202257889196fc4c6f059a12ce68 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 17:36:22 -0700 Subject: [PATCH 24/29] More bookmark changes --- docs/core/compatibility/sdk/6.0/apphost-generated-for-macos.md | 2 +- docs/core/docker/build-container.md | 2 +- docs/core/project-sdk/msbuild-props.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/sdk/6.0/apphost-generated-for-macos.md b/docs/core/compatibility/sdk/6.0/apphost-generated-for-macos.md index 59f552bfacec7..96ec415ad532d 100644 --- a/docs/core/compatibility/sdk/6.0/apphost-generated-for-macos.md +++ b/docs/core/compatibility/sdk/6.0/apphost-generated-for-macos.md @@ -5,7 +5,7 @@ ms.date: 07/13/2021 --- # Generate apphost for macOS -When building on macOS, the .NET SDK now [produces an executable](../../../deploying/index.md#produce-an-executable) for app projects. +When building on macOS, the .NET SDK now produces an executable for app projects. Since .NET Core 3.0, the .NET SDK has created an executable for app projects when building on non-macOS operating systems. However, it did not create an executable on macOS since we weren't signing this binary. That resulted in an app that was recognized as dangerous by the OS, which made it hard for the user to run it. The .NET 6 SDK can sign the app executable, so it now produces the executable by default. diff --git a/docs/core/docker/build-container.md b/docs/core/docker/build-container.md index 627cfeba46cff..0817b3adc1633 100644 --- a/docs/core/docker/build-container.md +++ b/docs/core/docker/build-container.md @@ -300,7 +300,7 @@ The `ENTRYPOINT` instruction sets `dotnet` as the host for the `DotNet.Docker.dl ENTRYPOINT ["./DotNet.Docker"] ``` -This causes the app to be executed directly, without `dotnet`, and instead relies on the app host and the underlying OS. For more information on deploying cross-platform binaries, see [Produce a cross-platform binary](../deploying/index.md#produce-an-executable). +This causes the app to be executed directly, without `dotnet`, and instead relies on the app host and the underlying OS. For more information on publishing cross-platform binaries, see [Cross-platform DLL deployment](../deploying/index.md#cross-platform-dll-deployment). To build the container, from your terminal, run the following command: diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index bfd54324fbd55..f2923eeaca16d 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -1623,7 +1623,7 @@ The following MSBuild properties are documented in this section: ### AppHostDotNetSearch -The `AppHostDotNetSearch` property configures how [the native executable](../deploying/index.md#produce-an-executable) produced for an application will search for a .NET installation. This property only impacts the executable produced on publish, not build. +The `AppHostDotNetSearch` property configures how [the native executable](../deploying/index.md#configure-net-install-search-behavior) produced for an application will search for a .NET installation. This property only impacts the executable produced on publish, not build. ```xml From 71cb721ffa787afa5cd94e459de1e8cf4fbf745a Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Tue, 12 Aug 2025 17:37:32 -0700 Subject: [PATCH 25/29] fix redirect --- .openpublishing.redirection.core.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 9454def34d3a5..0d7c6c2bb6c3a 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -387,11 +387,11 @@ "redirect_url": "/dotnet/core/deploying/index" }, { - "source_path_from_root": "docs/core/deploying/deploy-with-cli.md", + "source_path_from_root": "/docs/core/deploying/deploy-with-cli.md", "redirect_url": "/dotnet/core/deploying/index" }, - { - "source_path_from_root": "docs/core/deploying/deploy-with-vs.md", + { + "source_path_from_root": "/docs/core/deploying/deploy-with-vs.md", "redirect_url": "/dotnet/core/deploying/index" }, { From 6d9e32acff272e81a7a9fbad88af84a876f31987 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 13 Aug 2025 12:44:35 -0700 Subject: [PATCH 26/29] Fix links; link to tutorials --- docs/core/deploying/index.md | 12 ++++++++++++ docs/core/tutorials/publishing-with-visual-studio.md | 4 ++-- docs/navigate/devops-testing/toc.yml | 4 ---- docs/navigate/tools-diagnostics/index.yml | 2 +- 4 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 8263e25ee72c4..6b7778a2d7379 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -13,6 +13,18 @@ zone_pivot_groups: development-environment-one This article explains the different ways to publish a .NET application. It covers publishing modes, how to produce executables and cross-platform binaries, and the impact of each approach on deployment and runtime environments. You can publish .NET applications using either the .NET CLI or Visual Studio. +::: zone pivot="vscode" + +For a short tutorial on publishing, see [Tutorial: Publish a .NET console application using Visual Studio Code](../tutorials/publishing-with-visual-studio-code.md). + +::: zone-end + +::: zone pivot="visualstudio" + +For a short tutorial on publishing, see [Tutorial: Publish a .NET console application using Visual Studio](../tutorials/publishing-with-visual-studio.md). + +::: zone-end + ## What is publishing Publishing a .NET app means compiling source code to create an executable or binary, along with its dependencies and related files, for distribution. After publishing, deploy the app to a server, distribution platform, container, or cloud environment. The publishing process prepares an app for deployment and use outside of a development environment. diff --git a/docs/core/tutorials/publishing-with-visual-studio.md b/docs/core/tutorials/publishing-with-visual-studio.md index 06ca93e692d1c..a6cc1cd5c0732 100644 --- a/docs/core/tutorials/publishing-with-visual-studio.md +++ b/docs/core/tutorials/publishing-with-visual-studio.md @@ -54,7 +54,7 @@ In the following steps, you'll look at the files created by the publish process. 1. In **Solution Explorer**, select **Show all files**. -1. In the project folder, expand *bin/Release/net7.0/publish*. +1. In the project folder, expand *bin/Release/{net}/publish*. (Where {net} is the target framework folder, such as _net8.0_.) :::image type="content" source="media/publishing-with-visual-studio/published-files-output-net8.png" alt-text="Solution Explorer showing published files"::: @@ -70,7 +70,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.exe* - This is the [framework-dependent executable](../deploying/publish-with-cli.md#framework-dependent-executable) version of the application. To run it, enter `HelloWorld.exe` at a command prompt. The file is operating-system-specific. + This is the [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) version of the application. To run it, enter `HelloWorld.exe` at a command prompt. The file is operating-system-specific. - *HelloWorld.pdb* (optional for deployment) diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml index ee925f70a5a20..57a6ce1b45d6c 100644 --- a/docs/navigate/devops-testing/toc.yml +++ b/docs/navigate/devops-testing/toc.yml @@ -293,10 +293,6 @@ items: items: - name: Overview href: ../../core/deploying/index.md - - name: Deploy apps with Visual Studio - href: ../../core/deploying/publish-with-vs.md - - name: Publish apps with the CLI - href: ../../core/deploying/publish-with-cli.md - name: Create a NuGet package with the CLI href: ../../core/deploying/creating-nuget-packages.md - name: Self-contained deployment runtime roll forward diff --git a/docs/navigate/tools-diagnostics/index.yml b/docs/navigate/tools-diagnostics/index.yml index d0a7bf9c18896..521fd61399d04 100644 --- a/docs/navigate/tools-diagnostics/index.yml +++ b/docs/navigate/tools-diagnostics/index.yml @@ -67,7 +67,7 @@ landingContent: - linkListType: deploy links: - text: Publish apps - url: ../../core/deploying/publish-with-cli.md + url: ../../core/deploying/index.md # Card - title: Global and local tools From b7b1f140c1c623d8164593781013264195bd125b Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 13 Aug 2025 12:51:43 -0700 Subject: [PATCH 27/29] Fix that link that snuck through! --- docs/core/tutorials/publishing-with-visual-studio.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tutorials/publishing-with-visual-studio.md b/docs/core/tutorials/publishing-with-visual-studio.md index a6cc1cd5c0732..725040ff6fc0a 100644 --- a/docs/core/tutorials/publishing-with-visual-studio.md +++ b/docs/core/tutorials/publishing-with-visual-studio.md @@ -66,7 +66,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.dll* - This is the [framework-dependent deployment](../deploying/publish-with-cli.md#framework-dependent-deployment) version of the application. To execute this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. + This is the [framework-dependent deployment](../deploying/index#cross-platform-dll-deployment) version of the application. To execute this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. - *HelloWorld.exe* From d61f31689e01feeae35a0005556d3d205def1575 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 13 Aug 2025 13:30:52 -0700 Subject: [PATCH 28/29] ugh --- docs/core/tutorials/publishing-with-visual-studio.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tutorials/publishing-with-visual-studio.md b/docs/core/tutorials/publishing-with-visual-studio.md index 725040ff6fc0a..6f23304a0571d 100644 --- a/docs/core/tutorials/publishing-with-visual-studio.md +++ b/docs/core/tutorials/publishing-with-visual-studio.md @@ -66,7 +66,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.dll* - This is the [framework-dependent deployment](../deploying/index#cross-platform-dll-deployment) version of the application. To execute this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. + This is the [framework-dependent deployment](../deploying/index.md#cross-platform-dll-deployment) version of the application. To execute this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. - *HelloWorld.exe* From 6bd3f8bd0327c7326a8456bb0e2267b39d4e4a14 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Thu, 21 Aug 2025 14:17:02 -0700 Subject: [PATCH 29/29] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/deploying/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 6b7778a2d7379..38f8e4620c0d8 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -27,11 +27,11 @@ For a short tutorial on publishing, see [Tutorial: Publish a .NET console applic ## What is publishing -Publishing a .NET app means compiling source code to create an executable or binary, along with its dependencies and related files, for distribution. After publishing, deploy the app to a server, distribution platform, container, or cloud environment. The publishing process prepares an app for deployment and use outside of a development environment. +Publishing a .NET app means compiling source code to create an executable or binary, along with its dependencies and related files, for distribution. After publishing, you deploy the app to a server, distribution platform, container, or cloud environment. The publishing process prepares an app for deployment and use outside of a development environment. ## Publishing modes -There are two primary ways to publish an app. The choice depends on both the deployment environment and the compilation options you want to use. Some factors that influence this decision include whether the deployment environment has the appropriate .NET Runtime installed and whether you need specific compilation features that require bundling the runtime with your app. The two publishing modes are: +There are two primary ways to publish an app. Some factors that influence this decision include whether the deployment environment has the appropriate .NET Runtime installed and whether you need specific compilation features that require bundling the runtime with your app. The two publishing modes are: - **Publish self-contained**\ This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need to have the .NET runtime preinstalled. @@ -46,7 +46,7 @@ This mode produces a publishing folder that includes a platform-specific executa The [``](../project-sdk/msbuild-props.md#targetframework) setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any valid [Target Framework Moniker (TFM)](../../standard/frameworks.md). For example, if your project uses `net9.0`, a binary that targets .NET 9 is created. -If you want to target more than one framework, you can set the [``](../project-sdk/msbuild-props.md#targetframeworks) setting to multiple TFM values, separated by a semicolon. When you build your app, a build is produced for each target framework. However, when you publish your app, you must specify the target framework: +If you want to target more than one framework, you can set the [``](../project-sdk/msbuild-props.md#targetframeworks) setting to multiple TFM values, separated by a semicolon. When you build your app, your app is built for each target framework defined by your project. However, when you publish your app, you must specify the target framework: ::: zone pivot="cli,vscode" @@ -70,7 +70,7 @@ In Visual Studio, create separate publishing profiles for each target framework. When you publish a .NET app, you can target a specific platform or create a portable binary. By default, even when creating a portable binary, .NET publishes a platform-specific executable alongside the portable DLL unless you explicitly disable this behavior. -The platform-specific executable is created because of the `UseAppHost` property, which defaults to `true`. To publish only the portable DLL without the platform-specific executable, set `UseAppHost` to `false` either on the command line (`-p:UseAppHost=false`) or as a project property. +The platform-specific executable is created because of the `UseAppHost` property, which defaults to `true`. To publish only the portable DLL without the platform-specific executable, set `UseAppHost` to `false` either on the command line (`-p:UseAppHost=false`) or as a [project property](../project-sdk/msbuild-props.md#useapphost). The benefit of targeting a specific platform is that it can handle [native dependencies](#native-dependencies) that your app might require, ensuring compatibility with the target platform's specific requirements. @@ -131,7 +131,7 @@ Framework-dependent deployment is the default mode when you publish from either Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on the environment where your app runs. For example, if your app targets .NET 9, any environment that your app runs on must have the .NET 9 runtime installed. -Publishing a framework-dependent deployment creates an app that automatically rolls-forward to the latest .NET security patch available on the environment that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). +Publishing a framework-dependent deployment creates an app that automatically rolls forward to the latest .NET security patch available on the environment that runs the app. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#framework-dependent-apps-roll-forward). **Advantages** @@ -193,7 +193,7 @@ In .NET 9 and later versions, you can configure the .NET installation search pat `AppHostRelativeDotNet` specifies the path relative to the executable that will be searched when `AppHostDotNetSearch` contains `AppRelative`. -For more information, see [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch), [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet) and [install location options in apphost](https://github.com/dotnet/designs/blob/main/proposed/apphost-embed-install-location.md). +For more information, see [`AppHostDotNetSearch`](../project-sdk//msbuild-props.md#apphostdotnetsearch), [`AppHostRelativeDotNet`](../project-sdk//msbuild-props.md#apphostrelativedotnet), and [install location options in apphost](https://github.com/dotnet/designs/blob/main/proposed/apphost-embed-install-location.md). ### Cross-platform DLL deployment @@ -292,7 +292,7 @@ Single-file apps are always OS and architecture specific. You need to publish fo **Disadvantages** - **Larger file size**: The single file includes all dependencies, making it larger than individual files. -- **Slower startup**: Files must be extracted at runtime, which can impact startup performance. +- **Slower startup**: Files must be extracted at run time, which can impact startup performance. - **Platform-specific**: Must publish separate files for each target platform. Single-file deployment can be combined with other optimizations like [trimming](trimming/trim-self-contained.md) and [ReadyToRun compilation](#readytorun-deployment) for further optimization. @@ -336,7 +336,7 @@ Native AOT deployment compiles your app directly to native code, eliminating the **Advantages** -- **Fast startup**: No JIT compilation needed at runtime, leading to faster application startup. +- **Fast startup**: No JIT compilation needed at run time, leading to faster application startup. - **Reduced memory usage**: Lower memory footprint compared to traditional .NET applications. - **No runtime dependency**: The application runs without requiring .NET runtime installation. - **Smaller deployment size**: Often smaller than **self-contained deployment** with the full runtime.