- 
                Notifications
    You must be signed in to change notification settings 
- Fork 165
Add guidance for running .NET apps #346
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
c7a16cf
              f86f917
              2eefd83
              1259ca7
              4ff6e0d
              d05890b
              8ac41c9
              File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | 
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
|  | ||
| # Launching .NET Apps | ||
|  | ||
| This document covers recommendations for launching .NET applications. There are two main form factors for .NET app deployment: | ||
|  | ||
| * Self-contained | ||
| * Framework-dependent | ||
|  | ||
| Self-contained apps are the simplest. They have a platform-native entry executable and contain all files needed for their execution. They match the native platform standard for launching executables. They do not support configuration beyond the native platform convention. | ||
|  | ||
| Framework-dependent apps do not contain a runtime themselves and instead need a separate runtime located somewhere on the machine. This is the most complicated scenario with the most configuration options. | ||
|  | ||
| ## Framework-dependent apps | ||
|  | ||
| There are two ways to run framework-dependent apps: through the "apphost" launcher and via `dotnet app.dll`. 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. | ||
|         
                  agocke marked this conversation as resolved.
              Show resolved
            Hide resolved | ||
| * Apphost has available [low-level security mitigations](accepted/2021/runtime-security-mitigations.md) applied by default that makes it more secure. Mitigations applied to `dotnet` are the lowest common denominator of all supported runtimes. | ||
|  | ||
| The apphost will generally use a global install of the .NET runtime, where install locations are defined by [install locations](accepted/2021/install-location-per-architecture.md). | ||
|  | ||
| The .NET runtime path can also be customized on a per-execution basis. The DOTNET_ROOT environment variable can be used to point to the custom location. Details for all DOTNET_ROOT configuration can also be found in [install locations](accepted/2021/install-location-per-architecture.md). | ||
|  | ||
| In general, the best practice for using `DOTNET_ROOT` to set the runtime location for an app is to: | ||
|  | ||
| 1. Clear DOTNET_ROOT environment variables first, meaning all environment variables that start with the text `DOTNET_ROOT`. | ||
| There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'd link to https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-environment-variables#dotnet_root-dotnet_rootx86-dotnet_root_x86-dotnet_root_x64 since I don't think it's widely known that there are multiple variations of  There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agree. That adds context to why this needs to be done. | ||
| 2. Set `DOTNET_ROOT`, and only `DOTNET_ROOT`, to the target path. | ||
| There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Might be worth mentioning that if you are a tool launched by  There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Note: that DOTNET_HOST_PATH doc is also being updated: dotnet/docs#49422 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No:  There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, I know that's SDK only property, I was just thinking it's a common scenario and might be good mentioning it here. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It’s not a common scenario though: it’s only for Microsoft apps that ship in the sdk, or maybe for tools that people launch with MSBuild. One of those is internal-only and the other is only relevant for people who don’t have .NET globally installed. | ||
| 3. Execute the target apphost. | ||
Uh oh!
There was an error while loading. Please reload this page.