선언된 구성 확장성

아티클
10/15/2024
적용 대상:

✅ Windows 11, ✅ Windows 10

Windows 선언된 구성(WinDC) 등록은 네이티브 WMI 공급자를 통해 확장성을 제공합니다. 이 기능은 MI(관리 인프라) 인터페이스를 구현하는 WMI(Windows Management Instrumentation) 공급자를 사용하여 및 인터페이스를 인스턴스화합니다. 인터페이스는 GetTargetResource, TestTargetResource 및 SetTargetResource 메서드를 구현해야 하며 여러 문자열 속성을 구현할 수 있습니다.

참고

문자열 속성만 현재 확장성 공급자에서 지원됩니다.

[static, Description ("Get resource state based on input configuration file." )]
uint32 GetTargetResource(
    [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that is to be applied.")]
    string InputResource,
    [in, Description ("Flags passed to the provider. Reserved for future use." )]
    uint32 Flags,
    [out, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("The current state of the specified configuration resources." )]
    string OutputResource
);

[static, Description ("Test resource state based on input configuration file." )]
uint32 TestTargetResource(
    [in, EmbeddedInstance("MSFT_FileDirectoryConfiguration"), Description ("Configuration document to be applied." )]
    string InputResource,
    [in, Description ("Flags passed to the provider. reserved for future use." )]
    uint32 Flags,
    [out, Description ("True if identical. False otherwise." )]
    boolean Result,
    [out, Description ("Context information the provider can use to optimize the set. This is optional." )]
    uint64 ProviderContext
);

[static, Description ("Set resource state based on input configuration file." )]
uint32 SetTargetResource(
    [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"),
    Description ("Configuration document to be applied." )]
    string InputResource,
    [in, Description ("Context information the provider can use to optimize the set from SetTargetResource. This is optional." )]
    uint64 ProviderContext,
    [in, Description ("Flags passed to the provider. reserved for future use." )]
    uint32 Flags
);

원하는 상태 구성 리소스 작성

네이티브 WMI 공급자를 만들려면 MI 공급자를 구현하는 방법에 설명된 단계를 수행합니다. 이러한 단계에는 도구를 사용하여 Convert-MofToProvider.exe MI 인터페이스에 대한 소스 코드를 생성하여 DLL을 생성하고 배치를 준비하는 방법이 포함됩니다.

매개 변수 및 메서드를 포함하여 원하는 상태 구성 리소스에 대한 스키마를 정의하는 MOF(관리 개체 형식) 파일을 만듭니다. 이 파일에는 리소스에 필요한 매개 변수가 포함되어 있습니다.
필요한 파일과 함께 스키마 MOF 파일을 공급자 도구 디렉터리에 복사합니다(예: ProviderGenerationTool).
필요한 파일을 편집하고 올바른 파일 이름과 클래스 이름을 포함합니다.
공급자 생성기 도구를 호출하여 공급자의 프로젝트 파일을 생성합니다.
생성된 파일을 공급자의 프로젝트 폴더에 복사합니다.
개발 프로세스를 시작합니다.

MI 공급자 예제

이 예제에서는 라는 MSFT_FileDirectoryConfiguration샘플 네이티브 리소스를 구현하는 방법을 보여 주는 각 단계에 대한 자세한 내용을 제공합니다.

1단계: 리소스 스키마 MOF 파일 만들기

네이티브 리소스에 대한 MSFT_FileDirectoryConfiguration 초기 소스 코드를 생성하는 데 사용되는 샘플 스키마 MOF 파일을 만듭니다. 라는 MSFT_FileDirectoryConfiguration프로젝트 디렉터리에 배치합니다.

#pragma include ("cim_schema_2.26.0.mof")
#pragma include ("OMI_BaseResource.mof")
#pragma include ("MSFT_Credential.mof")

[ClassVersion("1.0.0"), Description("The configuration provider for files and directories.")]
class MSFT_FileDirectoryConfiguration : OMI_BaseResource
{
    [Key, Description("File name and path on target node to copy or create.")]
    string DestinationPath;

    [Write, Description("The name and path of the file to copy from.")]
    string SourcePath;

    [Write, Description("Contains a string that represents the contents of the file. To create an empty file, the string must be empty. The contents will be written and compared using UTF-8 character encoding.")]
    string Contents;

    [static, Description ("Get resource states based on input configuration file." )]
    uint32 GetTargetResource(
        [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that is to be applied." )]
        string InputResource,

        [in,Description ("Flags passed to the providers. Reserved for future use." )]
        uint32 Flags,

        [out, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("The current state of the specified configuration resources." )]
        string OutputResource
    );

    [static, Description ("Test resource states based on input configuration file." )]
    uint32 TestTargetResource(
        [in, EmbeddedInstance("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that to be applied." )]
        string InputResource,

        [in, Description ("Flags passed to the providers. reserved for future use." )]
        uint32 Flags,

        [out, Description ("True if identical. False otherwise." )]
        boolean Result,

        [out, Description ("Context information that the provider can use to optimize the set, This is optional." )]
        uint64 ProviderContext
    );

    [static, Description ("Set resource states based on input configuration file." )]
    uint32 SetTargetResource(
        [in, EmbeddedInstance ("MSFT_FileDirectoryConfiguration"), Description ("Configuration document that to be applied." )]
        string InputResource,

        [in, Description ("Context information that the provider can use to optimize the set from TestTargetResource, This is optional." )]
        uint64 ProviderContext,

        [in, Description ("Flags passed to the providers. reserved for future use." )]
        uint32 Flags
    );
};

참고

클래스 이름 및 DLL 파일 이름은 파일에 정의된 Provider.DEF 것과 동일해야 합니다.
속성의 형식 한정 [Key] 자는 리소스 instance 고유하게 식별한다는 것을 나타냅니다. 하나 이상의 [Key] 속성이 필요합니다.
한정자는 [Required] 속성이 필요하다는 것을 나타냅니다. 즉, 이 리소스를 사용하는 모든 구성 스크립트에서 값을 지정해야 합니다.
한정자는 [write] 구성 스크립트에서 사용자 지정 리소스를 사용할 때 속성이 선택 사항임을 나타냅니다. 한정자는 [read] 속성을 구성으로 설정할 수 없으며 보고 목적으로만 사용됨을 나타냅니다.
[Values] 한정자는 속성에 할당할 수 있는 값을 제한합니다. 에서 허용되는 값 목록을 정의합니다 [ValueMap]. 자세한 내용은 ValueMap 및 값 한정자를 참조하세요.

모든 새 MOF 파일에는 파일 맨 위에 다음 줄이 포함되어야 합니다.

#pragma include ("cim_schema_2.26.0.mof")
#pragma include ("OMI_BaseResource.mof")
#pragma include ("MSFT_Credential.mof")

메서드 이름과 해당 매개 변수는 모든 리소스에 대해 동일해야 합니다. EmbeddedInstance 값에서 원하는 공급자의 클래스 이름으로 변경 MSFT_FileDirectoryConfiguration 합니다. MOF 파일당 하나의 공급자만 있어야 합니다.

2단계: 스키마 MOF 파일 복사

다음 필수 파일 및 폴더를 1단계에서 만든 프로젝트 디렉터리에 복사합니다.

CIM-2.26.0
codegen.cmd
Convert-MofToProvider.exe
MSFT_Credential.mof
MSFT_DSCResource.mof
OMI_BaseResource.mof
OMI_Errors.mof
Provider.DEF
wmicodegen.dll

필요한 파일을 가져오는 방법에 대한 자세한 내용은 MI 공급자를 구현하는 방법을 참조하세요.

3단계: 필요한 파일 편집

프로젝트 디렉터리에서 다음 파일을 수정합니다.

MSFT_FileDirectoryConfiguration.mof: 1단계에서 이 파일을 만들었습니다.
Provider.DEF: 이 파일에는 DLL 이름(예: MSFT_FileDirectoryConfiguration.dll)이 포함되어 있습니다.

codegen.cmd: 이 파일에는 를 호출하는 명령이 포함되어 있습니다 convert-moftoprovider.exe.

"convert-moftoprovider.exe" ^
   -MofFile MSFT_FileDirectoryConfiguration.mof ^
            MSFT_DSCResource.mof ^
            OMI_Errors.mof ^
   -ClassList MSFT_FileDirectoryConfiguration ^
   -IncludePath CIM-2.26.0 ^
   -ExtraClass OMI_Error ^
               MSFT_DSCResource ^
   -OutPath temp

4단계: 공급자 생성기 도구 실행

명령을 실행하는 를 실행 codegen.cmd합니다 convert-moftoprovider.exe . 또는 명령을 직접 실행할 수 있습니다.

5단계: 생성된 원본 파일 복사

3단계의 명령은 매개 변수를 -OutPath 지정합니다. 이 예제에서는 라는 temp폴더입니다. 4단계에서 도구를 실행하면 이 폴더에 새 파일이 만들어집니다. 이 temp 폴더에서 생성된 파일을 프로젝트 디렉터리로 복사합니다. 1단계에서 프로젝트 디렉터리를 만들었는데, 이 예제에서는 입니다 MSFT_FileDirectoryConfiguration.

참고

스키마 MOF 파일을 업데이트할 때마다 스크립트를 codegen.cmd 실행하여 원본 파일을 다시 생성합니다. 생성기 도구를 다시 실행하면 기존 원본 파일이 덮어씁니다. 이 동작을 방지하기 위해 이 예제에서는 임시 폴더를 사용합니다. 기본 구현을 가장 최근에 자동 생성된 원본 파일과 병합해야 하므로 스키마 MOF 파일에 대한 업데이트를 최소화합니다.

리소스 정보 `MSFT_FileDirectoryConfiguration`

공급자 생성기 도구를 실행한 후 다음과 같은 여러 원본 및 헤더 파일을 만듭니다.

MSFT_FileDirectoryConfiguration.c
MSFT_FileDirectoryConfiguration.h
module.c
schema.c
WMIAdapter.c

이 목록에서 및 MSFT_FileDirectoryConfiguration.h만 수정 MSFT_FileDirectoryConfiguration.c 하면 됩니다. 원본 파일의 확장을 에서 로 .c.cpp변경할 수도 있습니다. 이 리소스의 경우입니다. 이 리소스에 대한 비즈니스 논리는 및 MSFT_FileDirectoryConfigurationImp.h에서 MSFT_FileDirectoryConfigurationImp.cpp 구현됩니다. 이러한 새 파일은 공급자 생성기 도구를 실행한 후 프로젝트 디렉터리에 추가 MSFT_FileDirectoryConfiguration 됩니다.

네이티브 원하는 상태 구성 리소스의 경우 에서 MSFT_FileDirectoryConfiguration.cpp세 개의 자동 생성된 함수를 구현해야 합니다.

MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource
MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource

이러한 세 가지 함수에서 Get 시나리오에만 MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource 필요합니다. MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource 및 MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource 는 수정이 필요할 때 사용됩니다.

에 네이티브 원하는 상태 구성 리소스에 MSFT_FileDirectoryConfiguration.cpp 대한 구현이 필요하지 않은 몇 가지 다른 자동 생성된 함수가 있습니다. 다음 함수를 수정할 필요가 없습니다.

MSFT_FileDirectoryConfiguration_Load
MSFT_FileDirectoryConfiguration_Unload
MSFT_FileDirectoryConfiguration_EnumerateInstances
MSFT_FileDirectoryConfiguration_GetInstance
MSFT_FileDirectoryConfiguration_CreateInstance
MSFT_FileDirectoryConfiguration_ModifyInstance
MSFT_FileDirectoryConfiguration_DeleteInstance

약 `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

함수는 MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource 다음 단계를 수행하여 작업을 완료합니다.

입력 리소스의 유효성을 검사합니다.
키와 필수 매개 변수가 있는지 확인합니다.
Get 메서드의 출력으로 사용되는 리소스 instance 만듭니다. 이 instance 에서 MI_Instance파생된 형식MSFT_FileDirectoryConfiguration입니다.
수정된 리소스 instance 출력 리소스 instance 만들고 다음 함수를 호출하여 MI 클라이언트로 반환합니다.
- MSFT_FileDirectoryConfiguration_GetTargetResource_Construct
- MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource
- MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn
- MSFT_FileDirectoryConfiguration_GetTargetResource_Post
- MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct
리소스를 정리합니다(예: 무료 할당된 메모리).

WinDC 문서

중요

시나리오 설정의 대상은 확장성을 위해 디바이스 전체일 수 있습니다. 및 WinDC 컨텍스트에 <LocURI> 정의된 CSP scope 이어야 Device합니다.

DeclaredConfiguration CSP의 Document 리프 노드 값은 요청을 설명하는 XML 문서입니다. 다음은 확장성을 위해 지정된 구성 데이터가 있는 샘플 WinDC 문서입니다.

<DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" osdefinedscenario="MSFTExtensibilityMIProviderConfig">
    <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
        <Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
        <Value name="Contents">TestFileContent1</Value>
    </DSC>
</DeclaredConfiguration>

지원되는 값 osdefinedscenario 만 사용할 수 있습니다. 지원되지 않는 값은 과 유사한 오류 메시지를 생성합니다 Invalid scenario name.

osdefinedscenario	설명
MSFTExtensibilityMIProviderConfig	MI 공급자 설정을 구성하는 데 사용됩니다.
MSFTExtensibilityMIProviderInventory	MI 공급자 설정 값을 검색하는 데 사용됩니다.

동일한 태그와 MSFTExtensibilityMIProviderInventory 특성이 필요한 및 시나리오.MSFTExtensibilityMIProviderConfig

XML 태그는 <DSC> 디바이스에 적용하거나 MI 공급자가 쿼리할 값과 함께 네임스페이스 및 클래스 이름으로 표현되는 대상 WMI 공급자를 설명합니다.

이 태그에는 다음과 같은 특성이 있습니다.

특성 설명

namespace 대상 MI 공급자 네임스페이스를 지정합니다.

classname 대상 MI 공급자입니다.
XML 태그는 <Key> 필수 매개 변수 이름 및 값을 설명합니다. 구성에 대한 값만 필요합니다. 이름은 특성이고 값은 콘텐츠입니다 <Key> .

이 태그에는 다음과 같은 특성이 있습니다.

특성 설명

name MI 공급자 매개 변수의 이름을 지정합니다.
XML 태그는 <Value> 선택적 매개 변수 이름 및 값을 설명합니다. 구성에 대한 값만 필요합니다. 이름은 특성이고 값은 콘텐츠입니다 <Value> .

이 태그에는 다음과 같은 특성이 있습니다.

특성 설명

name MI 공급자 매개 변수의 이름을 지정합니다.

특성	설명
`namespace`	대상 MI 공급자 네임스페이스를 지정합니다.
`classname`	대상 MI 공급자입니다.

특성	설명
`name`	MI 공급자 매개 변수의 이름을 지정합니다.

특성	설명
`name`	MI 공급자 매개 변수의 이름을 지정합니다.

SyncML 예제

표준 OMA-DM SyncML 구문은 Replace, Add 및 Delete와 같은 DeclaredConfiguration CSP 작업을 지정하는 데 사용됩니다. SyncML 요소의 <Data> 페이로드는 XML로 인코딩되어야 합니다. 이 XML 인코딩의 경우 사용할 수 있는 다양한 온라인 인코더가 있습니다. 페이로드 인코딩을 방지하려면 다음 SyncML 예제와 같이 CDATA 섹션 을 사용할 수 있습니다.

구성 요청

이 예제에서는 시나리오에서 MI 공급자를 사용하여 MSFT_FileDirectoryConfiguration 구성 요청을 보내는 방법을 보여 줍니다 MSFTExtensibilityMIProviderConfig .

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
      <CmdID>14</CmdID>
      <Item>
        <Target>
          <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Target>
        <Data><![CDATA[
            <DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" osdefinedscenario="MSFTExtensibilityMIProviderConfig">
                <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
                    <Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
                    <Value name="Contents">TestFileContent1</Value>
                </DSC>
            </DeclaredConfiguration>
        ]]></Data>
      </Item>
    </Replace>
  </SyncBody>
</SyncML>

인벤토리 요청

이 예제에서는 MSFTExtensibilityMIProviderInventory 시나리오에서 MSFT_FileDirectoryConfiguration MI 공급자를 사용하여 인벤토리 요청을 보내는 방법을 보여 줍니다.

<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
  <SyncBody>
    <Replace>
      <CmdID>15</CmdID>
      <Item>
        <Target>
          <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/12345678-1234-1234-1234-123456789012/Document</LocURI>
        </Target>
        <Data><![CDATA[
            <DeclaredConfiguration schema="1.0" context="Device" id="12345678-1234-1234-1234-123456789012" checksum="1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF" osdefinedscenario="MSFTExtensibilityMIProviderInventory">
                <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
                    <Key name="DestinationPath">c:\data\test\bin\ut_extensibility.tmp</Key>
                </DSC>
            </DeclaredConfiguration>
        ]]></Data>
      </Item>
    </Replace>
  </SyncBody>
</SyncML>

결과 검색

이 예제에서는 구성 또는 인벤토리 요청의 결과를 검색합니다.

요청:

<SyncML xmlns="SYNCML:SYNCML1.1">
    <SyncBody>
    <Get>
        <CmdID>2</CmdID>
        <Item>
        <Meta>
            <Format>chr</Format>
            <Type>text/plain</Type>
        </Meta>
        <Target>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Target>
        </Item>
    </Get>
    <Final />
    </SyncBody>
</SyncML>

응답:

<Status>
    <CmdID>2</CmdID>
    <MsgRef>1</MsgRef>
    <CmdRef>2</CmdRef>
    <Cmd>Get</Cmd>
    <Data>200</Data>
</Status>
<Results>
    <CmdID>3</CmdID>
    <MsgRef>1</MsgRef>
    <CmdRef>2</CmdRef>
    <Item>
        <Source>
            <LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Results/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
        </Source>
        <Data>
            <DeclaredConfigurationResult context="Device" schema="1.0" id="99988660-9080-3433-96e8-f32e85011999" osdefinedscenario="MSFTPolicies" checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999" result_checksum="EE4F1636201B0D39F71654427E420E625B9459EED17ACCEEE1AC9B358F4283FD" operation="Set" state="60">
                <DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration" status="200" state="60">
                    <Key name="DestinationPath" />
                    <Value name="Contents" />
                </DSC>
            </DeclaredConfigurationResult>
        </Data>
    </Item>
</Results>

다음을 통해 공유

선언된 구성 확장성

원하는 상태 구성 리소스 작성

MI 공급자 예제

1단계: 리소스 스키마 MOF 파일 만들기

2단계: 스키마 MOF 파일 복사

3단계: 필요한 파일 편집

4단계: 공급자 생성기 도구 실행

5단계: 생성된 원본 파일 복사

리소스 정보 `MSFT_FileDirectoryConfiguration`

약 `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`

WinDC 문서

SyncML 예제

구성 요청

인벤토리 요청

결과 검색

MI 구현 참조

피드백

추가 리소스

다음을 통해 공유

선언된 구성 확장성

원하는 상태 구성 리소스 작성

MI 공급자 예제

1단계: 리소스 스키마 MOF 파일 만들기

2단계: 스키마 MOF 파일 복사

3단계: 필요한 파일 편집

4단계: 공급자 생성기 도구 실행

5단계: 생성된 원본 파일 복사

리소스 정보 MSFT_FileDirectoryConfiguration

약 MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource

WinDC 문서

SyncML 예제

구성 요청

인벤토리 요청

결과 검색

MI 구현 참조

피드백

추가 리소스

리소스 정보 `MSFT_FileDirectoryConfiguration`

약 `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`