다음을 통해 공유

명령 기반 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 속성은 리소스의 정규화된 형식 이름을 나타냅니다. 구성 문서에서 리소스를 지정하고 dsc resource * 명령을 사용할 때 --resource 플래그 값으로 사용하는 데 사용됩니다. 리소스 종류 이름에 대한 자세한 내용은 DSC Resource 정규화된 형식 이름 스키마 참조참조하세요.

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는 Resource, Group및 Adapter세 가지 종류의 명령 기반 DSC 리소스를 지원합니다.

리소스 매니페스트에 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 리소스 get 명령 및 -모든 옵션을 사용하여 리소스의 모든 인스턴스에 대한 현재 상태를 반환하도록 리소스를 지정합니다.

이 속성의 값은 개체여야 합니다. 호출할 명령의 이름을 정의하는 개체의 executable 속성은 필수입니다. args 속성은 선택 사항입니다. 자세한 내용은 DSC 리소스 매니페스트 내보내기 속성 스키마 참조참조하세요.

Type:     object
Required: true

가져오기

get 속성은 리소스를 호출하여 인스턴스의 현재 상태를 가져오는 방법을 정의합니다. 이 속성은 모든 리소스에 필수입니다.

이 속성의 값은 개체여야 합니다. 호출할 명령의 이름을 정의하는 개체의 executable 속성은 필수입니다. args 및 input 속성은 선택 사항입니다. 자세한 내용은 DSC 리소스 매니페스트 가져오기 속성 스키마 참조참조하세요.

Type:     object
Required: true

집합

set 속성은 리소스를 호출하여 인스턴스의 원하는 상태를 설정하는 방법을 정의합니다. 또한 이 메서드에 대한 리소스의 출력을 처리하는 방법도 정의합니다. 이 속성이 정의되지 않은 경우 DSC는 리소스의 인스턴스를 관리할 수 없습니다. 현재 상태만 가져와 인스턴스가 원하는 상태인지 테스트할 수 있습니다.

이 속성의 값은 개체여야 합니다. 호출할 명령의 이름을 정의하는 executable 속성은 필수입니다. args input, implementsPretest및 returns 속성은 선택 사항입니다. 자세한 내용은 DSC 리소스 매니페스트 집합 속성 스키마 참조참조하세요.

Type:     object
Required: false

whatIf

DSC가 DSC 리소스를 호출하여 set 명령이 인스턴스를 수정할지 여부와 방법 및 DSC 리소스에서 출력을 처리하는 방법을 나타내는 방법을 정의합니다. 리소스가 매니페스트에서 이 메서드를 정의하지 않으면 DSC는 리소스에 대한 테스트 작업의 결과를 집합 결과로 변환하여 이 동작을 합성합니다.

이 속성의 값은 개체여야 합니다. 호출할 명령의 이름을 정의하는 executable 속성은 필수입니다. args input, implementsPretest및 returns 속성은 선택 사항입니다. 자세한 내용은 DSC 리소스 매니페스트 whatIf 속성 스키마 참조참조하세요.

테스트

test 속성은 리소스를 호출하여 인스턴스가 원하는 상태인지 여부를 테스트하는 방법을 정의합니다. 또한 이 메서드에 대한 리소스의 출력을 처리하는 방법도 정의합니다. 이 속성이 정의되지 않은 경우 DSC는 DSC 리소스 인스턴스에 대한 기본 가상 테스트를 수행합니다.

이 속성의 값은 개체여야 합니다. 호출할 명령의 이름을 정의하는 개체의 executable 속성은 필수입니다. args input및 returns 속성은 선택 사항입니다. 자세한 내용은 DSC 리소스 매니페스트 테스트 속성 스키마 참조참조하세요.

Type:     object
Required: false

확인

validate 속성은 DSC 그룹 리소스를 호출하여 해당 인스턴스의 유효성을 검사하는 방법을 정의합니다. 이 속성은 DSC 그룹 리소스에 필수입니다. DSC는 다른 모든 리소스에 대해 이 속성을 무시합니다.

이 속성의 값은 개체여야 합니다. 호출할 명령의 이름을 정의하는 개체의 executable 속성은 필수입니다. args 속성은 선택 사항입니다. 자세한 내용은 DSC 리소스 매니페스트 유효성 검사 속성 스키마 참조참조하세요.

Type:     object
Required: false

공급자

지정된 경우 provider 속성은 리소스를 DSC 리소스 공급자로 정의합니다.

이 속성의 값은 개체여야 합니다. 개체의 list 및 config 속성은 필수입니다. list 속성은 공급자를 호출하여 공급자가 관리할 수 있는 리소스를 반환하는 방법을 정의합니다. config 속성은 공급자가 입력을 기대하는 방법을 정의합니다. 자세한 내용은 DSC 리소스 매니페스트 공급자 속성 스키마 참조참조하세요.

exitCodes

exitCodes 속성은 리소스 및 해당 의미에 대한 유효한 종료 코드 집합을 정의합니다. 다음 위치에서 키-값 쌍 집합으로 이 속성을 정의합니다.

  • 키는 리소스의 알려진 종료 코드에 매핑되는 부호 있는 정수가 포함된 문자열입니다. 종료 코드는 리터럴 부호 있는 정수여야 합니다. 종료 코드에는 대체 형식을 사용할 수 없습니다. 예를 들어 "액세스 거부됨"에 대해 0x80070005 16진수 값 대신 종료 코드를 -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