(GH-420) Add environment variable conceptual document

[Gijs Reijn (Gijsreyn)]

PR Summary

Adds a new conceptual document describing how environment variables are read and set, how they change resource discovery, and more.

Fixes #420

PR Checklist

• Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• Summary: This PR's summary describes the scope and intent of the change.
• Contributor's Guide: I have read the contributors guide.
• Style: This PR adheres to the style guide.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 92339fd:

✅ Validation status: passed

File	Status	Preview URL	Details
dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md	✅Succeeded	View (dsc-3.0)
dsc/docs-conceptual/dsc-3.0/concepts/toc.yml	✅Succeeded

For more details, please refer to the build report.

[Copilot]

🟡 Changes recommended

Unresolved documentation corrections affect platform behavior, path resolution, discovery, and precedence guidance.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a DSC 3.0 conceptual guide for environment variables and links it in the concepts navigation.

Changes:

• Documents environment-variable behavior, discovery, configuration, tracing, and precedence.
• Adds the article to the DSC 3.0 concepts table of contents.

File summaries

File	Description
dsc/docs-conceptual/dsc-3.0/concepts/toc.yml	Adds the environment variables article to navigation.
dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md	Adds conceptual documentation for DSC environment variables.

Review details

Suppressed comments (6)

dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md:71

• The later precedence section says resourcePath.allowEnvOverride controls whether this variable is honored, but this introduction presents the restricted path as unconditional. With the setting disabled, these bullets are not the behavior users get; make the condition explicit here.

`DSC_RESTRICTED_PATH` is a stricter form of `DSC_RESOURCE_PATH`. When you define it, DSC:

dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md:239

• systemRoot() is based on the Windows SystemRoot value (for example, C:\Windows), not SYSTEMDRIVE (which is the drive-only value such as C:\). This row currently documents the wrong variable and the wrong result.

| `SYSTEMDRIVE`  | Windows      | Default value of the `systemRoot()` function, such as `C:\`. |

dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md:124

• The --file syntax also uses --file - for stdin, so the first bullet is too broad: stdin has no containing document folder. Clarify that the first case is a real file path and include --file - in the stdin case to avoid documenting the wrong DSC_CONFIG_ROOT behavior.

- When you specify a configuration document with the [`--file`][02] option, DSC sets
  `DSC_CONFIG_ROOT` to the absolute path of the folder that contains the document.
- When you pass the configuration document with the `--input` option or from stdin, DSC keeps the
  existing value of `DSC_CONFIG_ROOT` if the variable is already defined. Otherwise, DSC sets the
  variable to the current working directory.

dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md:63

• The changelog says that when DSC_RESOURCE_PATH is set, DSC restricts discovery of both manifests and the executables they reference to the listed paths (dsc/docs-conceptual/dsc-3.0/changelog.md:313-316). This paragraph instead says the DSC executable directory is added to PATH so shipped executables still work, which gives the opposite guidance. Revise this and the later PATH description to distinguish child-process inheritance from DSC's restricted executable discovery.

When `DSC_RESOURCE_PATH` is defined, DSC still adds the folder that contains the `dsc` executable
to `PATH` if it isn't already there. This ensures that resource manifests that reference
executables shipped with DSC continue to work. DSC doesn't search that folder for manifests unless
you include it in `DSC_RESOURCE_PATH`.

dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md:244

• These two adapter references maintain their own caches (PSAdapterCache.json and WindowsPSAdapterCache.json), while AdaptedResourcesLookupTable.json is the general adapted-resource discovery cache documented by dsc resource list. Attributing this file to the PowerShell adapters sends readers to the wrong cache and troubleshooting location.

The adapter cache is the `AdaptedResourcesLookupTable.json` file that the
[Microsoft.DSC/PowerShell][06] and [Microsoft.Windows/WindowsPowerShell][07] adapters use to
speed up discovery. For more information, see [dsc resource list][08].

dsc/docs-conceptual/dsc-3.0/concepts/environment-variables.md:124

• The existing Microsoft.DSC/Include reference says that relative paths supplied with configuration content resolve against the current working directory, but this section says --input and stdin retain an inherited DSC_CONFIG_ROOT. That produces different documented results for the same kind of invocation; reconcile the two references or explicitly document the exception in the Include guidance.

- When you pass the configuration document with the `--input` option or from stdin, DSC keeps the
  existing value of `DSC_CONFIG_ROOT` if the variable is already defined. Otherwise, DSC sets the
  variable to the current working directory.

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.