Document shared environments in environment files (#34406)

Author: tdykstra

aspnetcore/test/http-files.md

@@ -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.
@@ -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`. The `HostAddress` variable with the value `localhost:7293` 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 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` file 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.
 
@@ -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