This article explains the different ways to publish a .NET application. It covers publishing modes, how to produce executables and cross-platform binaries, and the impact of each approach on deployment and runtime environments. You can publish .NET applications using either the .NET CLI or Visual Studio.

What is publishing

Publishing a .NET app means compiling source code to create an executable or binary, along with its dependencies and related files, for distribution. After publishing, you deploy the app to a server, distribution platform, container, or cloud environment. The publishing process prepares an app for deployment and use outside of a development environment.

Publishing modes

There are two primary ways to publish an app. Some factors that influence this decision include whether the deployment environment has the appropriate .NET Runtime installed and whether you need specific compilation features that require bundling the runtime with your app. The two publishing modes are:

• Publish self-contained
  This mode produces a publishing folder that includes a platform-specific executable used to start the app, a compiled binary containing app code, any app dependencies, and the .NET runtime required to run the app. The environment that runs the app doesn't need to have the .NET runtime preinstalled.

• Publish framework-dependent
  This mode produces a publishing folder that includes an optional platform-specific executable used to start the app, a compiled binary containing app code, and any app dependencies. The environment that runs the app must have a version of the .NET runtime installed that the app can use.

Publishing basics

The<TargetFramework> setting of the project file specifies the default target framework when you publish your app. You can change the target framework to any validTarget Framework Moniker (TFM). For example, if your project uses<TargetFramework>net9.0</TargetFramework>, a binary that targets .NET 9 is created.

If you want to target more than one framework, you can set the<TargetFrameworks> setting to multiple TFM values, separated by a semicolon. When you build your app, your app is built for each target framework defined by your project. However, when you publish your app, you must specify the target framework:

dotnet publish -c Release -f net9.0

Portable binaries

When you publish a .NET app, you can target a specific platform or create a portable binary. By default, even when creating a portable binary, .NET publishes a platform-specific executable ("apphost") alongside the portable DLL unless you explicitly disable this behavior.

The platform-specific executable is created because of theUseAppHost property, which defaults totrue. To publish only the portable DLL without the platform-specific executable, setUseAppHost tofalse either on the command line (-p:UseAppHost=false) or as aproject property.

The benefit of targeting a specific platform is that it can handlenative dependencies that your app might require, ensuring compatibility with the target platform's specific requirements.

Native dependencies

If your app has native dependencies, it might not run on a different operating system if published as a portable binary. For example, apps that depend on the Windows API don't natively run on macOS or Linux. You would need to provide platform-specific code and compile an executable for each platform.

Consider also, if a library you referenced provides platform-specific dependencies, your app might not run on every platform. However, when you publish and target a specific platform, the platform-specific dependencies of a NuGet package are copied to the publish folder.

To ensure that your app is published with its native dependencies, publish for a specific platform:

dotnet publish -c Release -r <RID>

For a list of runtime identifiers, seeRuntime Identifier (RID) catalog.

Framework-dependent deployment

Framework-dependent deployment is the default mode when you publish from either the CLI or Visual Studio. In this mode, a platform-specific executable is created that can be used to start your app. The platform-specific executable is named something similar tomyapp.exe on Windows or justmyapp on other platforms.

Your app is configured to target a specific version of .NET. That targeted .NET runtime is required to be on the environment where your app runs. For example, if your app targets .NET 9, any environment that your app runs on must have the .NET 9 runtime installed.

Publishing a framework-dependent deployment creates an app that automatically rolls forward to the latest .NET security patch available on the environment that runs the app. For more information on version binding at compile time, seeSelect the .NET version to use.

Advantages

• Small deployment: Only the app and its dependencies are distributed. The environment where the app is run must already have the .NET runtime installed.
• Cross-platform: The app and any .NET-based library runs on other operating systems.
• Uses the latest patched runtime: The app uses the latest runtime installed in the environment.

Disadvantages

• Requires pre-installing the runtime: The app can run only if the version of .NET it targets is already installed in the environment.
• .NET might change: The environment where the app is run might use a newer .NET runtime, which could change app behavior.

