deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-12 13:27:23 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Split content and examples

Browse Source
This commit is contained in:
Vinay Pamnani (from Dev Box) 2024-08-14 17:45:17 -06:00
parent 4396f9f7f7
commit f13aa0e4da
4 changed files with 298 additions and 275 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
windows/client-management/declared-configuration-extensibility.md
View File

@ -58,7 +58,7 @@ To create a native WMI provider, follow the steps outlined in [How to implement
5. Copy the generated files into the provider's project folder.
6. Start the development process.
## Example
## Example MI Provider
This example provides more details about each step to demonstrate how to implement a sample native resource named `MSFT_FileDirectoryConfiguration`.
@ -235,6 +235,171 @@ The `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource` function does the
1. Clean up resources, for example, free allocated memory.
## Declared Configuration document
> [!IMPORTANT]
> The target of the scenario settings can only be device wide for extensibility. The CSP **scope** defined in `<LocURI>` and Declared Configuration **context** must be `Device`.
The value of the `Document` leaf node in the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md) is an XML document that describes the request. Here's a sample Declared Configuration document with the configuration data specified for extensibility.
```xml
<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>
```
Only supported values for `osdefinedscenario` can be used. Unsupported values result in an error message similar to `Invalid scenario name`.
| osdefinedscenario | Description |
|--------------------------------------|----------------------------------------------|
| MSFTExtensibilityMIProviderConfig | Used to configure MI provider settings. |
| MSFTExtensibilityMIProviderInventory | Used to retrieve MI provider setting values. |
Both `MSFTExtensibilityMIProviderConfig` and `MSFTExtensibilityMIProviderInventory` scenarios that require the same tags and attributes.
- The `<DSC>` XML tag describes the targeted WMI provider expressed by a namespace and class name along with the values either to be applied to the device or queried by the MI provider.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `namespace` | Specifies the targeted MI provider namespace. |
| `classname` | The targeted MI provider. |
- The `<Key>` XML tag describes the required parameter name and value. It only needs a value for configuration. The name is an attribute and the value is `<Key>` content.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `name` | Specifies the name of an MI provider parameter. |
- The `<Value>` XML tag describes the optional parameter name and value. It only needs a value for configuration. The name is an attribute and the value is `<Value>` content.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `name` | Specifies the name of an MI provider parameter. |
## SyncML examples
The standard OMA-DM SyncML syntax is used to specify the DeclaredConfiguration CSP operations such as **Replace**, **Add**, and **Delete**. The payload of the SyncML's `<Data>` element must be XML-encoded. For this XML encoding, there are various online encoders that you can use. To avoid encoding the payload, you can use [CDATA Section](https://www.w3.org/TR/REC-xml/#sec-cdata-sect) as shown in the following SyncML examples.
### Configuration request
This example demonstrates how to send a configuration request using the `MSFT_FileDirectoryConfiguration` MI provider with the `MSFTExtensibilityMIProviderConfig` scenario.
```xml
<?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>
```
### Inventory request
This example demonstrates how to send an inventory request using the MSFT_FileDirectoryConfiguration MI provider with the MSFTExtensibilityMIProviderInventory scenario.
```xml
<?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>
```
### Retrieve results
This example retrieves the results of a configuration or inventory request:
**Request**:
```xml
<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>
```
**Response**:
```xml
<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 implementation references
- [Introducing the management infrastructure (MI) API](/archive/blogs/wmi/introducing-new-management-infrastructure-mi-api)

121
windows/client-management/declared-configuration-resource-access.md
View File

@ -37,45 +37,77 @@ These guidelines provide best practices and examples for developers and testers
By following these guidelines and understanding the syntax of the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md), you can effectively implement and manage RA configurations while maintaining security and compliance.
## Resource access configuration with examples
## Declared Configuration document
Resource access configuration utilizes the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md). A declared configuration request for configuring resource access is sent using an OMA-URI similar to `./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/{DocID}/Document`.
The value of the `Document` leaf node in the [DeclaredConfiguration CSP](mdm/declaredconfiguration-csp.md) is an XML document that describes the request. Here's a sample Declared Configuration document with the configuration data specified for resource accecss.
- The URI is prefixed with a targeted scope. The `<LocURI>` and the DeclaredConfiguration Context need to match. For example, when `LocURI` starts with **Device**, Context should be **Device** as well. When `LocURI` doesn't start with **Device**, Context should be **User**.
- `{DocID}` is a unique identifier for the desired state of the configuration scenario. Every document must have an **ID**, which must be a GUID.
```xml
<DeclaredConfiguration context="user" schema="1.0" id="DCA000B5-397D-40A1-AABF-40B25078A7F9" osdefinedscenario="MSFTVPN" checksum="A0">
<CSP name="./Vendor/MSFT/VPNv2">
<URI path="Test_SonicWall/TrafficFilterList/0/Protocol" type="int">2</URI>
<URI path="Test_SonicWall/TrafficFilterList/0/Direction" type="chr">outbound</URI>
</CSP>
</DeclaredConfiguration>
```
:::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="Declared Configuration resource access syntax":::
Only supported values for `osdefinedscenario` can be used. Unsupported values result in a failure.
Only supported values for `osdefinedscenario` can be used. Unsupported values result in an error message similar to `Invalid scenario name`.
| osdefinedscenario | Recommended using with |
|------------------------------|-------------------------------|
| MSFTWiredNetwork | WiredNetwork |
| MSFTResource | ActiveSync |
| MSFTVpn | VPN and VPNv2 |
| MSFTVPN | VPN and VPNv2 |
| MSFTWifi | Wifi |
| MSFTInventory | Certificate inventory |
| MSFTClientCertificateInstall | SCEP, PFX, Bulk Template Data |
Examples:
These `osdefinedscenario` values require the following tags and attributes.
1. MSFTWifi (snippet) for Wifi:
- The `<CSP>` XML tag describes the CSP being targeted.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `name` | Specifies the targeted CSP OMA-URI. |
- The `<URI>` XML tag specifies the CSP setting node along with the desired value.
This tag has the following attributes:
| Attribute | Description |
|-----------|-------------------|
| `path` | Setting path |
| `type` | Setting data type |
> [!NOTE]
> The target of the scenario settings must match the Declared Configuration context. The CSP **scope** defined in `<LocURI>` and Declared Configuration **context** must both be either `Device` or `User`.
>
> :::image type="content" source="images/declared-configuration-ra-syntax.png" alt-text="Declared Configuration resource access syntax":::
### osdefinedscenario examples
- Partial `MSFTWifi` example for Wifi:
```xml
<DeclaredConfiguration context="Device" schema="1.0" id="10249228-e719-58bf-b459-060de45240f1" osdefinedscenario="MSFTWifi" checksum="11111111">
<CSP name="./Vendor/MSFT/WiFi">
```
1. MSFTTResource (snippet) for ActiveSync:
- Partial `MSFTResource` example for ActiveSync:
```xml
<DeclaredConfiguration context="User" schema="1.0" id="33333333-1861-4131-96e8-44444444" osdefinedscenario="MSFTResource" checksum="5555">
<CSP name="./Vendor/MSFT/ActiveSync">
```
## SyncML examples
The standard OMA-DM SyncML syntax is used to specify the DeclaredConfiguration CSP operations such as **Replace**, **Add**, and **Delete**. The payload of the SyncML's `<Data>` element must be XML-encoded. For this XML encoding, there are various online encoders that you can use. To avoid encoding the payload, you can use [CDATA Section](https://www.w3.org/TR/REC-xml/#sec-cdata-sect) as shown in the following SyncML examples.
### Configure a VPNv2 profile for resource access
This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to configure a VPN profile named **Test_SonicWall** on the device in the **User** scope.
This example demostrates how to use the [VPNv2 CSP](mdm/vpnv2-csp.md) to configure a VPN profile named **Test_SonicWall** on the device in the **User** scope.
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
@ -118,15 +150,17 @@ This example uses the [VPNv2 CSP](mdm/vpnv2-csp.md) to configure a VPN profile n
</SyncML>
```
<!--
> [!NOTE]
>
> - Format of the `<LocURI>` and `<DeclaredConfiguration>` follow the [Declared Configuration CSP](mdm/declaredconfiguration-csp.md) syntax.
> - The `id` of `<DeclaredConfiguration>` should be a unique string.
> - `<Format>` of `<Meta>` should be `chr` and `<Type>` should be `text/plain`.
-->
### Updating a VPNv2 profile for resource access
This example uses the same Declared Configuration **Document ID**, but with a new checksum("A3"). It installs a new VPNv2 profile named `Test_SonicwallNew`, and deletes the old profile.
This example demonstrates how to use the same Declared Configuration **Document ID**, but with a new checksum("A3"). It installs a new VPNv2 profile named `Test_SonicwallNew`, and deletes the old profile.
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
@ -166,7 +200,7 @@ This example uses the same Declared Configuration **Document ID**, but with a ne
### Getting the VPNv2 profile
This example uses `<Get>` to retrieve the results of the Declared configuration request.
This example demonstrates how to use `<Get>` to retrieve the results of the Declared configuration request.
```xml
<?xml version="1.0" encoding="utf-8"?>
@ -230,7 +264,7 @@ This example uses `<Get>` to retrieve the results of the Declared configuration
### Deleting the VPNv2 profile
This example uses `<Delete>` to remove the configuration request to set the VPNv2 profile.
This example demonstrates how to use `<Delete>` to remove the configuration request to set the VPNv2 profile.
```xml
<?xml version="1.0" encoding="utf-8"?>
@ -253,67 +287,12 @@ This example uses `<Delete>` to remove the configuration request to set the VPNv
</SyncML>
```
## Resource Ownership
MDM-managed resources, such as a VPN profile, are transferred/migrated to Windows Declared Configuration management when a Declared Configuration document is sent to the device for the same resource. This resource stays under Declared Configuration management until the Windows Declared Configuration document is deleted or abandoned. Otherwise, when MDM tries to manage the same resource via the legacy MDM channel using SyncML, it fails with error 0x86000031.
MDM-managed resources, such as a VPN profile, are transferred/migrated to Windows Declared Configuration management when a Declared Configuration document is sent to the device for the same resource. This resource stays under Declared Configuration management until the Windows Declared Configuration document is [deleted](mdm/declaredconfiguration-csp.md#delete-a-declared-configuration-document) or [abandoned](mdm/declaredconfiguration-csp.md#abandon-a-declared-configuration-document). Otherwise, when MDM tries to manage the same resource via the legacy MDM channel using SyncML, it fails with error 0x86000031.
`MDM ConfigurationManager: Command failure status. Configuraton Source ID: (29c383c5-6e2d-43bf-a741-c63cb7516bb4), Enrollment Type: (MDMDeviceWithAAD), CSP Name: (ActiveSync), Command Type: (Add: from Replace or Add), CSP URI: (./User/Vendor/MSFT/ActiveSync/Accounts/{3b8b9d4d-a24e-4c6d-a460-034d0bfb9316}), Result: (Unknown Win32 Error code: 0x86000031).`
### Abandon Workflow
Abandoning a resource occurs when certain resources are no longer targeted to a user or group. Instead of deleting the resource on the device, the server can choose to abandon the Declared Configuration document. An abandoned resource stays on the device but stops refreshing the Declared Configuration document that handles drift control. Also the resource ownership is transferred back to MDM, which means the same resource can be modified via legacy MDM channel again.
This example abandons a Windows Declared Configuration Document, by setting the **Abandoned** property to **1**.
```xml
<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>10</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned</LocURI>
</Target>
<Meta>
<Format xmlns="syncml:metinf">int</Format>
</Meta>
<Data>1</Data>
</Item>
</Replace>
<Final />
</SyncBody>
</SyncML>
```
### Unabandon workflow
Unabandoning the document causes the document to be applied right away, transferring the resource ownership back to Declared Configuration management and blocking legacy MDM channel from managing the channels again.
This example unabandons a Windows Declared Configuration Document, by setting the **Abandoned** property to **0**.
```xml
<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>10</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned</LocURI>
</Target>
<Meta>
<Format xmlns="syncml:metinf">int</Format>
</Meta>
<Data>0</Data>
</Item>
</Replace>
<Final />
</SyncBody>
</SyncML>
```
## Bulk template data
The Bulk template data scenario extends beyond the regular [ClientCertificateInstall CSP](mdm/clientcertificateinstall-csp.md). It uses a special bulk template document type. This section covers the structure, specification, and results of using the bulk template data.

8
windows/client-management/declared-configuration.md
View File

@ -7,14 +7,14 @@ ms.topic: overview
# What is the declared configuration protocol
The declared configuration protocol is a desired state device configuration model designed for efficient and reliable management of Windows devices. It leverages the OMA-DM SyncML protocol to provide all necessary settings in a single batch through a dedicated OMA-DM server. The device's declared configuration client stack processes these settings to achieve the desired state in the most efficient and reliable manner.
The declared configuration protocol is a desired state device configuration model designed for efficient and reliable management of Windows devices. It uses the OMA-DM SyncML protocol to provide all necessary settings in a single batch through a dedicated OMA-DM server. The device's declared configuration client stack processes these settings to achieve the desired state in the most efficient and reliable manner.
The declared configuration protocol requires that a device has a separate [OMA-DM enrollment](mdm-overview.md), which is dependent on the device being enrolled with the primary OMA-DM server. The desired state model is a different model from the current model where the server is responsible for the device's desire state. This dual enrollment is only allowed if the device is already enrolled into a primary MDM server. This other enrollment separates the desired state management functionality from the primary functionality.
- [Declared configuration discovery](declared-configuration-discovery.md): The initial discovery phase of the Declared Configuration Protocol uses a dedicated JSON schema to query enrollment details from the [discovery service endpoint (DS)](/openspecs/windows_protocols/ms-mde2/60deaa44-52df-4a47-a844-f5b42037f7d3#gt_8d76dac8-122a-452b-8c97-b25af916f19b). This phase involves sending HTTP requests with specific headers and a JSON body containing details such as user domain, tenant ID, and OS version. The DS responds with the necessary enrollment service URLs and authentication policies based on the enrollment type (Microsoft Entra joined or registered devices).
- [Declared configuration enrollment](declared-configuration-enrollment.md): The enrollment phase follows the [MS-MDE2 protocol](/openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) and uses new [DMClient CSP](mdm/dmclient-csp.md) policies for dual enrollment. This phase involves setting the `LinkedEnrollment/DiscoveryEndpoint` and triggering the `LinkedEnrollment/Enroll` using SyncML commands. The device can then manage its configuration state by interacting with the OMA-DM server through these policies.
The declared configuration enrollment offers following desired state management features:
The declared configuration enrollment offers these desired state management features:
- [Resource access](declared-configuration-resource-access.md): Provides access to necessary resources for configuration.
- [Extensibility](declared-configuration-extensibility.md): Allows for extending the configuration capabilities as needed.
@ -36,9 +36,9 @@ Declared Configuration enrollment for [Microsoft Entra registered devices](/entr
- Windows 11, version 22H2 with [KB5040527](https://support.microsoft.com/help/5040527) (OS Build 22621.3958)
- Windows 10, version 22H2 with [KB5040525](https://support.microsoft.com/help/5040525) (OS Build 19045.4717)
## Declared configuration refresh interval
## Refresh interval
The Declared Configuration refresh schedule is created whenever there's a Declared Configuration doc present on the device and there's currently no schedule task for refresh. The task runs every 4 hours by default and can be configured. Each time the Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine tries to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc can't be reapplied due to instance data missing, the Declared Configuration doc is marked in drifted state and a new sync session is triggered to notify there's a drift.
The Declared configuration refresh schedule is created whenever there's a Declared Configuration doc present on the device and there's currently no schedule task for refresh. The task runs every 4 hours by default and can be configured. Each time the Declared Configuration refresh task runs, it checks for all drifts from desired state by comparing the current system configuration versus the server intention in the Declared Configuration docs. If there are any drifts, Declared Configuration engine tries to reapply the Declared Configuration docs to fix it. In case where a Declared Configuration doc can't be reapplied due to instance data missing, the Declared Configuration doc is marked in drifted state and a new sync session is triggered to notify there's a drift.
To identify, adjust or remove the refresh schedule, use the **RefreshInterval** URI:

277
windows/client-management/mdm/declaredconfiguration-csp.md
View File

@ -730,103 +730,47 @@ The Document node's value is an XML based document containing a collection of se
<!-- DeclaredConfiguration-CspMoreInfo-Begin -->
<!-- Add any additional information about this CSP here. Anything outside this section will get overwritten. -->
## Declared configuration OMA URI
## Declared Configuration OMA URI
A declared configuration request is sent using an OMA-URI similar to `./Device/Vendor/MSFT/DeclaredConfiguration/Host/[Complete|Inventory]/Documents/{DocID}/Document`.
- The URI is prefixed with a targeted scope. The target of the scenario settings can only be device wide for extensibility. The scope should be `Device`.
- The URI is prefixed with a targeted scope (`User` or `Device`).
- `{DocID}` is a unique identifier for the desired state of the configuration scenario. Every document must have an ID, which must be a GUID.
- The request can be a **Configuration**, **Inventory**, or **Complete** request.
- The request can be a **Inventory**, or **Complete** request.
The following URI is an example of a **Complete** request: `./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document`
## DeclaredConfiguration document XML
The value of the leaf node `Document` is an XML document that describes the request. The actual processing of the request pivots around the `osdefinedscenario` tag:
- `MSFTExtensibilityMIProviderConfig`: Used to configure MI provider settings.
- `MSFTExtensibilityMIProviderInventory`: Used to retrieve MI provider setting values.
The DeclaredConfiguration CSP synchronously validates the batch of settings described by the `<DeclaredConfiguration>` element, which represents the declared configuration document. It checks for correct syntax based on the declared configuration XML schema. If there's a syntax error, the CSP returns an error immediately back to the server as part of the current OMA-DM session. If the syntax check passes, then the request is passed on to a Windows service. The Windows service asynchronously attempts the desired state configuration of the specified scenario. This process frees up the server to do other work thus the low latency of this declared configuration protocol. The Windows client service, the orchestrator, is responsible for driving the configuration of the device based on the server supplied desire state. The service also maintains this state throughout its lifetime, until the server removes or modifies it.
The following example uses the built-in, native MI provider `MSFT_FileDirectoryConfiguration` with the OS-defined scenario `MSFTExtensibilityMIProviderConfig`:
## Declared Configuration document
```xml
<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">TestFileContentBlah</Value>
</DSC>
<DeclaredConfiguration
schema="1.0"
context="Device"
id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2"
checksum="99925209110918B67FE962460137AA3440AFF4DB6ABBE15C8F499682457B9999"
osdefinedscenario="MSFTExtensibilityMIProviderConfig">
... {Configuration Data} ...
</DeclaredConfiguration>
```
The standard OMA-DM SyncML syntax is used to specify the DeclaredConfiguration CSP operations such as **Replace**, **Set**, and **Delete**. The payload of the SyncML's `<Data>` element must be XML-encoded. For this XML encoding, there are various online encoders that you can use. To avoid encoding the payload, you can use [CDATA Section](https://www.w3.org/TR/REC-xml/#sec-cdata-sect) as shown in the following example:
The `<DeclaredConfiguration>` XML tag specifies the details of the declared configuration document to process. The document could be part of a configuration request or an inventory request. The DeclaredConfiguration CSP has two URIs to allow the specification of a [configuration](#hostcomplete) or an [inventory](#hostinventory) request.
```xml
<?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/99988660-9080-3433-96e8-f32e85011999/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">TestFileContentBlah</Value>
</DSC>
</DeclaredConfiguration>]]>
</Data>
</Item>
</Replace>
<Final/>
</SyncBody>
</SyncML>
```
This tag has the following attributes:
### DeclaredConfiguration XML document tags
| Attribute | Description |
|---------------------|----------------------------------------------------------------------------------------|
| `schema` | The schema version of the xml. Currently `1.0`. |
| `context` | States whether the document is targeting the device or user. |
| `id` | The unique identifier of the document set by the server. This value should be a GUID. |
| `checksum` | This value is the server-supplied version of the document. |
| `osdefinedscenario` | The named scenario that the client should configure with the given configuration data. |
Both `MSFTExtensibilityMIProviderConfig` and `MSFTExtensibilityMIProviderInventory` are OS-defined scenarios that require the same tags and attributes.
The DeclaredConfiguration CSP synchronously validates the batch of settings described by the `<DeclaredConfiguration>` element, which represents the declared configuration document. It checks for correct syntax based on the declared configuration XML schema. If there's a syntax error, the CSP returns an error immediately back to the server as part of the current OMA-DM session. If the syntax check passes, then the request is passed on to a Windows service. The Windows service asynchronously attempts the desired state configuration of the specified scenario. This process frees up the server to do other work thus the low latency of the declared configuration protocol. The Windows client service, the orchestrator, is responsible for driving the configuration of the device based on the server supplied desire state. The service also maintains this state throughout its lifetime, until the server removes or modifies it.
- The `<DeclaredConfiguration>` XML tag specifies the details of the declared configuration document to process. The document could be part of a configuration request or an inventory request. The DeclaredConfiguration CSP has two URIs to allow the specification of a configuration or an inventory request.
The actual processing of the request pivots around the `osdefinedscenario` tag and the configuration data specified within the document. For more information, see:
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `schema` | The schema version of the xml. Currently `1.0`. |
| `context` | States that this document is targeting the device. The value should be `Device`. |
| `id` | The unique identifier of the document set by the server. This value should be a GUID. |
| `checksum` | This value is the server-supplied version of the document. |
| `osdefinedscenario` | The named scenario that the client should configure with the given configuration data. For extensibility, the scenario is either `MSFTExtensibilityMIProviderConfig` or `MSFTExtensibilityMIProviderInventory`. |
- The `<DSC>` XML tag describes the targeted WMI provider expressed by a namespace and class name along with the values either to be applied to the device or queried by the MI provider.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `namespace` | Specifies the targeted MI provider namespace. |
| `classname` | The targeted MI provider. |
- The `<Key>` XML tag describes the required parameter name and value. It only needs a value for configuration. The name is an attribute and the value is `<Key>` content.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `name` | Specifies the name of an MI provider parameter. |
- The `<Value>` XML tag describes the optional parameter name and value. It only needs a value for configuration. The name is an attribute and the value is `<Value>` content.
This tag has the following attributes:
| Attribute | Description |
|--|--|
| `name` | Specifies the name of an MI provider parameter. |
- [Declared Configuration document for resource access](../declared-configuration-resource-access.md#declared-configuration-document)
- [Declared Configuration document for extensibility](../declared-configuration-extensibility.md#declared-configuration-document)
## Declared configuration generic alert
@ -855,9 +799,11 @@ On every client response to the server's request, the client constructs a declar
In this example, there's one declared configuration document listed in the alert summary. The alert summary lists every document that the client stack is processing, either a configuration or inventory request. It describes the context of the document that specifies the scope of how the document is applied. The **context** value should be `Device`.
The **state** attribute has a value of `60`, which indicates that the document was processed successfully.
## Declared configuration states
The **state** attribute has a value of `60`, which indicates that the document was processed successfully. The following class defines the other state values:
The following class defines the state values:
```csharp
enum class DCCSPURIState :unsigned long
@ -891,133 +837,66 @@ enum class DCCSPURIState :unsigned long
## SyncML examples
- Retrieve the results of a configuration or inventory request:
- [SyncML examples for resource access](../declared-configuration-resource-access.md#syncml-examples)
- [SyncML examples for extensibility](../declared-configuration-extensibility.md#syncml-examples)
```xml
<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>
```
### Abandon a Declared Configuration document
```xml
<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>
```
Abandoning a resource occurs when certain resources are no longer targeted to a user or group. Instead of deleting the resource on the device, the server can choose to abandon the Declared Configuration document. An abandoned resource stays on the device but stops refreshing the Declared Configuration document that handles drift control. Also the [resource ownership](../declared-configuration-resource-access.md#resource-ownership) is transferred to MDM, which means the same resource can be modified via legacy MDM channel again.
- Replace a configuration or inventory request
This example demonstrats how to abandon a Declared Configuration Document, by setting the **Abandoned** property to **1**.
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>14</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</LocURI>
</Target>
<Data>
<![CDATA[<DeclaredConfiguration schema="1.0" context="Device" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" checksum="99995209110918B67FE962460137AA3440AFF4DB6ABBE15C8F49968245799999" osdefinedscenario="MSFTExtensibilityMIProviderInventory">
<DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration">
<Key name="DestinationPath">c:/temp/foobar.tmp</Key>
<Value name="Contents"></Value>
</DSC>
</DeclaredConfiguration>]]>
</Data>
</Item>
</Replace>
<Final />
</SyncBody>
</SyncML>
```
```xml
<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/Inventory/Results/99998660-9080-3433-96e8-f32e85019999/Document</LocURI>
</Source>
<Data>
<DeclaredConfigurationResult context="Device" schema="1.0" id="27FEA311-68B9-4320-9FC4-296F6FDFAFE2" osdefinedscenario="MSFTExtensibilityMIProviderInventory" checksum="99995209110918B67FE962460137AA3440AFF4DB6ABBE15C8F49968245799999" result_checksum="A27B0D234CBC2FAC1292F1E8FBDF6A90690F3988DEDC9D716829856C9ACE0E20" operation="Get" state="80">
<DSC namespace="root/Microsoft/Windows/DesiredStateConfiguration" className="MSFT_FileDirectoryConfiguration" status="200" state="80">
<Key name="DestinationPath">c:/temp/foobar.tmp</Key>
<Value name="Contents">TestFileContent</Value>
</DSC>
</DeclaredConfigurationResult>
</Data>
</Item>
</Results>
```
- Abandon a configuration or inventory request. This process results in the client tracking the document but not reapplying it. The alert has the `Abandoned` property set to `1`, which indicates that the document is no longer managed by the declared configuration server.
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>2</CmdID>
<Item>
<Meta>
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>2</CmdID>
<Item>
<Meta>
<Format>int</Format>
<Type>text/plain</Type>
</Meta>
<Target>
</Meta>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Properties/Abandoned</LocURI>
</Target>
<Data>1</Data>
</Item>
</Replace>
</Target>
<Data>1</Data>
</Item>
</Replace>
<Final/>
</SyncBody>
</SyncML>
```
</SyncBody>
</SyncML>
```
- Deletion of configuration or inventory request. The SyncML deletion of the document only removes the document but any extensibility settings persist on the device (tattoo).
### Unabandon a Declared Configuration document
Unabandoning the document causes the document to be applied right away, transferring the [resource ownership](../declared-configuration-resource-access.md#resource-ownership) back to Declared Configuration management and blocking legacy MDM channel from managing the channels again.
This example demonstrates how to unabandon a Windows Declared Configuration Document, by setting the **Abandoned** property to **0**.
```xml
<?xml version="1.0" encoding="utf-8"?>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>10</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/DCA000B5-397D-40A1-AABF-40B25078A7F9/Properties/Abandoned</LocURI>
</Target>
<Meta>
<Format xmlns="syncml:metinf">int</Format>
</Meta>
<Data>0</Data>
</Item>
</Replace>
<Final />
</SyncBody>
</SyncML>
```
### Delete a Declared Configuration document
The SyncML deletion of the document only removes the document but any settings persist on the device. This example demonstrates how to delete a document.
```xml
<?xml version="1.0" encoding="utf-8"?>