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.

Sign up for GitHub

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

Document shared environments in environment files #34406

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Document shared environments in environment files #34406

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0292a1b
Document sharred environments in environment files
tdykstra Dec 20, 2024
7ad76dd
Update aspnetcore/test/http-files.md
tdykstra Dec 20, 2024
9169d91
get rid of curly apostrophes
tdykstra Dec 25, 2024
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
30 changes: 27 additions & 3 deletions aspnetcore/test/http-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This article contains documentation for:
* [The `.http` file syntax](#http-file-syntax).
* [How to create an `.http` file](#create-an-http-file).
* [How to send a request from an `.http` file](#send-an-http-request).
* [Where to find `.http` file options that can be configured.](#http-file-options).
* [Where to find `.http` file options that can be configured](#http-file-options).
* [How to create requests in `.http` files by using the Visual Studio 2022 **Endpoints Explorer**](#use-endpoints-explorer).

The `.http` file format and editor was inspired by the Visual Studio Code [REST Client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client). The Visual Studio 2022 `.http` editor recognizes `.rest` as an alternative file extension for the same file format.
Expand Down Expand Up @@ -166,9 +166,33 @@ Visual Studio displays warnings in the following situations:

A variable defined in an environment file can be the same as one defined in the `.http` file, or it can be different. If a variable is defined in both the `.http` file and the environment file, the value in the `.http` file overrides the value in the environment file.

## Shared variables

`$shared` is a special environment name for values that are the same for multiple environments. For example, consider the following environment file (`http-client.env.json`):

```json
{
"$shared": {
"HostAddress": "https://localhost:7293"
},
"dev1": {
"username": "dev1user"
},
"dev2": {
"username": "dev2user"
},
"staging": {
"username": "staginguser",
"HostAddress": "https://staging.contoso.com"
}
}
```

In the preceding example, the `$shared` environment defines the `HostAddress` variable with the value `localhost:7293`. This variable with this value functions as a default for any environment that doesn't define a `HostAddress` variable. When you use the `dev1` or `dev2` environment, the value for `HostAddress` comes from the `$shared` environment because `dev1` and `dev2` don't define a `HostAddress` variable. When you use the `staging` environment, the value for `HostAddress` is set to `https://staging.contoso.com`, overriding the `$shared` default.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I got confused on this. Needs tweaking, but something like:

Suggested change
In the preceding example, the `$shared` environment defines the `HostAddress` variable with the value `localhost:7293`. This variable with this value functions as a default for any environment that doesn't define a `HostAddress` variable. When you use the `dev1` or `dev2` environment, the value for `HostAddress` comes from the `$shared` environment because `dev1` and `dev2` don't define a `HostAddress` variable. When you use the `staging` environment, the value for `HostAddress` is set to `https://staging.contoso.com`, overriding the `$shared` default.
In the preceding example, the `$shared` environment defines the `HostAddress` variable with the value `localhost:7293`. The `HostAddress` variable with the value `localhost:7293` value functions as a default for environments that don't define a `HostAddress`. When the `dev1` or `dev2` environment is defined, the value for `HostAddress` comes from the `$shared` environment because `dev1` and `dev2` don't define a `HostAddress` variable. When the `staging` environment is defined, the value for `HostAddress` is set to `https://staging.contoso.com`, overriding the `$shared` default.


## User-specific environment files

A user-specific value is any value that an individual developer wants to test with but doesn’t want to share with the team. Since the `http-client.env.json` file is checked in to source control by default, it wouldn’t be appropriate to add user-specific values to this file. Instead, put them in a file named `http-client.env.json.user` located in the same folder as the `http-client.env.json` file. Files that end with `.user` should be excluded from source control by default when using Visual Studio source control features.
A user-specific value is any value that an individual developer wants to test with but doesn't want to share with the team. Since the `http-client.env.json` file is checked in to source control by default, it wouldn't be appropriate to add user-specific values to this file. Instead, put them in a file named `http-client.env.json.user` located in the same folder as the `http-client.env.json` file. Files that end with `.user` should be excluded from source control by default when using Visual Studio source control features.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs tweaking, but something like

Suggested change
A user-specific value is any value that an individual developer wants to test with but doesn't want to share with the team. Since the `http-client.env.json` file is checked in to source control by default, it wouldn't be appropriate to add user-specific values to this file. Instead, put them in a file named `http-client.env.json.user` located in the same folder as the `http-client.env.json` file. Files that end with `.user` should be excluded from source control by default when using Visual Studio source control features.
A user-specific value is any value that a developer wants to test with but doesn't want to share with the team. The `http-client.env.json` file is checked in to source control by default, therefore, ***DO NOT*** add user-specific values to this file. Rather, add user-specific values in a file named `http-client.env.json.user`. The `http-client.env.json.user` is located in the same folder as the `http-client.env.json` file. Files that end with `.user` are excluded from source control by default when using Visual Studio source control features.


When the `http-client.env.json` file is loaded, Visual Studio looks for a sibling `http-client.env.json.user` file. If a variable is defined in an environment in both the `http-client.env.json` file and the `http-client.env.json.user` file, the value in the `http-client.env.json.user` file wins.

Expand Down Expand Up @@ -330,7 +354,7 @@ GET {{HostAddress}}{{Path}}
X-UserName: {{$processEnv USERNAME}}
```

If you try to use `$processEnv` to access an environment variable that doesn’t exist, the `.http` file editor displays an error message.
If you try to use `$processEnv` to access an environment variable that doesn't exist, the `.http` file editor displays an error message.

## `.env` files

Expand Down
Loading