Skip to content

parameters.md

Latest commit

 

History

History
114 lines (88 loc) · 2.76 KB

parameters.md

File metadata and controls

114 lines (88 loc) · 2.76 KB
description Reference for the 'parameters' DSC configuration document function
ms.date 02/28/2025
ms.topic reference
title parameters

parameters

Synopsis

Returns the value of a configuration parameter.

Syntax

parameters('<name>')

Description

The parameters() function returns the value of a specific parameter. You must pass the name of a valid parameter. When using this function for a resource instance, DSC validates the instance properties after this function runs and before calling the resource for the current operation. If the referenced parameter value is invalid for the property, DSC raises a validation error.

For more information about defining parameters in a configuration document, see DSC Configuration document parameter schema.

Examples

Example 1 - Use a parameter as a resource instance property value

The configuration uses the parameters() function to echo the value of the message parameter.

# parameters.example.1.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
parameters:
  message:
    type:         string
    defaultValue: Hello, world!
resources:
  - name: Echo message parameter
    type: Microsoft.DSC.Debug/Echo
    properties:
      output: "[parameters('message')]"

First, get the current state of the configuration without overriding the parameters with the --parameters or --parameters_file options. The output shows the default value for the message parameter.

config_file=parameters.example.1.dsc.config.yaml
cat $config_file | dsc config get
results:
- name: Echo message parameter
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output: Hello, world!
messages: []
hadErrors: false

Next, override the message parameter with the --parameters option.

params='{"parameters": {"message": "Hi, override."}}'
cat $config_file | dsc config --parameters $params get
results:
- name: Echo message parameter
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output: Hi, override.
messages: []
hadErrors: false

Parameters

name

The parameters() function expects a single string as input, representing the name of the parameter to return. If no parameter with the specified name is defined in the configuration document, DSC raises an error during validation.

Type:         string
Required:     true
MinimumCount: 1
MaximumCount: 1

Output

The parameters() function returns the value of the specified parameter.

Type: [string, int, bool, object, array]