diff --git a/docs/reference/cli/config/command.md b/docs/reference/cli/config/command.md new file mode 100644 index 000000000..0b8bbc07a --- /dev/null +++ b/docs/reference/cli/config/command.md @@ -0,0 +1,66 @@ +# dsc config + +## Synopsis + +Apply a configuration document. + +## Syntax + +```sh +dsc config [Options] +``` + +## Description + +The `dsc config` command includes subcommands for managing the resource instances defined in a DSC +configuration document. To manage resources directly, see the [dsc resource][01] command. + +## Commands + +### get + +The `get` command retrieves the current state of the resource instances in a configuration +document. For more information, see [dsc config get][02]. + +### set + +The `set` command enforces the desired state of the resource instances in a configuration document. +For more information, see [dsc config set][03]. + +### test + +The `test` command verifies whether the resource instances in a configuration document are in the +desired state. For more information, see [dsc config test][04]. + +### help + +The `help` command returns help information for this command or a subcommand. + +To get the help for a command or subcommand, use the syntax: + +```sh +dsc config help [] +``` + +For example, `dsc config help` gets the help for this command. `dsc config help set` gets the help +for the `set` subcommand. + +You can also use the [--help](#h---help) option on the command or subcommand to display the help +information. For example, `dsc config --help` or `dsc config set --help`. + +## Options + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +[01]: ../resource/command.md +[02]: get.md +[03]: set.md +[04]: test.md diff --git a/docs/reference/cli/config/get.md b/docs/reference/cli/config/get.md new file mode 100644 index 000000000..035b0f822 --- /dev/null +++ b/docs/reference/cli/config/get.md @@ -0,0 +1,72 @@ +# dsc config get + +## Synopsis + +Retrieves the current state of resource instances in a configuration document. + +## Syntax + +```sh +dsc config get [Options] +``` + +## Description + +The `get` subcommand returns the current state of the resource instances in a configuration +document. When this command runs, DSC validates the configuration document before invoking the get +operation for each resource instance defined in the document. + +The configuration document must be passed to this command as JSON or YAML over stdin. + +## Examples + +### Example 1 - Get the current state of a configuration's resource instances + +The command returns the actual state for the resource instances defined in the configuration +document saved as `example.dsc.config.yaml`. + +```yaml +# example.dsc.config.yaml +$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json +resources: +- name: Windows only + type: DSC/AssertionGroup + properties: + $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json + resources: + - name: os + type: Microsoft/OSInfo + properties: + family: Windows +- name: Current user registry example + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\example + _ensure: Present + dependsOn: + - '[DSC/Assertion]Windows only' +``` + +```sh +cat ./example.dsc.config.yaml | dsc config get +``` + +## Options + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns JSON output that includes whether the operation or any resources raised any +errors, the collection of messages emitted during the operation, and the get operation results for +every instance. For more information, see [dsc config get result schema][01]. + +[01]: ../../schemas/outputs/config/get.md diff --git a/docs/reference/cli/config/set.md b/docs/reference/cli/config/set.md new file mode 100644 index 000000000..b47c87a4d --- /dev/null +++ b/docs/reference/cli/config/set.md @@ -0,0 +1,73 @@ +# dsc config set + +## Synopsis + +Enforces the desired state of resource instances in a configuration document. + +## Syntax + +```sh +dsc config set [Options] +``` + +## Description + +The `set` subcommand enforces the desired state of the resource instances in a configuration +document. When this command runs, DSC validates the configuration document before invoking the test +operation for each resource instance defined in the document. DSC then invokes the set operation +for each resource instance that isn't in the desired state. + +The configuration document must be passed to this command as JSON or YAML over stdin. + +## Examples + +### Example 1 - Set a configuration's resource instances to the desired state + +The command inspects the resource instances defined in the configuration document saved as +`example.dsc.config.yaml` and sets them to the desired state as needed. + +```yaml +# example.dsc.config.yaml +$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json +resources: +- name: Windows only + type: DSC/AssertionGroup + properties: + $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json + resources: + - name: os + type: Microsoft/OSInfo + properties: + family: Windows +- name: Current user registry example + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\example + _ensure: Present + dependsOn: + - '[DSC/Assertion]Windows only' +``` + +```sh +cat ./example.dsc.config.yaml | dsc config set +``` + +## Options + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns JSON output that includes whether the operation or any resources raised any +errors, the collection of messages emitted during the operation, and the set operation results for +every instance. For more information, see [dsc config get result schema][01]. + +[01]: ../../schemas/outputs/config/set.md diff --git a/docs/reference/cli/config/test.md b/docs/reference/cli/config/test.md new file mode 100644 index 000000000..e60838aa4 --- /dev/null +++ b/docs/reference/cli/config/test.md @@ -0,0 +1,72 @@ +# dsc config test + +## Synopsis + +Verifies whether the resource instances in a configuration document are in the desired state. + +## Syntax + +```sh +dsc config test [Options] +``` + +## Description + +The `test` subcommand verifies whether the resource instances in a configuration document are in +the desired state. When this command runs, DSC validates the configuration document before invoking +the test operation for each resource instance defined in the document. + +The configuration document must be passed to this command as JSON or YAML over stdin. + +## Examples + +### Example 1 - Test whether a configuration's resource instances are in the desired state + +The command returns the status, desired state, actual state, and differing properties for the +resource instances defined in the configuration document saved as `example.dsc.config.yaml`. + +```yaml +# example.dsc.config.yaml +$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json +resources: +- name: Windows only + type: DSC/AssertionGroup + properties: + $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json + resources: + - name: os + type: Microsoft/OSInfo + properties: + family: Windows +- name: Current user registry example + type: Microsoft.Windows/Registry + properties: + keyPath: HKCU\example + _ensure: Present + dependsOn: + - '[DSC/Assertion]Windows only' +``` + +```sh +cat ./example.dsc.config.yaml | dsc config test +``` + +## Options + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns JSON output that includes whether the operation or any resources raised any +errors, the collection of messages emitted during the operation, and the test operation results for +every instance. For more information, see [dsc config test result schema][01]. + +[01]: ../../schemas/outputs/config/test.md diff --git a/docs/reference/cli/dsc.md b/docs/reference/cli/dsc.md new file mode 100644 index 000000000..8adc93757 --- /dev/null +++ b/docs/reference/cli/dsc.md @@ -0,0 +1,100 @@ +# dsc + +## Synopsis + +Apply configuration or invoke specific resources to manage software components. + +## Syntax + +```sh +dsc [Options] +``` + +## Commands + +### config + +The `config` command manages a DSC Configuration document. You can use it to: + +- Get the current state of the configuration. +- Test whether a configuration is in the desired state. +- Set a configuration to the desired state. + +For more information, see [config][01]. + +### resource + +The `resource` command manages a DSC Resource. You can use it to: + +- List the available resources. +- Get the JSON schema for a resource's instances. +- Get the current state of a resource instance. +- Test whether a resource instance is in the desired state. +- Set a resource instance to the desired state. + +For more information, see [resource][02] + +### schema + +The `schema` command returns the JSON schema for a specific DSC type. For more information, see +[schema][03]. + +### help + +The `help` command returns help information for dsc, a command, or a subcommand. + +To get the help for a command or subcommand, use the syntax: + +```sh +dsc help [] +``` + +For example, `dsc help config` gets the help for the `config` subcommand. `dsc help config set` +gets the help for the `config set` subcommand. + +You can also use the [--help](#h---help) option on a command to display the help information. For +example, `dsc config --help` or `dsc config set --help`. + +## Options + +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +To set the output format for a command or subcommand, specify this option before the command, like +`dsc --format pretty-json resource list`. + +```yaml +Type: String +Mandatory: false +Default Value: yaml +Valid Values: + - json + - pretty-json + - yaml +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +### -V, --version + +Displays the version of the application. When you specify this option, the application ignores all +options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +[01]: config.md +[02]: resource/command.md +[03]: schema.md diff --git a/docs/reference/cli/resource/command.md b/docs/reference/cli/resource/command.md new file mode 100644 index 000000000..24bfc23a8 --- /dev/null +++ b/docs/reference/cli/resource/command.md @@ -0,0 +1,80 @@ +# dsc resource + +## Synopsis + +Invoke a specific DSC Resource. + +## Syntax + +```sh +dsc resource [Options] +``` + +## Description + +The `dsc resource` command contains subcommands for listing DSC Resources and invoking them +directly. To manage resource instances in a configuration, see the [dsc config][01] command. + +## Commands + +### list + +The `list` command returns the list of available DSC Resources with an optional filter. For more +information, see [dsc resource list][02]. + +### get + +The `get` command invokes the get operation for a resource, returning the current state of a +resource instance. For more information, see [dsc resource get][03]. + +### set + +The `set` command invokes the set operation for a resource, enforcing the desired state of a +resource instance and returning the final state. For more information, see [dsc resource set][04]. + +### test + +The `test` command invokes the test operation for a resource, returning the expected and actual +state of an instance and an array of properties that are out of the desired state. For more +information, see [dsc resource test][05]. + +### schema + +The `schema` command returns the JSON Schema for instances of a resource. This schema validates an +instance before any operations are sent to the resource. For more information, see +[dsc resource schema][06]. + +### help + +The `help` command returns help information for this command or a subcommand. + +To get the help for a command or subcommand, use the syntax: + +```sh +dsc resource help [] +``` + +For example, `dsc resource help` gets the help for this command. `dsc resource help list` +gets the help for the `list` subcommand. + +You can also use the [--help](#h---help) option on the command or subcommand to display the help +information. For example, `dsc resource --help` or `dsc resource set --help`. + +## Options + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +[01]: ../config/command.md +[02]: list.md +[03]: get.md +[04]: set.md +[05]: test.md +[06]: schema.md diff --git a/docs/reference/cli/resource/get.md b/docs/reference/cli/resource/get.md new file mode 100644 index 000000000..ba2c09b00 --- /dev/null +++ b/docs/reference/cli/resource/get.md @@ -0,0 +1,133 @@ +# dsc resource get + +## Synopsis + +Invokes the get operation of a resource. + +## Syntax + +```sh +dsc resource get [Options] --resource +``` + +## Description + +The `get` subcommand returns the current state of a resource instance. + +This subcommand returns one instance from a specific DSC Resource. To return multiple resources, +use a resource group or the [dsc config get][01] command. + +Any properties the resource requires for retrieving the state of an instance must be passed to this +command as JSON. The JSON can be passed to this command from stdin or with the `--input` option. + +## Examples + +### Example 1 - Get resource instance without any input + +For resources single-instance resources that don't require any property values to return the actual +state of the resource instance, the JSON input isn't required. + +```sh +dsc resource get --resource Microsoft/OSInfo +``` + +```yaml +actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22621 + edition: Windows 11 Enterprise + bitness: '64' +``` + +### Example 2 - Get resource instance with input option + +If a resource requires one or more property values to return the actual state of the instance, the +JSON object can be passed with the **input** option. + +```sh +dsc resource get --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion", + "valueName": "SystemRoot" +}' +``` + +```yaml +actualState: + $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot + valueData: + String: C:\WINDOWS +``` + +### Example 3 - Get resource instance with input from stdin + +If a resource requires one or more property values to return the actual state of the instance, the +JSON object can be passed over stdin. + +```sh +'{ + "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion", + "valueName": "SystemRoot" +}' | dsc resource get --resource Microsoft.Windows/Registry +``` + +```yaml +actualState: + $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot + valueData: + String: C:\WINDOWS +``` + +## Options + +### -r, --resource + +Specifies the fully qualified type name of the DSC Resource to use, like +`Microsoft.Windows/Registry`. + +The fully qualified type name syntax is: `[.][.]/`, where: + +- The `owner` is the maintaining author or organization for the resource. +- The `group` and `area` are optional name components that enable namespacing for a resource. +- The `name` identifies the component the resource manages. + +```yaml +Type: String +Mandatory: true +``` + +### -i, --input + +Specifies a JSON object with the properties needed for retrieving an instance of the DSC Resource. +DSC validates the JSON against the resource's instance schema. If the validation fails, DSC raises +an error. + +This option can't be used with JSON over stdin. Choose whether to pass the instance JSON to the +command over stdin or with the `--input` flag. + +```yaml +Type: String +Mandatory: false +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns JSON output that includes the actual state of the instance. For more +information, see [dsc resource get result schema][02]. + +[01]: ../config/get.md +[02]: ../../schemas/outputs/resource/ diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md new file mode 100644 index 000000000..28addb980 --- /dev/null +++ b/docs/reference/cli/resource/list.md @@ -0,0 +1,176 @@ +# dsc resource list + +## Synopsis + +Returns the list of available DSC Resources with an optional filter. + +## Syntax + +```sh +dsc resource list [Options] +``` + +## Description + +The `list` subcommand searches for available DSC Resources and returns their information. DSC +discovers resources by first searching the `PATH` for `.dsc.resource.json` files. If any of the +discovered resources are resource providers, DSC then calls the providers to list their resources, +too. + +DSC returns the list of discovered resources with their implementation information and metadata. If +the command includes the `RESOURCE_NAME` argument, DSC filters the list of discovered resources +before returning them. The **description** and **tags** options filter the results by the +resource descriptions and tags. + +## Examples + +### Example 1 - List all resources + +Without any filters, the command returns every discovered DSC Resource. + +```sh +dsc resource list +``` + +```Output +type version tags description +---- ------- ---- ----------- +Test/TestGroup 0.1.0 +Microsoft/OSInfo 0.1.0 {os, linux, windows, macos} Returns information about the operating system. +Microsoft.Windows/Registry 0.1.0 {Windows, NT} Registry configuration provider for the Windows Registry + This is a test resource. +DSC/PowerShellGroup 0.1.0 {PowerShell} Resource provider to classic DSC Powershell resources. +DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. +DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. + This is a test resource. +DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +``` + +### Example 2 - List a specific resource + +When the `RESOURCE_NAME` argument doesn't include a wildcard, the command returns only the resource +with the specified type name. + +```sh +dsc resource list DSC/Group +``` + +```Output +Type Version Requires Description +------------------------------------------------------------------------------------------------ +DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +``` + +### Example 3 - List resources with a matching type name + +When the `RESOURCE_NAME` argument includes a wildcard, the command returns every resource with a +matching type name. + +```sh +dsc resource list DSC/* +``` + +```Output +Type Version Requires Description +--------------------------------------------------------------------------------------------------------------- +DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. +DSC/PowerShellGroup 0.1.0 Resource provider to classic DSC Powershell resources. +DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. +``` + +### Example 4 - List resources with a matching description + +When the command includes the **description** option, the results include resources that have a +description containing the specified value. + +```sh +dsc resource list --description 'supplied configuration' +``` + +```Output +Type Version Requires Description +-------------------------------------------------------------------------------------------------------------- +DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. +DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. +DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +``` + +### Example 5 - List resources with matching tags + +When the command includes multiple instances of the **tags** option, the results include resources +that have any of the specified tags. + +```sh +dsc resource list --tags Windows --tags Linux +``` + +```output +Type Version Requires Description +------------------------------------------------------------------------------------------------------- +Microsoft.Windows/Registry 0.1.0 Registry configuration provider for the Windows Registry +Microsoft/OSInfo 0.1.0 Returns information about the operating system. +``` + +## Arguments + +### RESOURCE_NAME + +Specifies an optional filter to apply for the type names of discovered DSC Resources. The filter +may include wildcards (`*`). The filter isn't case-sensitive. + +When this argument is specified, DSC filters the results to include only resources where the +resource type name matches the filter. + +For example, specifying the filter `Microsoft.*` returns only the resources published by Microsoft. +Specifying the filter `*Sql*` returns any resource with the string `Sql` in its name, regardless of +the casing. + +```yaml +Type: String +Mandatory: false +``` + +## Options + +### -d, --description + +Specifies a string to match in a resource's description. When this option is specified, DSC filters +the resources by their description strings. The filter is case-insensitive and matches the value +anywhere in the description string. Wildcards aren't permitted. + +```yaml +Type: String +Mandatory: false +``` + +### -t, --tags + +Specifies a resource tag to filter on. When this option is specified, DSC filters the resources and +only includes those with a matching tag. The filter is case-insensitive. Wildcards aren't permitted. + +You can specify this option more than once to filter on a set of tags. The results include +resources that have at least one of the tags specified with this option. + +```yaml +Type: String +Mandatory: false +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns a JSON object for each resource that includes the resource's type, version, +manifest settings, and other metadata. For more information, see +[dsc resource list result schema][01]. + +[01]: ../../schemas/output/resource/list.md diff --git a/docs/reference/cli/resource/schema.md b/docs/reference/cli/resource/schema.md new file mode 100644 index 000000000..e287f044b --- /dev/null +++ b/docs/reference/cli/resource/schema.md @@ -0,0 +1,107 @@ +# dsc resource schema + +## Synopsis + +Returns the JSON Schema for instances of a resource. + +## Syntax + +```sh +dsc resource schema [Options] --resource +``` + +## Description + +The `schema` subcommand returns the JSON schema for a instances of a specific DSC Resource. DSC +uses these schemas to validate the input for the `get`, `set`, and `test` subcommands and when +validating the instances in a DSC Configuration document. + +Integrating tools may use these schemas for validation or to enhance the configuration authoring +experience. A resource's instance schema defines the valid structure for an instance, including +which properties are mandatory and what their values should be. The instance schemas may also +include lightweight documentation for the properties with the `title` and `description` keywords. + +## Examples + +### Example 1 - Get the schema for a resource + +This example returns the schema for the `OSInfo` command-based DSC Resource. + +```sh +dsc resource schema --resource Microsoft/OSInfo +``` + +```yaml +$schema: http://json-schema.org/draft-07/schema# +title: OsInfo +type: object +required: [] +properties: + $id: + type: string + architecture: + type: + - string + - 'null' + bitness: + $ref: '#/definitions/Bitness' + codename: + type: + - string + - 'null' + edition: + type: + - string + - 'null' + family: + $ref: '#/definitions/Family' + version: + type: string +additionalProperties: false +definitions: + Bitness: + type: string + enum: + - '32' + - '64' + - unknown + Family: + type: string + enum: + - Linux + - MacOS + - Windows +``` + +## Options + +### -r, --resource + +Specifies the fully qualified type name of the DSC Resource to retrieve the instance schema from, +like `Microsoft.Windows/Registry`. + +The fully qualified type name syntax is: `[.][.]/`, where: + +- The `owner` is the maintaining author or organization for the resource. +- The `group` and `area` are optional name components that enable namespacing for a resource. +- The `name` identifies the component the resource manages. + +```yaml +Type: String +Mandatory: true +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns a JSON object representing the JSON schema for an instance of the specified +DSC Resource. diff --git a/docs/reference/cli/resource/set.md b/docs/reference/cli/resource/set.md new file mode 100644 index 000000000..61137b6e1 --- /dev/null +++ b/docs/reference/cli/resource/set.md @@ -0,0 +1,114 @@ +# dsc resource set + +## Synopsis + +Invokes the set operation of a resource. + +## Syntax + +```sh +dsc resource set [Options] --resource +``` + +## Description + +The `set` subcommand enforces the desired state of a resource instance and returns the final state. + +This subcommand sets one instance of a specific DSC Resource. To set multiple resources, +use a resource group or the [dsc config set][01] command. + +The desired state of the instance to set must be passed to this command as JSON. The JSON can be +passed to this command from stdin or with the `--input` option. + +This subcommand can only be invoked for command-based DSC Resources that define the `set` section +of their resource manifest. If this subcommand is called for a resource that doesn't define a set +operation, DSC raises an error. + +The subcommand's behavior depends on the value of the `set.preTest` option in the resource +manifest: + +- If the resource's manifest doesn't define the `set.preTest` key as `true`, DSC invokes the + resource's test operation to determine whether a set operation is required. + + If the instance is already in the desired state, DSC doesn't invoke the set operation. If the + instance isn't in the desired state, DSC invokes the resource's set operation with the desired + state as input. +- If the resource's manifest defines the `set.preTest` key as `true`, DSC invokes the resource's + set operation without testing the resource state first. + +## Examples + +### Example 1 - Setting a resource with properties from stdin + +The command ensures that the `Example` key exists in the current user hive. It specifies the +resource instance properties as JSON and passes them from stdin. + +```sh +'{ + "keyPath": "HKCU\\Example", + "_ensure": "present" +}' | dsc resource set --resource Microsoft.Windows/Registry +``` + +### Example 2 - Setting a resource with the input option + +The command ensures that the `Example` key exists in the current user hive. It specifies the +resource instance properties as JSON and passes them with the **input** option. + +```sh +dsc resource set --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKCU\\Example", + "_ensure": "present" +}' +``` + +## Options + +### -r, --resource + +Specifies the fully qualified type name of the DSC Resource to use, like +`Microsoft.Windows/Registry`. + +The fully qualified type name syntax is: `[.][.]/`, where: + +- The `owner` is the maintaining author or organization for the resource. +- The `group` and `area` are optional name components that enable namespacing for a resource. +- The `name` identifies the component the resource manages. + +```yaml +Type: String +Mandatory: true +``` + +### -i, --input + +Specifies a JSON object with the properties defining the desired state of a DSC Resource instance. +DSC validates the JSON against the resource's instance schema. If the validation fails, DSC raises +an error. + +This option can't be used with JSON over stdin. Choose whether to pass the instance JSON to the +command over stdin or with the `--input` flag. + +```yaml +Type: String +Mandatory: false +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns JSON output that includes the actual state of the instance before and after +the set operation, and the list of properties that the set operation modified. For more +information, see [dsc resource set result schema][02]. + +[01]: ../config/set.md +[02]: ../../schemas/outputs/resource/set.md diff --git a/docs/reference/cli/resource/test.md b/docs/reference/cli/resource/test.md new file mode 100644 index 000000000..381d05e46 --- /dev/null +++ b/docs/reference/cli/resource/test.md @@ -0,0 +1,110 @@ +# dsc resource test + +## Synopsis + +Invokes the test operation of a resource. + +## Syntax + +```sh +dsc resource test [Options] --resource +``` + +## Description + +The `test` subcommand validates the actual state of a resource instance against a desired state. + +This subcommand tests one instance of a specific DSC Resource. To test multiple resources, use a +resource group or the [dsc config test][01] command. + +The desired state of the instance to test must be passed to this command as JSON. The JSON can be +passed to this command from stdin or with the `--input` option. + +If this command is invoked for a command-based DSC Resource that doesn't define its own test +operation, DSC performs a synthetic test. The synthetic test compares each property for the desired +state of an instance against the actual state. The synthetic test uses strict, case-sensitive +equivalence. If the desired state for a property and the actual state aren't the same, DSC marks +the property as out of the desired state. + +This command only validates instance properties under two conditions: + +1. When the property is explicitly included in the desired state input. +1. When the property has a default value and isn't explicitly included in the desired state input. + +## Examples + +### Example 1 - Testing a resource with properties from stdin + +The command tests whether the `Example` key exists in the current user hive. It specifies the +resource instance properties as JSON and passes them from stdin. + +```sh +'{ + "keyPath": "HKCU\\Example", + "_ensure": "present" +}' | dsc resource test --resource Microsoft.Windows/Registry +``` + +### Example 2 - Testing a resource with the input option + +The command tests whether the `Example` key exists in the current user hive. It specifies the +resource instance properties as JSON and passes them with the **input** option. + +```sh +dsc resource test --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKCU\\Example", + "_ensure": "present" +}' +``` + +## Options + +### -r, --resource + +Specifies the fully qualified type name of the DSC Resource to use, like +`Microsoft.Windows/Registry`. + +The fully qualified type name syntax is: `[.][.]/`, where: + +- The `owner` is the maintaining author or organization for the resource. +- The `group` and `area` are optional name components that enable namespacing for a resource. +- The `name` identifies the component the resource manages. + +```yaml +Type: String +Mandatory: true +``` + +### -i, --input + +Specifies a JSON object with the properties defining the desired state of a DSC Resource instance. +DSC validates the JSON against the resource's instance schema. If the validation fails, DSC raises +an error. + +This option can't be used with JSON over stdin. Choose whether to pass the instance JSON to the +command over stdin or with the `--input` flag. + +```yaml +Type: String +Mandatory: false +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns JSON output that includes the desired state of the instance, the actual state, +the list of properties that are out of the desired state, and a boolean value indicating whether +the instance is in the desired state. For more information, see +[dsc resource test result schema][02]. + +[01]: ../config/test.md +[02]: ../../schemas/outputs/resource/test.md diff --git a/docs/reference/cli/schema/command.md b/docs/reference/cli/schema/command.md new file mode 100644 index 000000000..43c1090a1 --- /dev/null +++ b/docs/reference/cli/schema/command.md @@ -0,0 +1,101 @@ +# dsc schema + +## Synopsis + +Gets the JSON schema for a DSC type. + +## Syntax + +```sh +dsc [Options] --type +``` + +## Description + +The `schema` command returns the JSON schema for a specific DSC type. These schemas can be used to +validate the return data from the application or to generate compatible type definitions for an +integrating tool. + +The application uses these schemas to validate data internally when it's received or represent the +output for one of the application's commands. + +## Examples + +### Example 1 - Retrieve the schema for the dsc resource get command result + +```sh +dsc schema --type get-result +``` + +```yaml +$schema: http://json-schema.org/draft-07/schema# +title: GetResult +type: object +required: +- actualState +properties: + actualState: + description: The state of the resource as it was returned by the Get method. +additionalProperties: false +``` + +## Options + +### -t, --type + +This option is mandatory for the `schema` command. The value for this option determines which +schema the application returns: + +- `dsc-resource` ([reference documentation][01]) - Represents a DSC Resource as returned from the + `dsc resource list` command. +- `resource-manifest` ([reference documentation][02]) - Validates a command-based DSC Resource's + manifest. If the manifest is invalid, DSC raises an error. +- `get-result` ([reference documentation][03]) - Represents the output from the `dsc resource get` + command. +- `set-result` ([reference documentation][04]) - Represents the output from the `dsc resource set` + command. +- `test-result` ([reference documentation][05]) - Represents the output from the + `dsc resource test` command. +- `configuration` ([reference documentation][06]) - Validates a DSC Configuration document. If the + document is invalid, DSC raises an error. +- `configuration-get-result` ([reference documentation][07]) - Represents the output from the + `dsc config get` command. +- `configuration-set-result` ([reference documentation][08]) - Represents the output from the + `dsc config set` command. +- `configuration-test-result` ([reference documentation][09]) - Represents the output from the + `dsc config test` command. + +```yaml +Type: String +Mandatory: true +Valid Values: + - dsc-resource + - resource-manifest + - get-result + - set-result + - test-result + - configuration + - configuration-get-result + - configuration-set-result + - configuration-test-result +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +[01]: ../schemas/outputs/resource/list.md +[02]: ../schemas/resource/manifest.md +[03]: ../schemas/outputs/resource/get.md +[04]: ../schemas/outputs/resource/set.md +[05]: ../schemas/outputs/resource/test.md +[06]: ../schemas/configuration/document.md +[07]: ../schemas/outputs/config/get.md +[08]: ../schemas/outputs/config/set.md +[09]: ../schemas/outputs/config/test.md