Skip to content

Commit 62c393d

Browse files
elinor-fungelinor-fung
authored
Add doc for embedding install location options in apphost (#318)
There have been numerous requests around being able to customize how/where the .NET root path will be determined for a an application. This document describes a proposed mechanism for basic configuration of how apphost will search for the .NET install location. This is intended to be a step towards a broader (not-yet-designed) SDK experience for building an application or set of applications with a customized .NET runtime path. It does not attempt to tackle the problem of the fuller experience.
1 parent 7e18508 commit 62c393d

File tree

2 files changed

+153
-0
lines changed

2 files changed

+153
-0
lines changed

‎INDEX.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ Use update-index to regenerate it:
9898

9999
|Year|Title|Owners|
100100
|----|-----|------|
101+
| | [Add ability to embed install location options in apphost](proposed/apphost-embed-install-location.md) | |
101102
| | [Provide SDK hint paths in global.json](proposed/local-sdk-global-json.md) | |
102103
| | [Rate limits](proposed/rate-limit.md) | [John Luo](https://github.com/juntaoluo), [Sourabh Shirhatti](https://github.com/shirhatti) |
103104
| | [Readonly references in C# and IL verification.](proposed/verifiable-ref-readonly.md) | |

‎proposed/apphost-embed-install-location.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Add ability to embed install location options in apphost
2+
3+
There have been numerous requests around being able to customize how/where the
4+
.NET root path will be determined for an application. This document describes
5+
a proposed mechanism for basic configuration of how `apphost` will search for
6+
the .NET install location.
7+
8+
Goals:
9+
10+
- Enable developers to build an app and configure it such that it can:
11+
- Only consider global .NET installs
12+
- Always look at a relative path for a .NET install
13+
- Create a building block for a fuller, SDK-supported experience that should fit
14+
in regardless of where we land for the full experience
15+
16+
Non-goals:
17+
18+
- SDK support for layout and deployment of the app with a runtime files in a
19+
corresponding relative path
20+
- SDK and project system experience for building a set of applications using the
21+
same custom runtime install location
22+
23+
Related:
24+
25+
- [dotnet/runtime#2572](https://github.com/dotnet/runtime/issues/2572)
26+
- [dotnet/runtime#3453](https://github.com/dotnet/runtime/issues/3453)
27+
- [dotnet/runtime#53834](https://github.com/dotnet/runtime/issues/53834)
28+
- [dotnet/runtime#64430](https://github.com/dotnet/runtime/issues/64430)
29+
- [dotnet/runtime#70975](https://github.com/dotnet/runtime/issues/70975)
30+
- [dotnet/runtime#86801](https://github.com/dotnet/runtime/issues/86801)
31+
32+
## State in .NET 8
33+
34+
The current state is described in detail in
35+
[install-locations](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md)
36+
and [install-locations-per-architecture](https://github.com/dotnet/designs/blob/main/accepted/2021/install-locations-per-architecture.md)
37+
38+
At a high level, the process and priority for `apphost` determining the install
39+
location is:
40+
41+
1. App-local
42+
- Look for the runtime in the app's folder (self-contained apps)
43+
2. Environment variables
44+
- Read the `DOTNET_ROOT_<arch>` and `DOTNET_ROOT` environment variables
45+
3. Global install (registered)
46+
- Check for a registered install - registry key on Windows or an install
47+
location file on non-Windows
48+
4. Global install (default)
49+
- Fall back to a well-known default install location based on the platform
50+
51+
## Embedded install location options for `apphost`
52+
53+
Every `apphost` already has a placeholder that gets rewritten to contain the app
54+
binary path during build (that is, `dotnet build`). This proposal adds another
55+
placeholder which would represent the optional configuration of search locations
56+
and app-relative path to an install location. Same as existing placeholder, it
57+
would conditionally be rewritten based on the app's settings. This rewrite would
58+
[only be done on `publish`](#writing-options-on-publish) of the app currently.
59+
This is similar to the proposal in [dotnet/runtime#64430](https://github.com/dotnet/runtime/issues/64430),
60+
but with additional configuration of which search locations to use.
61+
62+
### Configuration of search locations
63+
64+
Some applications do not want to use all the default search locations when they
65+
are deployed - for example, [dotnet/runtime#86801](https://github.com/dotnet/runtime/issues/86801).
66+
67+
We can allow selection of which search locations the `apphost` will use. When
68+
search locations are configured, only the specified locations will be searched.
69+
70+
The search location could be specified via a property in the project:
71+
72+
```xml
73+
<AppHostDotNetSearch>Global</AppHostDotNetSearch>
74+
```
75+
76+
where the valid values are `AppLocal`, `AppRelative`, `EnvironmentVariables`, or
77+
`Global`. Multiple values can be specified, delimited by semi-colons.
78+
79+
When a value is specified, only those locations will be used. For example, if
80+
`Global` is specified, `apphost` will only look at global install locations, not
81+
app-local, at any app-relative path, or at environment variables.
82+
83+
### App-relative path to install location
84+
85+
When a relative path is written into an `apphost` which is [configured to look
86+
at it](#configuration-of-search-locations), that path will be used as the .NET
87+
install root when running the application.
88+
89+
The install location could be specified via a property in the project:
90+
91+
```xml
92+
<AppHostRelativeDotNet>./relative/path/to/runtime</AppHostRelativeDotNet>
93+
```
94+
95+
Setting this implies `AppHostDotNetSearch=AppRelative`. This means that only the
96+
relative path will be considered. If a .NET install is not found at the relative
97+
path, other locations - environment variables, global install locations - will
98+
not be considered and the app will fail to run.
99+
100+
`AppHostDotNetSearch` could also be explicitly set to include a fallback - for
101+
example, `AppHostDotNetSearch=AppRelative;Global` would look at the relative
102+
path and, if it is not found, the global locations. If `AppHostDotNetSearch` is
103+
explicitly set to a value that does not include `AppRelative`, then setting
104+
`AppHostRelativeDotNet` is meaningless - the SDK will not write the relative
105+
path into the `apphost` and the `apphost` will not check for a relative path.
106+
107+
## Updated behaviour
108+
109+
At a high level, the updated process and priority for `apphost` determining the
110+
install location would be:
111+
112+
1. App-local, if search location not configured
113+
- Look for the runtime in the app's folder (self-contained apps)
114+
2. App-relative, if specified as a search location
115+
- Use the path written into `apphost`, relative to the app location
116+
3. Environment variables, if search location not configured or if set as a
117+
search location
118+
- Read the `DOTNET_ROOT_<arch>` and `DOTNET_ROOT` environment variables
119+
4. Global install (registered), if search location not configured or if set as
120+
a search location
121+
- Check for a registered install - registry key on Windows or a install
122+
location file on non-Windows
123+
5. Global install (default), if search location not configured or if set as a
124+
search location
125+
- Fall back to a well-known default install location based on the platform
126+
127+
By default - that is, without any configured install location options - the
128+
effective behaviour remains as in the [current state](#state-in-net-8).
129+
130+
## Considerations
131+
132+
### Writing options on publish
133+
134+
This proposal writes the install location options in the `apphost` on `publish`.
135+
Without SDK support for constructing the layout, updating on `build` would cause
136+
the app to stop working in inner dev loop scenarios (running from output folder,
137+
`dotnet run`, F5) unless they create a layout with the runtime in the expected
138+
location relative to the app output as part of their build. This introduces a
139+
difference between `build` and `publish` for `apphost` (currently, it is the
140+
same between `build` and `publish` - with the exception of single-file, which is
141+
only a `publish` scenario), but once SDK support is added it can be reconciled.
142+
143+
### Other hosts
144+
145+
This proposal is only for `apphost`. It is not relevant for `singlefilehost`, as
146+
that has the runtime itself statically linked. Other hosts (`comhost`, `ijwhost`)
147+
are also not included. In theory, other hosts could be given the same treatment,
148+
but we do not have feedback for scenarios using them. They also do not have the
149+
app-local search or the existing requirement of being partially re-written via a
150+
known placeholder. Changing them would add significant complexity without a
151+
compelling scenario. If we see confusion here, we could add an SDK warning if
152+
`AppHostRelativeDotNet` or `AppHostDotNetSearch` is set for those projects.

0 commit comments

Comments
 (0)