宣告的組態擴充性

發行項
10/15/2024
適用於:

✅ Windows 11, ✅ Windows 10

Windows 宣告的設定 (WinDC) 註冊可透過原生 WMI 提供者提供擴充性。這項功能會使用實作管理基礎結構 (MI) 介面的 Windows Management Instrumentation (WMI) 提供者來具現化和介面。介面必須實作 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 工具來產生 DLL 並準備放置，以產生 MI 介面的原始程式碼。

建立受控物件格式 (MOF) 檔案，以定義所需狀態組態資源的架構，包括參數和方法。此檔案包含資源的必要參數。
將架構MOF檔案以及任何必要的檔案複製到提供者工具目錄，例如：ProviderGenerationTool。
編輯必要的檔案，並包含正確的檔名和類別名稱。
叫用提供者產生器工具以產生提供者的項目檔。
將產生的檔案複製到提供者的項目資料夾。
開始開發程式。

MI 提供者範例

此範例提供有關每個步驟的詳細數據，以示範如何實作名為的 MSFT_FileDirectoryConfiguration範例原生資源。

步驟 1：建立資源架構 MOF 檔案

建立範例架構MOF檔案，用來產生原生資源的 MSFT_FileDirectoryConfiguration 初始原始程式碼。將它放在名為 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] 表示它唯一識別資源實例。至少需要一個 [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.c 和 MSFT_FileDirectoryConfiguration.h。您也可以將來源檔案的擴展名從 .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

在這三個函式中，只有 MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource Get 案例才需要。 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 方法輸出的資源實例。這個實例的型別 MSFT_FileDirectoryConfiguration為，衍生自 MI_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 範圍必須是 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 需要相同標記和屬性的案例。

<DSC> XML 標籤描述以命名空間和類別名稱表示的目標 WMI 提供者，以及要套用至裝置或由 MI 提供者查詢的值。

此標籤具有下列屬性：

屬性描述

namespace 指定目標 MI 提供者命名空間。

classname 目標 MI 提供者。
<Key> XML 標記描述必要的參數名稱和值。它只需要設定的值。名稱是屬性，而值為 <Key> content。

此標籤具有下列屬性：

屬性描述

name 指定 MI 提供者參數的名稱。
<Value> XML 標記描述選擇性的參數名稱和值。它只需要設定的值。名稱是屬性，而值為 <Value> content。

此標籤具有下列屬性：

屬性描述

name 指定 MI 提供者參數的名稱。

屬性	描述
`namespace`	指定目標 MI 提供者命名空間。
`classname`	目標 MI 提供者。

屬性	描述
`name`	指定 MI 提供者參數的名稱。

屬性	描述
`name`	指定 MI 提供者參數的名稱。

SyncML 範例

標準 OMA-DM SyncML 語法可用來指定 DeclaredConfiguration CSP 作業，例如 Replace、 Add 和 Delete。 SyncML <Data> 項目的承載必須是 XML 編碼。針對此 XML 編碼，您可以使用各種在線編碼器。若要避免編碼承載，您可以使用 CDATA 區段，如下列 SyncML 範例所示。

組態要求

此範例示範如何搭配案例使用 MSFT_FileDirectoryConfiguration MI提供者 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>

清查要求

此範例示範如何使用 MSFT_FileDirectoryConfiguration MI 提供者搭配 MSFTExtensibilityMIProviderInventory 案例來傳送清查要求。

<?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`