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

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

  • Статья

Синопсис

Файл данных, определяющий ресурс DSC на основе команд.

Метаданные

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

Описание

Каждый ресурс DSC на основе команд должен иметь манифест. Файл манифеста должен:

  1. Быть обнаруженным в переменной среды PATH.
  2. Форматируется как JSON или YAML.
  3. Следуйте соглашению об именовании <name>.dsc.resource.<extension>. Допустимые расширения включают json, ymlи yaml.
  4. Будьте допустимы для схемы, описанной в этом документе.

Остальная часть этого документа описывает схему манифеста.

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

Манифест должен содержать следующие свойства:

Свойства

$schema

Свойство $schema указывает канонический URI этой схемы, на который манифест проверяется. Это свойство является обязательным. DSC использует это значение для проверки манифеста в правильной схеме JSON.

Для каждой версии схемы существует три допустимых URL-адреса:

  • .../resource/manifest.json

    URL-адрес канонической неувязанной схемы. Когда он используется для проверки, проверяющий клиент должен получить эту схему и каждую схему, на которую она ссылается.

  • .../bundled/resource/manifest.json

    URL-адрес в пакетной схеме. При использовании для проверки проверяющий клиент должен получить только эту схему.

    Эта схема использует модель объединение, представленную для схемы JSON 2020-12. Хотя DSC по-прежнему может проверить документ при использовании этой схемы, другие средства могут ошибться или вести себя непредвиденными способами.

  • .../bundled/resource/manifest.vscode.json

    URL-адрес расширенной схемы разработки. Эта схема гораздо больше, чем другие схемы, так как она включает дополнительные определения, которые предоставляют контекстную справку и фрагменты, которые другие не включают.

    Эта схема использует ключевые слова, которые распознаются только VS Code. Хотя DSC по-прежнему может проверить документ при использовании этой схемы, другие средства могут ошибться или вести себя непредвиденными способами.

Type:        string
Required:    true
Format:      URI
ValidValues: [
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
             ]

тип

Свойство type представляет полное имя типа ресурса. Он используется для указания ресурса в документах конфигурации и в качестве значения флага --resource при использовании команд dsc resource *. Дополнительные сведения о именах типов ресурсов см. в справочнике по схеме имен полного типа DSC.

Type:     string
Required: true
Pattern:  ^\w+(\.\w+){0,2}\/\w+$

Версия

Свойство version должно быть текущей версией ресурса в качестве допустимой семантической версии (semver). Версия применяется к ресурсу, а не программному обеспечению, который он управляет.

Type:     string
Required: true
Pattern:  ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

описание

Свойство description определяет синопсис для назначения ресурса. Значение этого свойства должно быть короткой строкой.

Type:     string
Required: false

добрый

Свойство kind определяет, как DSC должен обрабатывать ресурс. DSC поддерживает три типа ресурсов DSC на основе команд: Resource, Groupи Adapter.

Если kind не определен в манифесте ресурса, DSC определяет значение свойства. Если свойство adapter определено в манифесте ресурса, DSC определяет значение kind как Adapter. Если свойство adapter не определено, DSC выводит значение kind как Resource. DSC не может определить, является ли манифест ресурсом группы.

При определении ресурса группы всегда явно определять свойство kind манифеста как Group.

Дополнительные сведения см. в справочнике по схеме типа ресурсов DSC.

Type:        string
Required:    false
ValidValues: [Resource, Adapter, Group]

Теги

Свойство tags определяет список терминов, доступных для поиска для ресурса. Значение этого свойства должно быть массивом строк. Каждый тег должен содержать только буквенно-цифровые символы и символы подчеркивания. Другие символы не разрешены. Каждый тег должен быть уникальным.

Type:              array
Required:          false
ItemsMustBeUnique: true
ItemsType:         string
ItemsPattern:      ^\w+$

экспорт

Свойство export определяет, как вызвать ресурс для получения текущего состояния каждого экземпляра. При определении этого свойства пользователи могут:

  • Укажите экземпляр ресурса в входной конфигурации для команды экспорта конфигурации dsc dsc для создания документа конфигурации, который можно использовать.
  • Укажите ресурс с помощью команды экспорта ресурсов dsc dsc, чтобы создать документ конфигурации, определяющий каждый экземпляр ресурса.
  • Укажите ресурс с помощью команды ресурса dsc и параметра -all, чтобы вернуть текущее состояние для каждого экземпляра ресурса.

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

Type:     object
Required: true

Получить

Свойство get определяет, как вызвать ресурс для получения текущего состояния экземпляра. Это свойство является обязательным для всех ресурсов.

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

Type:     object
Required: true

набор

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

Значение этого свойства должно быть объектом. Свойство executable, определяющее имя вызываемой команды, является обязательным. Свойства argsinput, implementsPretestи returns являются необязательными. Дополнительные сведения см. в справочнике по схеме свойств набора манифестов ресурсов DSC.

Type:     object
Required: false

whatIf

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

Значение этого свойства должно быть объектом. Свойство executable, определяющее имя вызываемой команды, является обязательным. Свойства argsinput, implementsPretestи returns являются необязательными. Дополнительные сведения см. в разделе манифеста ресурсов DSC, справочник по схеме свойств.

тест

Свойство test определяет, как вызвать ресурс для проверки того, находится ли экземпляр в требуемом состоянии. Он также определяет, как обрабатывать выходные данные из ресурса для этого метода. Если это свойство не определено, DSC выполняет базовый искусственный тест для экземпляров ресурса DSC.

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

Type:     object
Required: false

обосновывать

Свойство validate определяет, как вызвать ресурс группы DSC для проверки его экземпляров. Это свойство является обязательным для ресурсов группы DSC. DSC игнорирует это свойство для всех остальных ресурсов.

Значение этого свойства должно быть объектом. Свойство executable объекта, определяющее имя вызываемой команды, является обязательным. Свойство args является необязательным. Дополнительные сведения см. в справочнике по схеме свойств dSC Resource manifest.

Type:     object
Required: false

поставщик

При указании свойство provider определяет ресурс как поставщик ресурсов DSC.

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

exitCodes

Свойство exitCodes определяет набор допустимых кодов выхода для ресурса и их значения. Определите это свойство как набор пар "ключ-значение", где:

  • Ключ — это строка, содержащая целое число со знаком, которое сопоставляется с известным кодом выхода для ресурса. Код выхода должен быть целым числом со знаком. Вы не можете использовать альтернативные форматы для кода выхода. Например, вместо шестнадцатеричного значения 0x80070005 для параметра "Отказано в доступе", укажите код выхода как -2147024891.
  • Это строка, описывающая семантический смысл этого кода выхода для человеческого читателя.

DSC интерпретирует код выхода 0 как успешную операцию и любой другой код выхода как ошибку.

Кончик

Если вы создаете манифест ресурса в yaml, обязательно заключите код выхода в одинарные кавычки, чтобы убедиться, что файл YAML можно проанализировать правильно. Например:

exitCodes:
  '0': Success
  '1': Invalid parameter
  '2': Invalid input
  '3': Registry error
  '4': JSON serialization failed

Type:                object
Required:            false
PropertyNamePattern: ^-?[0-9]+#
PropertyValueType:   string

схема

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

  • command. При указании свойства command DSC вызывает определенную команду, чтобы получить схему JSON.
  • embedded. При указании свойства embedded DSC использует определенное значение в качестве схемы JSON.

Дополнительные сведения см. в справочнике по свойству схемы манифеста ресурсов DSC.

Type:     object
Required: true