Launch framework-dependent apps

There are two ways to run framework-dependent apps: through the platform-specific executable ("apphost") and viadotnet myapp.dll. You can run the apphost executable directly instead of callingdotnet myapp.dll, which is still an acceptable way to run the app. Whenever possible, it's recommended to use the apphost. There are a number of advantages to using the apphost:

• Executables appear like standard native platform executables.
• Executable names are preserved in the process names, meaning apps can be easily recognized based on their names.
• Because the apphost is a native binary, native assets like manifests can be attached to them.
• Apphost has available low-level security mitigations applied by default that makes it more secure. For example, Control-flow Enforcement Technology (CET) shadow stack is enabled by default starting with .NET 9. Mitigations applied todotnet are the lowest common denominator of all supported runtimes.

Publish

dotnet publish -c Release [-r <RID>]

dotnet publish -c Release [-r <RID>] --self-contained false

Configure .NET install search behavior

By default, the apphost discovers and uses a globally installed .NET runtime, with install locations varying by platform. For more information about runtime discovery and install locations, seeTroubleshoot app launch failures.

The .NET runtime path can also be customized on a per-execution basis. TheDOTNET_ROOT environment variable can be used to point to the custom location. For more information about allDOTNET_ROOT configuration options, see.NET environment variables.

In general, the best practice for usingDOTNET_ROOT is to:

1. ClearDOTNET_ROOT environment variables first, meaning all environment variables that start with the textDOTNET_ROOT.
2. SetDOTNET_ROOT, and onlyDOTNET_ROOT, to the target path.
3. Execute the target apphost.

In .NET 9 and later versions, you can configure the .NET installation search paths of the published executable via theAppHostDotNetSearch andAppHostRelativeDotNet properties.

AppHostDotNetSearch allows specifying one or more locations where the executable will look for a .NET installation:

• AppLocal: app executable's folder
• AppRelative: path relative to the app executable
• EnvironmentVariable: value ofDOTNET_ROOT[_<arch>] environment variables
• Global:registered anddefault global install locations

AppHostRelativeDotNet specifies the path relative to the executable that will be searched whenAppHostDotNetSearch containsAppRelative.

For more information, seeAppHostDotNetSearch,AppHostRelativeDotNet, andinstall location options in apphost.

Cross-platform DLL deployment

Alternatively, you can publish your app as a cross-platform DLL without a platform-specific executable. In this mode, amyapp.dll file is created in the publish output folder. To run your app, navigate to the output folder and use thedotnet myapp.dll command.

To publish as a cross-platform DLL:

dotnet publish -c Release -p:UseAppHost=false

Self-contained deployment

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, seeSelect the .NET version to use.

Advantages

• Control .NET version: Control which version of .NET is deployed with the app.
• Platform-specific targeting: Because the app must be published for each platform, it's clear where the app runs.

Disadvantages

• Larger deployments: Because the app includes the .NET runtime and all dependencies, the download size and hard drive space required is greater than aframework-dependent deployment.
• Harder to update the .NET version: The .NET Runtime can only be upgraded by releasing a new version of the app.

Publish

dotnet publish -c Release -r <RID> --self-contained true

Single-file deployment

When you publish your app as a single-file deployment, all application-dependent files are bundled into a single binary. This deployment model is available for both framework-dependent and self-contained applications, providing an attractive option to deploy and distribute your application as a single file.

Single-file apps are always OS and architecture specific. You need to publish for each configuration, such as Linux x64, Linux Arm64, Windows x64, and so forth.

Advantages

• Simplified distribution: Deploy and distribute your application as a single executable file.
• Reduced file clutter: All dependencies are bundled, eliminating the need to manage multiple files.
• Easy deployment: Copy a single file to deploy the application.

Disadvantages

• Larger file size: The single file includes all dependencies, making it larger than individual files.
• Slower startup: Files must be extracted at run time, which can impact startup performance.
• Platform-specific: Must publish separate files for each target platform.

