Поделиться через

Справочник по схеме свойств набора манифестов ресурсов DSC

Краткий обзор

Определяет, как применить состояние для экземпляра ресурса DSC.

Метаданные

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.set.json
Type:          object

Описание

Чтобы управлять экземпляром с помощью DSC, ресурс DSC должен определить set свойство в своем манифесте. Это свойство определяет, как DSC может принудительно применять текущее состояние экземпляра.

Если это свойство не определено, DSC может только получить текущее состояние экземпляров и проверить, находятся ли они в нужном состоянии. DSC не может принудительно применить требуемое состояние для ресурса.

DSC отправляет данные в команду тремя способами:

  1. Если input имеет значение stdin, DSC отправляет данные в виде строки, представляющей данные в виде сжатого объекта JSON без пробелов или новых линий между свойствами объекта.
  2. Если input имеет значение env, DSC отправляет данные в виде переменных среды. Он создает переменную среды для каждого свойства объекта входных данных, используя имя и значение свойства .
  3. args Если массив содержит определение входного аргумента JSON, DSC отправляет данные в виде строки, представляющей данные в виде сжатого объекта JSON в указанный аргумент.

Если вы не определяете input свойство и не определяете входной аргумент JSON, DSC не сможет передать входной JSON в ресурс. Для команды можно определить только один входной аргумент JSON.

Необходимо определить input свойство, один входной аргумент JSON в массиве args свойств или оба.

Примеры

Пример 1. Полное определение

Этот пример из Microsoft.Windows/Registry ресурса DSC.

"set": {
  "executable": "registry",
  "args": [
    "config",
    "set"
  ],
  "input":            "stdin",
  "implementsPretest": true,
  "return":           "state"
}

Он определяет executable как registry, а не registry.exeкак . Расширение не требуется, если операционная система распознает команду как исполняемый файл.

Манифест определяет два аргумента: config и set. Значение свойства указывает, что set команда ожидает входные данные в виде большого input двоичного объекта JSON от stdin.

В сочетании со значением executableDSC вызывает метод set для этого ресурса, выполнив следующую команду:

{ ... } | registry config set

Так как манифест определяет implementsPretest как true, DSC не будет вызывать test метод для ресурса перед вызовом set. Этот параметр указывает, что сам ресурс проверяет экземпляры перед применением требуемого состояния.

Манифест определяет return как state, указывая, что он возвращает окончательное состояние ресурса только после set выполнения метода. DSC сравнивает требуемое состояние с возвращаемыми данными этого ресурса, чтобы определить, к каким свойствам ресурса set применяется метод , если таковые есть.

Обязательные свойства

Определение set должно включать следующие свойства:

Свойства

исполняемый файл

Свойство executable определяет имя выполняемой команды. Значение должно быть именем команды, обнаруживаемой в системной PATH переменной среды, или полным путем к команде. Расширение файла требуется только в том случае, если команда не распознается операционной системой как исполняемый файл.

Type:     string
Required: true

args

Свойство args определяет список аргументов для передачи команде. Аргументами может быть любое количество строк. Если вы хотите передать объект JSON, представляющий контейнер свойств для ресурса, в аргумент, можно определить один элемент в массиве как [объект JSON], указав имя аргумента со jsonInputArg строковым свойством и является ли аргумент обязательным для команды с mandatory логическим свойством.

Type:     array
Required: false
Default:  []
Type:     [string, object(JSON Input Argument)]

Строковые аргументы

Любой элемент в массиве аргументов может быть строкой, представляющей статический аргумент для передачи команде, например config или --format.

Type: string

Входной аргумент JSON

Определяет аргумент для команды, которая принимает входной объект JSON в виде строки. DSC передает входные данные JSON в именованный аргумент, если они доступны. Входной аргумент JSON определяется как объект JSON со следующими свойствами:

  • jsonInputArg (обязательный) — аргумент для передачи данных JSON для команды, например --input.
  • mandatory (необязательно) — указывает, следует ли DSC всегда передавать аргумент команде, даже если для команды нет входных данных JSON. В этом случае DSC передает пустую строку входным аргументам JSON.

Для каждого массива аргументов можно определить только один входной аргумент JSON.

