From e7be7003e0336eeb06c46b3859cccf6dbc9410da Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 22 Jul 2026 16:57:30 -0700 Subject: [PATCH 1/7] Clean some things up --- docs/core/deploying/index.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 7165da1e71e00..177ba551d37dc 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -58,6 +58,9 @@ 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). +> [!IMPORTANT] +> When you skip the build step during publish by passing the `--no-build` parameter, publish with the same configuration you used to build. For example, don't build as a framework-dependent app and then publish as a self-contained app. + ::: zone-end ::: zone pivot="visualstudio" @@ -107,11 +110,9 @@ 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. +The following table provides quick examples of how to publish your app with the `dotnet` CLI: | Publish Mode | Command | |--|--| @@ -123,9 +124,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` | | [Container deployment](#container-deployment) | `dotnet publish -c Release [-r ] -t:PublishContainer` | -::: zone-end - -## Framework-dependent deployment +## Publish as framework-dependent Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable is created that can be used to start your app. The platform-specific executable is named something similar to `myapp.exe` on Windows or just `myapp` on other platforms. @@ -247,7 +246,7 @@ dotnet publish -c Release -p:UseAppHost=false ::: zone-end -## Self-contained deployment +## Publish as self-contained 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. @@ -296,7 +295,7 @@ dotnet publish -c Release -r --self-contained true ::: zone-end -## Single-file deployment +## Publish as single-file 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. @@ -349,7 +348,7 @@ dotnet publish -c Release -r -p:PublishSingleFile=true ::: zone-end -## Native AOT deployment +## Publish as native AOT 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. @@ -411,7 +410,7 @@ For more information about Native AOT deployment, see [Native AOT deployment](na ::: zone-end -## ReadyToRun deployment +## Publish as ReadyToRun 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. From 4010b53fd3b6feffb121f689248b9fbf07bb7475 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Wed, 22 Jul 2026 17:23:14 -0700 Subject: [PATCH 2/7] build errors --- docs/core/deploying/index.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 177ba551d37dc..d60a5b7399326 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -59,7 +59,7 @@ 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). > [!IMPORTANT] -> When you skip the build step during publish by passing the `--no-build` parameter, publish with the same configuration you used to build. For example, don't build as a framework-dependent app and then publish as a self-contained app. +> When you skip the build step during publish by passing the `--no-build` parameter, use the same options you used when you built the app, including target framework and build mode. For example, don't build as a framework-dependent app and then publish as a self-contained app. ::: zone-end @@ -116,14 +116,16 @@ The following table provides quick examples of how to publish your app with the | 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` | +| [Framework-dependent deployment](#publish-as-framework-dependent) | `dotnet publish -c Release [-r ]` | +| [Framework-dependent deployment (DLL)](#cross-platform-dll-deployment) | `dotnet publish -c Release -p:UseAppHost=false` | +| [Self-contained deployment](#publish-as-self-contained) | `dotnet publish -c Release [-r ] --self-contained true` | +| [Single-file deployment](#publish-as-single-file) | `dotnet publish -c Release [-r ] -p:PublishSingleFile=true` | +| [Native AOT deployment](#publish-as-native-aot) | `dotnet publish -c Release [-r ] -p:PublishAot=true` | +| [ReadyToRun deployment](#publish-as-readytorun) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | | [Container deployment](#container-deployment) | `dotnet publish -c Release [-r ] -t:PublishContainer` | + + ## Publish as framework-dependent Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable is created that can be used to start your app. The platform-specific executable is named something similar to `myapp.exe` on Windows or just `myapp` on other platforms. @@ -246,6 +248,8 @@ dotnet publish -c Release -p:UseAppHost=false ::: zone-end + + ## Publish as self-contained 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. @@ -295,6 +299,8 @@ dotnet publish -c Release -r --self-contained true ::: zone-end + + ## Publish as single-file 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. @@ -348,6 +354,8 @@ dotnet publish -c Release -r -p:PublishSingleFile=true ::: zone-end + + ## Publish as native AOT 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. @@ -410,6 +418,8 @@ For more information about Native AOT deployment, see [Native AOT deployment](na ::: zone-end + + ## Publish as ReadyToRun 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. From b22a83fd4143ffc0d530ecef29519e7b2b1ccdfd Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Thu, 23 Jul 2026 10:12:38 -0700 Subject: [PATCH 3/7] Update docs/core/deploying/index.md Co-authored-by: Wade Pickett --- 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 d60a5b7399326..2271e0381d301 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -114,7 +114,7 @@ For a list of runtime identifiers, see [Runtime Identifier (RID) catalog](../rid The following table provides quick examples of how to publish your app with the `dotnet` CLI: -| Publish Mode | Command | +| Publish mode | Command | |--|--| | [Framework-dependent deployment](#publish-as-framework-dependent) | `dotnet publish -c Release [-r ]` | | [Framework-dependent deployment (DLL)](#cross-platform-dll-deployment) | `dotnet publish -c Release -p:UseAppHost=false` | From 6da622a48bb626f308ecbc960dc6042074f8202d Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Thu, 23 Jul 2026 12:57:33 -0700 Subject: [PATCH 4/7] Fix links --- docs/ai/quickstarts/build-mcp-server.md | 6 +++--- .../multi-container-applications-docker-compose.md | 2 +- docs/core/compatibility/sdk/8.0/arch-option.md | 2 +- .../sdk/8.0/runtimespecific-app-default.md | 2 +- docs/core/deploying/index.md | 14 ++------------ docs/core/deploying/native-aot/diagnostics.md | 2 +- docs/core/deploying/native-aot/index.md | 6 +++--- docs/core/deploying/ready-to-run.md | 4 ++-- docs/core/deploying/runtime-store.md | 2 +- docs/core/deploying/single-file/overview.md | 2 +- .../core/deploying/trimming/trim-self-contained.md | 2 +- docs/core/install/macos-notarization-issues.md | 2 +- .../native-interop/expose-components-to-com.md | 2 +- docs/core/project-sdk/msbuild-props.md | 4 ++-- .../runtime-discovery/troubleshoot-app-launch.md | 4 ++-- docs/core/tools/dotnet-clean.md | 2 +- docs/core/tools/dotnet-publish.md | 6 +++--- docs/core/tools/sdk-errors/netsdk1071.md | 2 +- docs/core/tools/troubleshoot-usage-issues.md | 2 +- docs/core/tutorials/publish-console-app.md | 6 +++--- docs/core/versions/selection.md | 6 +++--- 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 +- 26 files changed, 44 insertions(+), 54 deletions(-) diff --git a/docs/ai/quickstarts/build-mcp-server.md b/docs/ai/quickstarts/build-mcp-server.md index 75050ec98b448..0874cb526d8e1 100644 --- a/docs/ai/quickstarts/build-mcp-server.md +++ b/docs/ai/quickstarts/build-mcp-server.md @@ -77,7 +77,7 @@ In this quickstart, you create a minimal Model Context Protocol (MCP) server usi - **Framework**: Select the target .NET framework. - **MCP Server Transport Type**: Choose between creating a **local** (stdio) or a **remote** (http) MCP server. - **Enable native AOT (Ahead-Of-Time) publish**: Enable your MCP server to be self-contained and compiled to native code. For more information, see the [Native AOT deployment guide](../../core/deploying/native-aot/index.md). - - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#self-contained-deployment). + - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#publish-as-self-contained). Choose your preferred options or keep the default ones, and then select **Create**. @@ -124,7 +124,7 @@ In this quickstart, you create a minimal Model Context Protocol (MCP) server usi - **Framework**: Select the target .NET framework. - **MCP Server Transport Type**: Choose between creating a **local** (stdio) or a **remote** (http) MCP server. - **Enable native AOT (Ahead-Of-Time) publish**: Enable your MCP server to be self-contained and compiled to native code. For more information, see the [Native AOT deployment guide](../../core/deploying/native-aot/index.md). - - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#self-contained-deployment). + - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#publish-as-self-contained). ![MCP Server Template Options](../media/build-mcp-server/vscode-mcp-server-template-options.png) @@ -151,7 +151,7 @@ In this quickstart, you create a minimal Model Context Protocol (MCP) server usi - **Framework**: Select the target .NET framework. - **MCP Server Transport Type**: Choose between creating a **local** (stdio) or a **remote** (http) MCP server. - **Enable native AOT (Ahead-Of-Time) publish**: Enable your MCP server to be self-contained and compiled to native code. For more information, see the [Native AOT deployment guide](../../core/deploying/native-aot/index.md). - - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#self-contained-deployment). + - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#publish-as-self-contained). ![Template options for an MCP Server in .NET CLI](../media/build-mcp-server/cli-mcp-server-template-options.png) 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 86308780fc78e..c8d62e20839a5 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#self-contained-deployment) +- **runtime-deps**: for production scenarios of [self-contained applications](../../../core/deploying/index.md#publish-as-self-contained) 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 a67d780d6889a..b10a89da056c3 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#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. +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-as-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. ## 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 4723b5916daaa..87d5077e1c563 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#self-contained-deployment) by default. Instead, they are [framework-dependent](../../../deploying/index.md#framework-dependent-deployment) by default. +Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#publish-as-self-contained) by default. Instead, they are [framework-dependent](../../../deploying/index.md##publish-as-framework-dependent) 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 2271e0381d301..663a48a99f825 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -124,8 +124,6 @@ The following table provides quick examples of how to publish your app with the | [ReadyToRun deployment](#publish-as-readytorun) | `dotnet publish -c Release [-r ] -p:PublishReadyToRun=true` | | [Container deployment](#container-deployment) | `dotnet publish -c Release [-r ] -t:PublishContainer` | - - ## Publish as framework-dependent Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable is created that can be used to start your app. The platform-specific executable is named something similar to `myapp.exe` on Windows or just `myapp` on other platforms. @@ -248,13 +246,11 @@ dotnet publish -c Release -p:UseAppHost=false ::: zone-end - - ## Publish as self-contained 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. -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). +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#publish-as-self-containeds-include-the-selected-runtime). **Advantages** @@ -299,8 +295,6 @@ dotnet publish -c Release -r --self-contained true ::: zone-end - - ## Publish as single-file 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. @@ -319,7 +313,7 @@ Single-file apps are always OS and architecture specific. You need to publish fo - **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. +Single-file deployment can be combined with other optimizations like [trimming](trimming/trim-self-contained.md) and [ReadyToRun compilation](#publish-as-native-readytorun) for further optimization. For more information about single-file deployment, see [Single-file deployment](single-file/overview.md). @@ -354,8 +348,6 @@ dotnet publish -c Release -r -p:PublishSingleFile=true ::: zone-end - - ## Publish as native AOT 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. @@ -418,8 +410,6 @@ For more information about Native AOT deployment, see [Native AOT deployment](na ::: zone-end - - ## Publish as ReadyToRun 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. diff --git a/docs/core/deploying/native-aot/diagnostics.md b/docs/core/deploying/native-aot/diagnostics.md index 74f9d6f262e70..b464f30d4aa34 100644 --- a/docs/core/deploying/native-aot/diagnostics.md +++ b/docs/core/deploying/native-aot/diagnostics.md @@ -75,7 +75,7 @@ This mechanism leverages the fact that at the time `RhThrowEx` is called, the CP When publishing, the Native AOT compiler produces both an executable and a symbol file. Native debugging, and related activities like profiling, require access to the native symbol file. If this file isn't present, you might have degraded or broken results. -For information about the name and location of the symbol file, see [Native debug information](index.md#native-aot-deployment). +For information about the name and location of the symbol file, see [Native debug information](index.md#publish-as-native-aot). ## CPU profiling diff --git a/docs/core/deploying/native-aot/index.md b/docs/core/deploying/native-aot/index.md index 51e10306fbdcd..39a5415accc27 100644 --- a/docs/core/deploying/native-aot/index.md +++ b/docs/core/deploying/native-aot/index.md @@ -8,11 +8,11 @@ ai-usage: ai-assisted # Native AOT deployment -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. +Publishing your app as *Native AOT* produces an app that's [self-contained](../index.md#publish-as-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. 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#self-contained-deployment). +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-as-self-contained). ## Prerequisites @@ -173,7 +173,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#self-contained-deployment), increasing their size as compared to framework-dependent apps). +- Apps include required runtime libraries (just like [self-contained apps](../index.md#publish-as-self-contained), increasing their size as compared to framework-dependent apps). - always use their interpreted form, which is slower than runtime generated compiled code. - Generic parameters substituted with struct type arguments 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 9554d7c95988c..ee6e8a57681ec 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#self-contained-deployment) 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#publish-as-self-contained) 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#self-contained-deployment) deployment. +> In .NET 6, Composite ReadyToRun is only supported for [self-contained](index.md#publish-as-self-contained) deployment. ## Cross platform/architecture restrictions diff --git a/docs/core/deploying/runtime-store.md b/docs/core/deploying/runtime-store.md index 45446031017f1..40d2f90fedc38 100644 --- a/docs/core/deploying/runtime-store.md +++ b/docs/core/deploying/runtime-store.md @@ -156,7 +156,7 @@ When deploying a [framework-dependent deployment](index.md#framework-dependent-d ``` > [!NOTE] -> 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. +> For [self-contained deployment](index.md#publish-as-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. ## See also diff --git a/docs/core/deploying/single-file/overview.md b/docs/core/deploying/single-file/overview.md index 341b31c1994fc..43677e3f47816 100644 --- a/docs/core/deploying/single-file/overview.md +++ b/docs/core/deploying/single-file/overview.md @@ -9,7 +9,7 @@ ai-usage: ai-assisted # 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#framework-dependent-deployment) and [self-contained applications](../index.md#self-contained-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#framework-dependent-deployment) and [self-contained applications](../index.md#publish-as-self-contained). 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 7af38701597a7..e23591540df1f 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#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 [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#publish-as-self-contained), 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 cac7a0c19e23c..deb7740d148a3 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#self-contained-deployment) and you cannot disable it. +An **appHost** is required when you publish your app [self-contained](../deploying/index.md#publish-as-self-contained) 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 0d05727041dd9..9b585c49c6dcf 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#self-contained-deployment) of COM components are not supported. Only [framework-dependent deployments](../deploying/index.md#framework-dependent-deployment) of COM components are supported. +[Self-contained deployments](../deploying/index.md#publish-as-self-contained) of COM components are not supported. Only [framework-dependent deployments](../deploying/index.md##publish-as-framework-dependent) 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 2b5e182b1eab4..d2e12722363e9 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -594,7 +594,7 @@ Specify a single [runtime identifier (RID)](../rid-catalog.md) for publish opera ### PublishSelfContained -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. +The `PublishSelfContained` property informs `dotnet publish` to publish an app as a [self-contained app](../deploying/index.md#publish-as-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. 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`. @@ -674,7 +674,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#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. +The `SelfContained` property informs `dotnet build` and `dotnet publish` to build or publish an app as a [self-contained app](../deploying/index.md#publish-as-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. 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/runtime-discovery/troubleshoot-app-launch.md b/docs/core/runtime-discovery/troubleshoot-app-launch.md index 0b27567c2cd11..503782af82f7e 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#framework-dependent-deployment), 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##publish-as-framework-dependent), 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). @@ -279,4 +279,4 @@ By default, an application requires a framework that matches the same major vers - [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#framework-dependent-deployment) +- [Framework-dependent applications](../deploying/index.md##publish-as-framework-dependent) diff --git a/docs/core/tools/dotnet-clean.md b/docs/core/tools/dotnet-clean.md index 9dfdd42a1c940..215b8d1dc46b4 100644 --- a/docs/core/tools/dotnet-clean.md +++ b/docs/core/tools/dotnet-clean.md @@ -60,7 +60,7 @@ The `dotnet clean` command cleans the output of the previous build. It's impleme - **`-r|--runtime `** - Cleans the output folder of the specified runtime. This is used when a [self-contained deployment](../deploying/index.md#self-contained-deployment) was created. + Cleans the output folder of the specified runtime. This is used when a [self-contained deployment](../deploying/index.md#publish-as-self-contained) 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 5b01d3f22d76d..467dad0a402b6 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -227,9 +227,9 @@ For more information, see the following resources: dotnet publish ``` - 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. + Starting with .NET Core 3.0 SDK, this example also creates a [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) for the current platform. -- Create a [self-contained executable](../deploying/index.md#self-contained-deployment) for the project in the current directory, for a specific runtime: +- Create a [self-contained executable](../deploying/index.md#publish-as-self-contained) for the project in the current directory, for a specific runtime: ```dotnetcli dotnet publish --runtime osx-x64 @@ -237,7 +237,7 @@ For more information, see the following resources: The RID must be in the project file. -- Create a [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) for the project in the current directory, for a specific platform: +- Create a [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) 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 2b85dbed857e6..a8929e8edcc67 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#self-contained-deployment) 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#publish-as-self-contained) 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 ba7fcd5fc23bb..1e3cbc4fde40a 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#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: +.NET tools are [framework-dependent applications](../deploying/index.md##publish-as-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: - 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/tutorials/publish-console-app.md b/docs/core/tutorials/publish-console-app.md index 10aabcce536d8..6d58ffbb08b2f 100644 --- a/docs/core/tutorials/publish-console-app.md +++ b/docs/core/tutorials/publish-console-app.md @@ -139,7 +139,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/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. + This is the [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) 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) @@ -175,7 +175,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.exe* (*HelloWorld* on Linux or macOS.) - This is the [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) version of the application. The file is operating-system-specific. + This is the [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) version of the application. The file is operating-system-specific. - *HelloWorld.pdb* (optional for deployment) @@ -203,7 +203,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld* - This is the [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) version of the application. The file is operating-system-specific. Codespaces runs on Linux, so this a Linux executable. + This is the [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) version of the application. The file is operating-system-specific. Codespaces runs on Linux, so this a Linux executable. - *HelloWorld.deps.json* diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 83bfb86d17e18..f481880630194 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -22,7 +22,7 @@ Version selection occurs: - When you run an SDK command, [the SDK uses the latest installed version](#the-sdk-uses-the-latest-installed-version). - When you build an assembly, [target framework monikers define build time APIs](#target-framework-monikers-define-build-time-apis). - When you run a .NET application, [target framework dependent apps roll-forward](#framework-dependent-apps-roll-forward). -- When you publish a self-contained application, [self-contained deployments include the selected runtime](#self-contained-deployments-include-the-selected-runtime). +- When you publish a self-contained application, [self-contained deployments include the selected runtime](#publish-as-self-containeds-include-the-selected-runtime). The rest of this document examines those four scenarios. @@ -87,7 +87,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#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. +When you run an application from source with [`dotnet run`](../tools/dotnet-run.md), from a [**framework-dependent deployment**](../deploying/index.md##publish-as-framework-dependent) with [`dotnet myapp.dll`](../tools/dotnet.md#description), or from a [**framework-dependent executable**](../deploying/index.md##publish-as-framework-dependent) 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. @@ -179,7 +179,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#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 runtime. +You can publish an application as a [**self-contained distribution**](../deploying/index.md#publish-as-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 runtime. The *restore* event that occurs when publishing selects the latest patch version of the given runtime family. For example, `dotnet publish` selects .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 bd40eea36193e..b2934e77689c8 100644 --- a/docs/core/whats-new/dotnet-core-2-2.md +++ b/docs/core/whats-new/dotnet-core-2-2.md @@ -13,7 +13,7 @@ ms.update-cycle: 3650-days ## New deployment mode -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. +Starting with .NET Core 2.2, you can deploy [framework-dependent executables](../deploying/index.md##publish-as-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. 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 f3651754f5479..02211421214fb 100644 --- a/docs/core/whats-new/dotnet-core-3-0.md +++ b/docs/core/whats-new/dotnet-core-3-0.md @@ -57,7 +57,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#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. +.NET Core now builds [framework-dependent executables](../deploying/index.md##publish-as-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-as-self-contained) 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: @@ -72,7 +72,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#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). +Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md##publish-as-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-as-self-contained). You can either configure the appHost at the project level, or toggle the appHost for a specific `dotnet` command with the `-p:UseAppHost` parameter: @@ -329,7 +329,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#self-contained-deployment) .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#publish-as-self-contained) .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 50c8e79728054..d5d42ee191f3a 100644 --- a/docs/core/whats-new/dotnet-core-3-1.md +++ b/docs/core/whats-new/dotnet-core-3-1.md @@ -40,7 +40,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#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). +Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md##publish-as-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-as-self-contained). 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 7a96c5ed33ffc..0a129b3d12ea5 100644 --- a/docs/standard/glossary.md +++ b/docs/standard/glossary.md @@ -115,7 +115,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#framework-dependent-deployment) +- [framework-dependent app](../core/deploying/index.md##publish-as-framework-dependent) Sometimes "framework" refers to an [implementation of .NET](#implementation-of-net). @@ -289,7 +289,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#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). + 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-as-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). - *.NET runtime libraries* @@ -310,7 +310,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#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 [framework-dependent apps](../core/deploying/index.md##publish-as-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-as-self-contained), 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 5c9a054df1dd4..0acb726028385 100644 --- a/docs/standard/runtime-libraries-overview.md +++ b/docs/standard/runtime-libraries-overview.md @@ -44,4 +44,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#framework-dependent-deployment) +* [Publish framework-dependent apps](../core/deploying/index.md##publish-as-framework-dependent) From 03575cc26bea807a5d59a6be151ecc0c1fa5dd48 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Thu, 23 Jul 2026 14:21:50 -0700 Subject: [PATCH 5/7] Fix links --- .../compatibility/sdk/8.0/runtimespecific-app-default.md | 2 +- docs/core/deploying/index.md | 4 ++-- docs/core/deploying/runtime-store.md | 4 ++-- docs/core/deploying/single-file/overview.md | 2 +- docs/core/deploying/trimming/trim-self-contained.md | 2 +- docs/core/native-interop/expose-components-to-com.md | 2 +- docs/core/runtime-discovery/troubleshoot-app-launch.md | 4 ++-- docs/core/tools/dotnet-publish.md | 4 ++-- docs/core/tools/troubleshoot-usage-issues.md | 2 +- docs/core/tutorials/publish-console-app.md | 6 +++--- 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 | 4 ++-- docs/core/whats-new/dotnet-core-3-1.md | 2 +- docs/standard/glossary.md | 6 +++--- docs/standard/runtime-libraries-overview.md | 2 +- 16 files changed, 26 insertions(+), 26 deletions(-) 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 87d5077e1c563..858b57931886f 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-as-self-contained) by default. Instead, they are [framework-dependent](../../../deploying/index.md##publish-as-framework-dependent) by default. +Runtime-specific apps, or .NET apps with a `RuntimeIdentifier`, are no longer [self-contained](../../../deploying/index.md#publish-as-self-contained) by default. Instead, they are [framework-dependent](../../../deploying/index.md#publish-as-framework-dependent) 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 663a48a99f825..fb45612ce35cb 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -250,7 +250,7 @@ dotnet publish -c Release -p:UseAppHost=false 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. -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#publish-as-self-containeds-include-the-selected-runtime). +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#publish-as-self-containede). **Advantages** @@ -313,7 +313,7 @@ Single-file apps are always OS and architecture specific. You need to publish fo - **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](#publish-as-native-readytorun) for further optimization. +Single-file deployment can be combined with other optimizations like [trimming](trimming/trim-self-contained.md) and [ReadyToRun compilation](#publish-as-native-aot) for further optimization. For more information about single-file deployment, see [Single-file deployment](single-file/overview.md). diff --git a/docs/core/deploying/runtime-store.md b/docs/core/deploying/runtime-store.md index 40d2f90fedc38..e3a58aa6d43d1 100644 --- a/docs/core/deploying/runtime-store.md +++ b/docs/core/deploying/runtime-store.md @@ -143,11 +143,11 @@ Specify the target manifests in the project file only when the target environmen The ASP.NET Core implicit store applied 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#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. +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-as-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. 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#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: +When deploying a [framework-dependent deployment](index.md#publish-as-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: ```xml diff --git a/docs/core/deploying/single-file/overview.md b/docs/core/deploying/single-file/overview.md index 43677e3f47816..f57ec1baad00a 100644 --- a/docs/core/deploying/single-file/overview.md +++ b/docs/core/deploying/single-file/overview.md @@ -9,7 +9,7 @@ ai-usage: ai-assisted # 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#framework-dependent-deployment) and [self-contained applications](../index.md#publish-as-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#publish-as-framework-dependent) and [self-contained applications](../index.md#publish-as-self-contained). 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 e23591540df1f..a3069a0c13297 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#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#publish-as-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#publish-as-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-as-self-contained), 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/native-interop/expose-components-to-com.md b/docs/core/native-interop/expose-components-to-com.md index 9b585c49c6dcf..7d9e0d2cb75e8 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-as-self-contained) of COM components are not supported. Only [framework-dependent deployments](../deploying/index.md##publish-as-framework-dependent) of COM components are supported. +[Self-contained deployments](../deploying/index.md#publish-as-self-contained) of COM components are not supported. Only [framework-dependent deployments](../deploying/index.md#publish-as-framework-dependent) 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/runtime-discovery/troubleshoot-app-launch.md b/docs/core/runtime-discovery/troubleshoot-app-launch.md index 503782af82f7e..fd81d9a2f30a5 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-as-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#publish-as-framework-dependent), 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). @@ -279,4 +279,4 @@ By default, an application requires a framework that matches the same major vers - [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-as-framework-dependent) +- [Framework-dependent applications](../deploying/index.md#publish-as-framework-dependent) diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 467dad0a402b6..2a1770e909bf0 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -227,7 +227,7 @@ For more information, see the following resources: dotnet publish ``` - Starting with .NET Core 3.0 SDK, this example also creates a [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) for the current platform. + Starting with .NET Core 3.0 SDK, this example also creates a [framework-dependent executable](../deploying/index.md#publish-as-framework-dependent) for the current platform. - Create a [self-contained executable](../deploying/index.md#publish-as-self-contained) for the project in the current directory, for a specific runtime: @@ -237,7 +237,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-as-framework-dependent) for the project in the current directory, for a specific platform: +- Create a [framework-dependent executable](../deploying/index.md#publish-as-framework-dependent) 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/troubleshoot-usage-issues.md b/docs/core/tools/troubleshoot-usage-issues.md index 1e3cbc4fde40a..026ef405501c5 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-as-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#publish-as-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: - 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/tutorials/publish-console-app.md b/docs/core/tutorials/publish-console-app.md index 6d58ffbb08b2f..dd2b95b68e097 100644 --- a/docs/core/tutorials/publish-console-app.md +++ b/docs/core/tutorials/publish-console-app.md @@ -139,7 +139,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/index.md##publish-as-framework-dependent) 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#publish-as-framework-dependent) 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) @@ -175,7 +175,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.exe* (*HelloWorld* on Linux or macOS.) - This is the [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) version of the application. The file is operating-system-specific. + This is the [framework-dependent executable](../deploying/index.md#publish-as-framework-dependent) version of the application. The file is operating-system-specific. - *HelloWorld.pdb* (optional for deployment) @@ -203,7 +203,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld* - This is the [framework-dependent executable](../deploying/index.md##publish-as-framework-dependent) version of the application. The file is operating-system-specific. Codespaces runs on Linux, so this a Linux executable. + This is the [framework-dependent executable](../deploying/index.md#publish-as-framework-dependent) version of the application. The file is operating-system-specific. Codespaces runs on Linux, so this a Linux executable. - *HelloWorld.deps.json* diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index f481880630194..3150c19e90605 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -22,7 +22,7 @@ Version selection occurs: - When you run an SDK command, [the SDK uses the latest installed version](#the-sdk-uses-the-latest-installed-version). - When you build an assembly, [target framework monikers define build time APIs](#target-framework-monikers-define-build-time-apis). - When you run a .NET application, [target framework dependent apps roll-forward](#framework-dependent-apps-roll-forward). -- When you publish a self-contained application, [self-contained deployments include the selected runtime](#publish-as-self-containeds-include-the-selected-runtime). +- When you publish a self-contained application, [self-contained deployments include the selected runtime](#publish-as-self-containede). The rest of this document examines those four scenarios. @@ -87,7 +87,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-as-framework-dependent) with [`dotnet myapp.dll`](../tools/dotnet.md#description), or from a [**framework-dependent executable**](../deploying/index.md##publish-as-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#publish-as-framework-dependent) with [`dotnet myapp.dll`](../tools/dotnet.md#description), or from a [**framework-dependent executable**](../deploying/index.md#publish-as-framework-dependent) 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. diff --git a/docs/core/whats-new/dotnet-core-2-2.md b/docs/core/whats-new/dotnet-core-2-2.md index b2934e77689c8..314962f31e2f8 100644 --- a/docs/core/whats-new/dotnet-core-2-2.md +++ b/docs/core/whats-new/dotnet-core-2-2.md @@ -13,7 +13,7 @@ ms.update-cycle: 3650-days ## New deployment mode -Starting with .NET Core 2.2, you can deploy [framework-dependent executables](../deploying/index.md##publish-as-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#publish-as-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. 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 02211421214fb..8e0e414d0fa21 100644 --- a/docs/core/whats-new/dotnet-core-3-0.md +++ b/docs/core/whats-new/dotnet-core-3-0.md @@ -57,7 +57,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-as-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-as-self-contained) would produce an executable. +.NET Core now builds [framework-dependent executables](../deploying/index.md#publish-as-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-as-self-contained) 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: @@ -72,7 +72,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-as-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-as-self-contained). +Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md#publish-as-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-as-self-contained). 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/core/whats-new/dotnet-core-3-1.md b/docs/core/whats-new/dotnet-core-3-1.md index d5d42ee191f3a..9d5f88de28aa1 100644 --- a/docs/core/whats-new/dotnet-core-3-1.md +++ b/docs/core/whats-new/dotnet-core-3-1.md @@ -40,7 +40,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-as-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-as-self-contained). +Without the appHost, the only way a user can start a [framework-dependent](../deploying/index.md#publish-as-framework-dependent) app is with the `dotnet ` command. An appHost is always created when you publish your app [self-contained](../deploying/index.md#publish-as-self-contained). 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 0a129b3d12ea5..c1e15fe1334f3 100644 --- a/docs/standard/glossary.md +++ b/docs/standard/glossary.md @@ -115,7 +115,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-as-framework-dependent) +- [framework-dependent app](../core/deploying/index.md#publish-as-framework-dependent) Sometimes "framework" refers to an [implementation of .NET](#implementation-of-net). @@ -289,7 +289,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-as-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#publish-as-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). - *.NET runtime libraries* @@ -310,7 +310,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-as-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-as-self-contained), the shared framework assemblies are included with the app. +For [framework-dependent apps](../core/deploying/index.md#publish-as-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-as-self-contained), 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 0acb726028385..e7f75b8ef609f 100644 --- a/docs/standard/runtime-libraries-overview.md +++ b/docs/standard/runtime-libraries-overview.md @@ -44,4 +44,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-as-framework-dependent) +* [Publish framework-dependent apps](../core/deploying/index.md#publish-as-framework-dependent) From c9da325cccc09abacfc34cc68a5f7a34de073417 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Thu, 23 Jul 2026 15:08:58 -0700 Subject: [PATCH 6/7] Fix links --- docs/core/deploying/index.md | 2 +- docs/core/deploying/native-aot/diagnostics.md | 2 +- docs/core/versions/selection.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index fb45612ce35cb..15d8dcb16715f 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -250,7 +250,7 @@ dotnet publish -c Release -p:UseAppHost=false 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. -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#publish-as-self-containede). +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#publish-as-self-contained). **Advantages** diff --git a/docs/core/deploying/native-aot/diagnostics.md b/docs/core/deploying/native-aot/diagnostics.md index b464f30d4aa34..74f9d6f262e70 100644 --- a/docs/core/deploying/native-aot/diagnostics.md +++ b/docs/core/deploying/native-aot/diagnostics.md @@ -75,7 +75,7 @@ This mechanism leverages the fact that at the time `RhThrowEx` is called, the CP When publishing, the Native AOT compiler produces both an executable and a symbol file. Native debugging, and related activities like profiling, require access to the native symbol file. If this file isn't present, you might have degraded or broken results. -For information about the name and location of the symbol file, see [Native debug information](index.md#publish-as-native-aot). +For information about the name and location of the symbol file, see [Native debug information](index.md#native-aot-deployment). ## CPU profiling diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 3150c19e90605..c516eb6e91aee 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -22,7 +22,7 @@ Version selection occurs: - When you run an SDK command, [the SDK uses the latest installed version](#the-sdk-uses-the-latest-installed-version). - When you build an assembly, [target framework monikers define build time APIs](#target-framework-monikers-define-build-time-apis). - When you run a .NET application, [target framework dependent apps roll-forward](#framework-dependent-apps-roll-forward). -- When you publish a self-contained application, [self-contained deployments include the selected runtime](#publish-as-self-containede). +- When you publish a self-contained application, [self-contained deployments include the selected runtime](#publish-as-self-contained). The rest of this document examines those four scenarios. From fa2a92fb775fa63c6cf4e216faa215d6b00a4740 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Thu, 23 Jul 2026 15:25:08 -0700 Subject: [PATCH 7/7] So annoying... --- docs/core/deploying/index.md | 2 +- docs/core/versions/selection.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index 15d8dcb16715f..5dc47165a7ee9 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -250,7 +250,7 @@ dotnet publish -c Release -p:UseAppHost=false 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. -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#publish-as-self-contained). +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#framework-dependent-apps-roll-forward). **Advantages** diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index c516eb6e91aee..0aee66729549b 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -22,7 +22,7 @@ Version selection occurs: - When you run an SDK command, [the SDK uses the latest installed version](#the-sdk-uses-the-latest-installed-version). - When you build an assembly, [target framework monikers define build time APIs](#target-framework-monikers-define-build-time-apis). - When you run a .NET application, [target framework dependent apps roll-forward](#framework-dependent-apps-roll-forward). -- When you publish a self-contained application, [self-contained deployments include the selected runtime](#publish-as-self-contained). +- When you publish a self-contained application, [self-contained deployments include the selected runtime](#self-contained-deployments-include-the-selected-runtime). The rest of this document examines those four scenarios.