编辑

通过

dsc schema

Synopsis

Gets the JSON schema for a DSC type.

Syntax

dsc schema [Options] --type <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.

Note

Currently, the schemas returned by the dsc schema command and those published to GitHub are not the same. The published schemas more fully describe and validate the data than the schemas emitted by the command. The DSC team is working to canonicalize the schemas returned from the command.

Both the published schemas and those returned from this command correctly validate the data. The schemas returned from this command are less strict than the published schemas. Even though data validates against the schemas returned by this command, DSC might raise errors when processing the data. For example, the returned schema for versions indicates that the valid value is a string - but if you specify a string that isn't a semantic version, DSC raises an error. In that case, the data passed the schema validation but was incorrect.

Until the schemas are canonicalized, consider using the published schemas when indpendently testing your configuration documents and resource manifests with a JSON Schema validation tool.

Examples

Example 1 - Retrieve the schema for the dsc resource get command result

dsc schema --type get-result

$schema: http://json-schema.org/draft-07/schema#
title: GetResult
anyOf:
- $ref: '#/definitions/ResourceGetResponse'
- type: array
  items:
    $ref: '#/definitions/ResourceGetResult'
definitions:
  ResourceGetResponse:
    type: object
    required:
    - actualState
    properties:
      actualState:
        description: The state of the resource as it was returned by the Get method.
    additionalProperties: false
  ResourceGetResult:
    type: object
    required:
    - name
    - result
    - type
    properties:
      metadata:
        anyOf:
        - $ref: '#/definitions/Metadata'
        - type: 'null'
      name:
        type: string
      type:
        type: string
      result:
        $ref: '#/definitions/GetResult'
    additionalProperties: false
  Metadata:
    type: object
    properties:
      Microsoft.DSC:
        anyOf:
        - $ref: '#/definitions/MicrosoftDscMetadata'
        - type: 'null'
  MicrosoftDscMetadata:
    type: object
    properties:
      version:
        description: Version of DSC
        type:
        - string
        - 'null'
      operation:
        description: The operation being performed
        anyOf:
        - $ref: '#/definitions/Operation'
        - type: 'null'
      executionType:
        description: The type of execution
        anyOf:
        - $ref: '#/definitions/ExecutionKind'
        - type: 'null'
      startDatetime:
        description: The start time of the configuration operation
        type:
        - string
        - 'null'
      endDatetime:
        description: The end time of the configuration operation
        type:
        - string
        - 'null'
      duration:
        description: The duration of the configuration operation
        type:
        - string
        - 'null'
      securityContext:
        description: The security context of the configuration operation, can be specified to be required
        anyOf:
        - $ref: '#/definitions/SecurityContextKind'
        - type: 'null'
      context:
        description: Identifies if the operation is part of a configuration
        anyOf:
        - $ref: '#/definitions/ContextKind'
        - type: 'null'
  Operation:
    type: string
    enum:
    - Get
    - Set
    - Test
    - Export
  ExecutionKind:
    type: string
    enum:
    - Actual
    - WhatIf
  SecurityContextKind:
    type: string
    enum:
    - Current
    - Elevated
    - Restricted
  ContextKind:
    type: string
    enum:
    - Configuration
    - Resource
  GetResult:
    anyOf:
    - $ref: '#/definitions/ResourceGetResponse'
    - type: array
      items:
        $ref: '#/definitions/ResourceGetResult'

Options

-t, --type

This option is mandatory for the schema command. The value for this option determines which schema the application returns:

  • configuration (reference documentation) - Validates a DSC Configuration document. If the document is invalid, DSC raises an error.
  • dsc-resource (reference documentation) - Represents a DSC Resource as returned from the dsc resource list command.
  • resource-manifest (reference documentation) - Validates a command resource's manifest. If the manifest is invalid, DSC raises an error.
  • include - represents the instance schema for the built-in Microsoft.DSC/Include importer resource.
  • configuration-get-result (reference documentation) - Represents the output from the dsc config get command.
  • configuration-set-result (reference documentation) - Represents the output from the dsc config set command.
  • configuration-test-result (reference documentation) - Represents the output from the dsc config test command.
  • get-result (reference documentation) - Represents the output from the dsc resource get command.
  • resolve-result - Represents the resolved form of the configuration document an importer resource emits.
  • set-result (reference documentation) - Represents the output from the dsc resource set command.
  • test-result (reference documentation) - Represents the output from the dsc resource test command.
Type:        string
Mandatory:   true
ValidValues: [
               configuration
               dsc-resource
               resource-manifest
               include
               configuration-get-result
               configuration-set-result
               configuration-test-result
               get-result
               resolve-result
               set-result
               test-result
             ]
LongSyntax  : --type <TYPE>
ShortSyntax : -t <TYPE>

-o, --output-format

The --output-format option controls which format DSC uses for the data the command returns. The available formats are:

  • json to emit the data as a JSON Line.
  • pretty-json to emit the data as JSON with newlines, indentation, and spaces for readability.
  • yaml to emit the data as YAML.

The default output format depends on whether DSC detects that the output is being redirected or captured as a variable:

  • If the command isn't being redirected or captured, DSC displays the output as the yaml format in the console.
  • If the command output is redirected or captured, DSC emits the data as the json format to stdout.

When you use this option, DSC uses the specified format regardless of whether the command is being redirected or captured.

When the command isn't redirected or captured, the output in the console is formatted for improved readability. When the command isn't redirected or captured, the output include terminal sequences for formatting.

Type        : string
Mandatory   : false
ValidValues : [json, pretty-json, yaml]
LongSyntax  : --output-format <OUTPUT_FORMAT>
ShortSyntax : -o <OUTPUT_FORMAT>

-h, --help

Displays the help for the current command or subcommand. When you specify this option, the application ignores all other options and arguments.

Type        : boolean
Mandatory   : false
LongSyntax  : --help
ShortSyntax : -h

Output

This command returns formatted data representing a JSON Schema specified by the --type option.

For more information about the formatting of the output data, see the --output-format option.