Include variables from external files

[Gijsreyn]

Summary of the new feature / enhancement

As a DSC configuration author,
I want to load variables from external files,
So that I can reuse common variable definitions across multiple configurations without duplicating them.

As a DevOps engineer,
I want to separate environment-specific variables from my configuration documents,
so that I can maintain a single configuration file and swap variable files for different
environments (dev, staging, production).

As an infrastructure-as-code practitioner,
I want to organize my variables in dedicated files,
so that I can manage configuration complexity and improve maintainability.

Proposed technical implementation details (optional)

Background

Currently, Microsoft DSC only supports:

• Inline variables using the variables property in the configuration document.
• Parameters from files via the --parameters-file CLI option (or parametersContent in the Include` resource)

However, other configuration management tooling includes features supporting loading variables from external files at the configuration document level. This limitation forces users to:

1. Duplicate variable definitions across multiple configurations
2. Use parameters (which are designed for runtime overrides) when static reusable values would be more appropriate
3. Maintain larger, less maintainable configuration documents

Proposed experience

Add a new optional property variablesFiles at the configuration document level:

# config.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3.2/bundled/config/document.json
variablesFiles:
  - common/variables.yaml
  - environments/production.yaml
variables:
  # Inline variables can still be defined and will merge with file variables
  localVar: "inline value"
resources:
  - name: Example
    type: Microsoft.DSC.Debug/Echo
    properties:
      output: "[variables('serverPort')]"  # From variables file

Variables file format (common/variables.yaml):

# Variables file - simple key-value pairs
serverPort: 8080
serverName: production-server
database:
  host: db.example.com
  port: 5432

Or to keep it consistent with how you define it in --parameters-file:

# Variables file - simple key-value pairs
variables:
  serverPort: 8080
  serverName: production-server
  database:
    host: db.example.com
    port: 5432

(not to forget the support in JSON):

{
  "serverPort": 8080,
  "serverName": "production-server",
  "database": {
    "host": "db.example.com",
    "port": 5432
  }
}

CLI option for variables file

Add a new CLI option --variables-file (or -v):

dsc config get --file config.dsc.yaml --variables-file common/variables.yaml

Multiple files can be specified:

dsc config get --file config.dsc.yaml \
  --variables-file common/variables.yaml \
  --variables-file environments/prod.yaml

Combined usage example

1. Base variables file (variables/common.yaml):

appName: MyApplication
logLevel: info
ports:
  http: 80
  https: 443

2. Environment-specific file (variables/prod.yaml):

logLevel: warning
database:
  connectionString: "Server=prod-db;Database=app"

3. Configuration document (config.dsc.yaml):

$schema: https://aka.ms/dsc/schemas/v3.2/bundled/config/document.json
variablesFiles:
  - variables/common.yaml
  - variables/prod.yaml
variables:
  deployTime: "[dateTimeAdd(utcNow(), 'PT0S')]"
resources:
  - name: Configure App
    type: MyOrg/AppConfig
    properties:
      name: "[variables('appName')]"
      logLevel: "[variables('logLevel')]"
      httpPort: "[variables('ports').http]"
      dbConnection: "[variables('database').connectionString]"

Specification

Configuration document schema changes

Add new optional property to the Configuration schema:

{
  "variablesFiles": {
    "type": "array",
    "items": {
      "type": "string",
      "description": "Path to a variables file (YAML or JSON). Relative paths are resolved from the configuration document location."
    },
    "description": "List of external files containing variables to load. Files are processed in order, with later files overriding earlier ones."
  }
}

Variables file schema

Variables files must contain a flat or nested object structure. Each top-level key becomes a variable name:

{
  "$schema": "https://aka.ms/dsc/schemas/v3.2/config/variablesFile.json",
  "type": "object",
  "additionalProperties": true,
  "description": "A file containing variable definitions for DSC configuration documents."
}

Supported file extensions:

• .yml
• .yaml
• .json

Processing order and precedence

Variables are loaded and merged in the following order (later overrides earlier):

1. Load variables files specified in variablesFiles property (document-level, in array order)
2. Merge inline variables from the document
3. Load variables files specified via --variables-file CLI option (in order specified)

Path resolution

• Absolute paths: Used as-is
• Relative paths: Resolved relative to the configuration document location (using
  DSC_CONFIG_ROOT)
• Security: Parent directory traversal (..) is not allowed (consistent with existing Include
  behavior)

Merge behavior

Variables are merged using the following rules:

• Scalar values: Later values replace earlier values
• Objects: Deep merge (keys are merged recursively)
• Arrays: Later arrays replace earlier arrays (no concatenation)