Single-file deployment can be combined with other optimizations liketrimming andReadyToRun compilation for further optimization.

For more information about single-file deployment, seeSingle-file deployment.

Publish

dotnet publish -c Release -r <RID> -p:PublishSingleFile=true

Native AOT deployment

Native AOT deployment compiles your app directly to native code, eliminating the need for a runtime. This publishing option usesself-contained deployment mode, as the compiled native code must include everything needed to run the application. This results in faster startup times and reduced memory usage, but comes with some limitations on supported features.

Advantages

• Fast startup: No JIT compilation needed at run time, leading to faster application startup.
• Reduced memory usage: Lower memory footprint compared to traditional .NET applications.
• No runtime dependency: The application runs without requiring .NET runtime installation.
• Smaller deployment size: Often smaller thanself-contained deployment with the full runtime.

Disadvantages

• Limited framework support: Not all .NET features and libraries are compatible with Native AOT.
• Longer build times: Compilation to native code takes longer than regular builds.
• Platform-specific: Must compile separately for each target platform and architecture.
• Debugging limitations: More complex debugging experience compared to regular .NET applications.

For more information about Native AOT deployment, seeNative AOT deployment.

Publish

dotnet publish -c Release -r <RID> -p:PublishAot=true

ReadyToRun deployment

When you publish your app with ReadyToRun compilation, your application assemblies are compiled as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation that improves startup performance by reducing the amount of work the just-in-time (JIT) compiler needs to do as your application loads. This publishing option can be used with bothframework-dependent andself-contained deployment modes.

ReadyToRun binaries contain both intermediate language (IL) code and the native version of the same code. While R2R binaries are larger than regular assemblies, they provide better startup performance.

Advantages

• Improved startup time: The app spends less time running the JIT compiler during startup.
• Better first-use performance: Reduced latency for first-time execution of code paths.
• Compatible with existing code: Works with most .NET libraries and frameworks without modification.
• Flexible deployment: Can be combined with bothframework-dependent deployment andself-contained deployment modes.

Disadvantages

• Larger size: The app is larger on disk due to including both IL and native code.
• Longer build times: Compilation takes more time than standard publishing.
• Platform-specific optimizations: Best performance gains require targeting specific platforms.

Publish

dotnet publish -c Release -r <RID> -p:PublishReadyToRun=true

For more information about ReadyToRun deployment, seeReadyToRun compilation.

Container deployment

When you publish your app as a container, the .NET SDK packages your application and its dependencies into a container image without requiring a separate Dockerfile. This deployment mode creates a complete container image that can be run on any container runtime, such as Docker or Podman. Container deployment simplifies the containerization process by eliminating the need to write and maintain Dockerfiles while providing optimized base images.

Starting with .NET SDK 8.0.200, container support is included by default and doesn't require extra NuGet packages. For console applications, you might need to enable container support explicitly by setting theEnableSdkContainerSupport property totrue.

Advantages

• Simplified containerization: No need to write or maintain Dockerfiles for basic scenarios.
• Optimized base images: Uses Microsoft-provided, optimized base images with the latest security updates.
• Consistent environment: Ensures consistent runtime environment across development, testing, and production.
• Easy distribution: Container images can be easily shared and deployed across different environments.
• Platform isolation: Applications run in isolated containers, reducing conflicts between applications.

Disadvantages

• Container runtime dependency: The target environment must have a container runtime installed.
• Image size: Container images are typically larger than other deployment methods.
• Learning curve: Requires understanding of container concepts and tooling.
• Limited customization: Less flexibility compared to custom Dockerfiles for complex scenarios.

Publish

dotnet publish -c Release [-r <RID>] /t:PublishContainer

dotnet publish -c Release [-r <RID>] -p:PublishProfile=DefaultContainer

For more information about container deployment, see.NET SDK container creation overview.

See also

• .NET Runtime Identifier (RID) catalog
• Select the .NET version to use
• Publishing for macOS