Environment variables in Dataverse — a deep dive

Environment variables are Dataverse's mechanism for per-environment configuration: URLs, thresholds, feature flags, secrets. A solution defines the variables; each environment supplies values. Used well, they decouple environment-specific configuration from solution content, making ALM clean and deployment predictable.

The two records per variable.

• Environment Variable Definition — the variable's name, datatype, default value, description.
• Environment Variable Value — the value for this specific environment.

The definition is solution-aware (moves between environments); the value is per-environment (stays where you set it).

Datatypes.

• String — text.
• Number — integer.
• Boolean — true/false.
• DateTime — date and time.
• JSON — structured data.
• Secret — reference to Azure Key Vault secret.

The datatype determines how values are entered and validated.

Default values. A definition can specify a default:

• Used when no environment-specific value exists.
• Useful for development environments that don't need explicit setting.
• Production should always have explicit values (never rely on defaults).

Using environment variables.

In Power Automate:

@{environmentVariables('myVarName')}

In Power Apps canvas:

EnvironmentVariable.myVarName

In plug-ins: Read via Dataverse API at runtime.

In flow conditions: Reference variable to drive branching.

Per-environment values. After importing a solution:

• New variables appear unbound to environment-specific values.
• Admin must set values for the target environment.
• Solution import wizard prompts for new variables (with defaults shown).

This is the deployment moment where ops team supplies per-environment configuration.

Solution layering. Variables are managed-solution-aware:

• Variable definition in a solution → managed; can't be edited at environment.
• Variable value at environment → unmanaged; environment admin sets.
• Updates to variable definition flow through solution upgrades.

Variables vs hardcoded values.

• Hardcoded URL — changes require code change.
• Variable URL — changes per environment without code.

Anything that varies between environments should be a variable.

Variables vs connection references.

• Variable — values (URLs, thresholds, feature flags).
• Connection reference — abstract connection bindings to specific connections per environment.

They serve different purposes; both decouple environment specifics.

Secret-type variables. As covered in [[dataverse-secrets-and-key-vault-integration]]:

• Definition declares datatype as Secret.
• Value references Key Vault.
• Runtime fetches actual secret.

For production secrets, this is the canonical pattern.

Common variables in real solutions.

• External API URL — varies between sandbox and production.
• Feature flag — enable/disable specific features.
• Email sender address — varies per environment.
• Tenant identifier — for multi-tenant logic.
• API timeout values — tuning per environment.
• Email recipient list — for notifications.

JSON variables. For complex configuration:

{
  "endpoints": {
    "primary": "https://...",
    "fallback": "https://..."
  },
  "timeouts": {
    "default": 30,
    "long": 300
  }
}

Parse in code at use time. Useful for tightly-related configuration values.

Variable scope.

• Environment variables are environment-scoped, not solution-scoped.
• All solutions in the environment share variables.
• Naming conventions matter to avoid collisions.

Naming conventions.

• mySolution_apiUrl — prefixed by solution publisher.
• Camel case or snake case — be consistent.
• Avoid generic names like apiUrl (collision risk).

ALM deployment patterns.

• Solution package + variables — variables defined in solution; values set per-environment post-import.
• Pipelines — automated; variables values from pipeline configuration.
• Documentation — list of variables and per-environment values.

The deployment runbook lists every variable to verify after solution import.

Common pitfalls.

• Default values relied on in production. Default fires; behaviour wrong.
• No documentation of variables. New ops team can't determine what to set.
• Hardcoded values bypassing variables. Same problem variables were meant to solve.
• Variable value missed during deployment. Variable undefined; runtime fails.
• Naming collisions across solutions. Two solutions need the same logical config; choose one as authoritative.
• Sensitive values in non-Secret type. Plain-text secret in a String variable; security gap.

Migration to environment variables. From hardcoded:

1. Identify hardcoded values across solution.
2. Group into logical variables.
3. Create environment variable definitions.
4. Update code/flows to read from variables.
5. Set values per environment.
6. Test.
7. Deploy.

This refactoring pays back continuously across future deployments.

Best practices.

• One variable per logical configuration value. Don't over-pack into JSON.
• Documented and described. Future operators understand purpose.
• Validated values. Where possible, validate format / range.
• Audit changes. Variable values are operational config; track changes.
• Convention over flexibility. Standard naming, standard usage patterns.

Strategic positioning. Environment variables are the unsung hero of Dataverse ALM. Solutions become portable; deployments become repeatable; configuration is decoupled from code. Mature deployments use environment variables liberally; immature ones have hardcoded environment-specific values scattered through code. The investment in variable discipline is moderate; the payback is in every deployment, every incident, every audit. Treat environment variables as a foundational pattern, not an optional convenience.