dotnet / dotnet/sdk

Document dotnetup user and developer environment variables separately

Open
#55,580 2 comments 1 reaction 3 assignees Claimed by @nagilson View on GitHub
Area-dotnetup cookie documentation
Dominant language
C#
Stars
3.2k
Forks
1.3k
PR merge metrics
PR metrics pending

Description

## Description

Create dedicated environment-variable documentation for `dotnetup`, split by audience:

1. A user-facing reference for supported `dotnetup` environment variables and supported .NET CLI variables that affect dotnetup.
2. A contributor/developer reference for diagnostics, test hooks, and implementation-only environment variables.

This follows the discussion in dotnet/sdk#55421: https://github.com/dotnet/sdk/pull/55421#discussion_r3705804171

The telemetry documentation currently contains a `Related Environment Variables` section added or updated as part of #55421. That information should be reorganized rather than lost:

- `DOTNET_CLI_TELEMETRY_STORAGE_PATH`
- `DOTNET_CLI_TELEMETRY_SHUTDOWN_TIMEOUT_MS`
- `DOTNETUP_TELEMETRY_FORCE_LOCAL_DELIVERY`

The audit should cover all environment variables consumed by dotnetup, including direct string lookups and constants. Current examples include:

- User/runtime behavior: `DOTNET_CLI_TELEMETRY_OPTOUT`, `DOTNET_NOLOGO`, `DOTNET_CLI_UI_LANGUAGE`, `VSLANG`, `DOTNET_DOTNETUP_DATA_DIR`, `DOTNET_CLI_TELEMETRY_SHUTDOWN_TIMEOUT_MS`, and `DOTNETUP_TELEMETRY_FORCE_LOCAL_DELIVERY`.
- Developer/diagnostic behavior: `DOTNETUP_TELEMETRY_DEBUG`, `DOTNETUP_CLI_GET_PERF_TRACE`, `DOTNETUP_DEV_BUILD`, telemetry exporter overrides, and disk logging.
- Test-only hooks: `DOTNET_CLI_TELEMETRY_E2E_CONNECTION_STRING`, `DOTNET_TESTHOOK_DOTNETUP_TELEMETRY_SHUTDOWN_BUDGET_PATH`, `DOTNET_TESTHOOK_MANIFEST_PATH`, and `DOTNET_TESTHOOK_DEFAULT_DOTNET_PATH`.

Variables owned and already documented by the .NET CLI should link to the canonical CLI documentation instead of duplicating definitions that may drift. The documentation should explicitly decide where `DOTNET_CLI_TELEMETRY_STORAGE_PATH` belongs if it is not already covered canonically.

The shutdown-timeout and force-local-delivery controls should remain discoverable to users. They allow CI users to choose the latency/reliability tradeoff rather than disabling telemetry entirely, and force-local delivery may later be useful for GitHub Actions or Azure DevOps task integration.

## Acceptance criteria

- Add a consolidated user-facing `dotnetup` environment-variable reference in the canonical dotnetup documentation area.
- Add a separate contributor/developer environment-variable reference for diagnostics and test hooks.
- Audit dotnetup source and tests for all consumed environment variables and classify each as user-facing, shared .NET CLI, developer/diagnostic, or test-only.
- Link shared .NET CLI variables to their canonical documentation instead of duplicating their contracts.
- Update `src/Installer/dotnetup.Library/docs/dotnetup-telemetry.md` so its environment-variable content links to the new references and remains focused on telemetry behavior and privacy.
- Preserve documentation for the CI shutdown timeout and force-local-delivery controls in the user-facing reference.
- Ensure documentation distinguishes supported public controls from implementation details and test hooks.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.