Если вы определяете входной аргумент JSON и input тип команды, DSC отправляет данные JSON обоими способами:

  • Если вы определяете input как env и входной аргумент JSON, DSC задает переменную среды для каждого свойства во входных данных JSON и передает входной объект JSON в виде строки в определенный аргумент.
  • Если вы определяете input как stdin и входной аргумент JSON, DSC передает входные данные JSON через stdin и как строку в определенный аргумент.
  • Если вы определяете входной аргумент JSON без определения input свойства, DSC передает входные данные JSON только в виде строки в определенный аргумент.

Если вы не определяете input свойство и не определяете входной аргумент JSON, DSC не сможет передать входной JSON в ресурс. Это делает манифест недопустимым. Необходимо определить input свойство, входной аргумент JSON в массиве args свойств или и то, и другое.

Type:                object
RequiredProperties: [jsonInputArg]

input

Свойство input определяет способ передачи входных данных в ресурс. Если это свойство не определено и определение не определяет входной аргумент JSON, DSC не отправляет входные данные ресурсу при вызове set операции.

Значение этого свойства должно быть одной из следующих строк:

  • env — указывает, что ресурс ожидает, что свойства экземпляра будут указаны в качестве переменных среды с одинаковыми именами и регистром.

    Этот параметр поддерживает только следующие типы данных для свойств экземпляра:

    • boolean
    • integer
    • number
    • string
    • arrayзначений integer
    • arrayзначений number
    • arrayзначений string

    Для значений, не являющихся массивами, DSC присваивает переменной среды указанное значение "как есть". Если тип данных является массивом значений, DSC задает переменную среды в виде строки с разделителями-запятыми. Например, свойство foo со значением [1, 2, 3] сохраняется в переменной foo среды как "1,2,3".

    Если ресурс должен поддерживать сложные свойства со значением object или многотипными массивами, задайте для него значение stdin .

  • stdin — указывает, что ресурс ожидает большой двоичный объект JSON, представляющий экземпляр из stdin. JSON должен соответствовать схеме экземпляра для ресурса.

Type:        string
Required:    false
ValidValues: [env, stdin]

implementsPretest

Свойство implementsPretest определяет, проверяет ли ресурс, находится ли экземпляр в нужном состоянии внутренне перед применением требуемого состояния. Присвойте этому свойству значение , true когда ресурс проверяет экземпляр в рамках set операции. Присвойте этому свойству значение , false если это не так.

Если это значение равно false, это означает, что пользователи должны всегда вызывать dsc resource test экземпляр перед вызовом dsc resource set команды для ресурса.

Значение по умолчанию — false.

Type:     boolean
Required: false
Default:  false

handlesExist

Свойство handlesExist определяет, имеет ли ресурс встроенную обработку свойства _exist в set операции. Значение по умолчанию — false.

Присвойте этому свойству значение , true если ресурс соответствует следующим требованиям реализации:

  • Схема экземпляра ресурса определяет _exist свойство как допустимое свойство экземпляра.
  • Команда ресурса обрабатывает создание, обновление и удаление экземпляра set на основе текущего состояния экземпляра и значения _exist свойства в нужном состоянии.

Если этому свойству trueприсвоено значение , ресурс указывает, что у него есть возможностьSetHandlesExist. При обработке SetHandlesExist ресурсов с возможностью в конфигурации DSC вызывает set операцию для ресурса, когда экземпляр определяет _exist как false. Без этой возможности ресурс должен определить операцию удаления для поддержки удаления экземпляров ресурса.

Если манифест ресурса не определяет это свойство как true и не определяет delete операцию, DSC вызывает ошибку при обнаружении экземпляра ресурса с _exist значением false.

return

Свойство return определяет, как DSC должен обрабатывать выходные данные для этого метода. Значение этого свойства должно быть одной из следующих строк:

  • state — указывает, что ресурс возвращает только окончательное состояние экземпляра после операции задания в виде большого двоичного объекта JSON.
  • stateAndDiff — указывает, что ресурс возвращает конечное состояние экземпляра и массив имен свойств, измененных ресурсом.

Значение по умолчанию — state.

Type:        string
Required:    false
Default:     state
ValidValues: [state, stateAndDiff]