Skip to content
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

Update Binding-and-project-context-evaluation.md with details for the CLI host parameters #8587

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions docs/Binding-and-project-context-evaluation.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@ The feature is available for both `dotnet new` and Visual Studio.
## `bind` symbols

The symbol binds value from external sources.

By default, the following sources are available:
- host parameters - parameters defined at certain host. For .NET SDK the following parameters are defined: `HostIdentifier: dotnetcli`, `GlobalJsonExists: true/false`, `WorkingDirectory: <dotnet_new_context_directory>`. Binding syntax is `host:<param name>`, example: `host:HostIdentifier`.
- host parameters - parameters defined by each individual Template Engine host, for example the .NET CLI, Visual Studio, and C# Dev Kit. See [Host parameters](#host-parameters) for more details.
- environment variables - allows to bind environment variables. Binding syntax is `env:<environment variable name>`, example: `env:MYENVVAR`.
- msbuild properties - allows to bind to arbitrary MSBuild Properties. Binding syntax is `msbuild:<property name>`. See [Binding to MSBuild Properties](#binding-to-msbuild-properties) for more details.

It is also possible to bind the parameter without the prefix as a fallback behavior: `HostIdentifier`, `MYENVVAR`.

Expand Down Expand Up @@ -44,6 +46,31 @@ The higher value indicates higher priority.
}
}
```
### Host parameters

As mentioned above, different hosts may expose different bindable properties for you to use:

#### .NET CLI

| Symbol Name | Default value | Meaning |
| - | - | - |
| HostIdentifier | dotnetcli | Uniquely identifies this host |
| WorkingDirectory | System.Environment.CurrentDirectory | The full path that the template engine was invoked from |
| prefs:language | C# | For templates that support multiple programming languages, which one should be chosen if no explicit choice is made |
| dotnet-cli-version | <varies> | The exact SemVer version of the .NET SDK being run for this invocation of the Template Engine - for example 8.0.404 or 9.0.100-rc.2 |
| RuntimeFrameworkVersion | <varies> | The exact SemVer version of the Microsoft.NETCore.App Runtime (aka the .NET Runtime) being used by the .NET SDK for this invocation of the Template Engine - for example 8.0.10 or 9.0.0-rc.2.24473.5 |
| NetStandardImplicitPackageVersion | <varies> | The version of the NetStandard.Library that would be inserted by the .NET SDK - this is deprecated and seems to be mostly wrong, do not use it. |

#### Visual Studio

| Symbol Name | Default value | Meaning |
| - | - | - |
| HostIdentifier | dotnetcli | Uniquely identifies this host |
| WorkingDirectory | System.Environment.CurrentDirectory | The full path that the template engine was invoked from |

#### C# Dev Kit

TODO: add details about the Dev Kit template engine host

### Binding to MSBuild properties

Expand Down Expand Up @@ -79,7 +106,6 @@ Example - binds `DefaultNamespace` symbol to `RootNamespace` of the project:
}
```


## Visual Studio specifics

Visual Studio supports binding to host parameters, environment variables and MSBuild properties.
Expand All @@ -99,4 +125,4 @@ or
```json
"type": "bind"
"binding": "host:namespace"
```
```
Loading