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

Merge pull request #8923 from MicrosoftDocs/main

Browse Source 
Publish main to live, Friday 10:30AM PDT, 9/29
This commit is contained in:
Stacyrch140 2023-09-29 13:44:26 -04:00 committed by GitHub
commit 272f15b1d7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 1943 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

251
windows/client-management/declared-configuration-extensibility.md Normal file
View File

@ -0,0 +1,251 @@
---
title: Declared configuration extensibility
description: Learn more about declared configuration extensibility through native WMI providers.
ms.date: 09/26/2023
ms.topic: how-to
---
# Declared configuration extensibility providers
The declared configuration enrollment, which supports the declared configuration client stack, offers extensibility through native WMI providers. This feature instantiates and interfaces with a Windows Management Instrumentation (WMI) provider that has implemented a management infrastructure (MI) interface. The interface must implement GetTargetResource, TestTargetResource, and SetTargetResource methods, and may implement any number of string properties.
> [!NOTE]
> Only string properties are currently supported by extensibility providers.
```mof
[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
);
```
## Author desired state configuration resources
To create a native WMI provider, follow the steps outlined in [How to implement an MI provider](/previous-versions/windows/desktop/wmi_v2/how-to-implement-an-mi-provider). These steps include how to generate the source code for an MI interface using the `Convert-MofToProvider.exe` tool to generate the DLL and prepare it for placement.
1. Create a MOF file that defines the schema for the desired state configuration resource including parameters and methods. This file includes the required parameters for the resource.
2. Copy the schema MOF file along with any required files into the provider tools directory, for example: ProviderGenerationTool.
3. Edit the required files and include the correct file names and class names.
4. Invoke the provider generator tool to generate the provider's project files.
5. Copy the generated files into the provider's project folder.
6. Start the development process.
## Example
This example provides more details about each step to demonstrate how to implement a sample native resource named `MSFT_FileDirectoryConfiguration`.
### Step 1: Create the resource schema MOF file
Create a sample schema MOF file used to generate the initial source code for the `MSFT_FileDirectoryConfiguration` native resource. Place it in the project directory named `MSFT_FileDirectoryConfiguration`.
```mof
#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
);
};
```
> [!NOTE]
>
> - The class name and DLL file name should be the same, as defined in the `Provider.DEF` file.
> - The type qualifier `[Key]` on a property indicates that it uniquely identifies the resource instance. At least one `[Key]` property is required.
> - The `[Required]` qualifier indicates that the property is required. In other words, a value must be specified in any configuration script that uses this resource.
> - The `[write]` qualifier indicates that the property is optional when using the custom resource in a configuration script. The `[read]` qualifier indicates that a property can't be set by a configuration, and is for reporting purposes only.
> - The `[Values]` qualifier restricts the values that can be assigned to the property. Define the list of allowed values in `[ValueMap]`. For more information, see [ValueMap and value qualifiers](/windows/win32/wmisdk/value-map).
> - Any new MOF file should include the following lines at the top of the file:
>
> ```mof
> #pragma include ("cim_schema_2.26.0.mof")
> #pragma include ("OMI_BaseResource.mof")
> #pragma include ("MSFT_Credential.mof")
> ```
>
> - Method names and its parameters should be same for every resource. Change `MSFT_FileDirectoryConfiguration` from EmbeddedInstance value to the class name of the desired provider. There should be only one provider per MOF file.
### Step 2: Copy the schema MOF files
Copy these required files and folders to the project directory you created in step 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`
For more information on how to obtain the required files, see [How to implement an MI provider](/previous-versions/windows/desktop/wmi_v2/how-to-implement-an-mi-provider).
### Step 3: Edit the required files
Modify the following files in the project directory:
- `MSFT_FileDirectoryConfiguration.mof`: You created this file in step 1.
- `Provider.DEF`: This file contains the DLL name, for example, `MSFT_FileDirectoryConfiguration.dll`.
- `codegen.cmd`: This file contains the command to invoke `convert-moftoprovider.exe`.
```cmd
"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
```
### Step 4: Run the provider generator tool
Run `codegen.cmd`, which runs the `convert-moftoprovider.exe` command. Alternatively, you can run the command directly.
### Step 5: Copy the generated source files
The command in step 3 specifies the `-OutPath` parameter, which in this example is a folder named `temp`. When you run the tool in step 4, it creates new files in this folder. Copy the generated files from this `temp` folder to the project directory. You created the project directory in step 1, which in this example is `MSFT_FileDirectoryConfiguration`.
> [!NOTE]
> Any time you update the schema MOF file, run the `codegen.cmd` script to regenerate the source files. Rerunning the generator tool overwrites any existing the source files. To prevent this behavior, this example uses a temporary folder. Minimize updates to the schema MOF file since the main implementation should be merged with the most recent auto-generated source files.
### About the `MSFT_FileDirectoryConfiguration` resource
After you run the provider generator tool, it creates several source and header files:
- `MSFT_FileDirectoryConfiguration.c`
- `MSFT_FileDirectoryConfiguration.h`
- `module.c`
- `schema.c`
- `WMIAdapter.c`
From this list, you only need to modify `MSFT_FileDirectoryConfiguration.c` and `MSFT_FileDirectoryConfiguration.h`. You can also change the extension for the source files from `.c` to `.cpp`, which is the case for this resource. The business logic for this resource is implemented in `MSFT_FileDirectoryConfigurationImp.cpp` and `MSFT_FileDirectoryConfigurationImp.h`. These new files are added to the `MSFT_FileDirectoryConfiguration` project directory after you run the provider generator tool.
For a native desired state configuration resource, you have to implement three autogenerated functions in `MSFT_FileDirectoryConfiguration.cpp`:
- `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`
- `MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource`
- `MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource`
From these three functions, only `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource` is required for a Get scenario. `MSFT_FileDirectoryConfiguration_Invoke_TestTargetResource` and `MSFT_FileDirectoryConfiguration_Invoke_SetTargetResource` are used when remediation is needed.
There are several other autogenerated functions in `MSFT_FileDirectoryConfiguration.cpp` that don't need implementation for a native desired state configuration resource. You don't need to modify the following functions:
- `MSFT_FileDirectoryConfiguration_Load`
- `MSFT_FileDirectoryConfiguration_Unload`
- `MSFT_FileDirectoryConfiguration_EnumerateInstances`
- `MSFT_FileDirectoryConfiguration_GetInstance`
- `MSFT_FileDirectoryConfiguration_CreateInstance`
- `MSFT_FileDirectoryConfiguration_ModifyInstance`
- `MSFT_FileDirectoryConfiguration_DeleteInstance`
### About `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource`
The `MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource` function does the following steps to complete its task:
1. Validate the input resource.
1. Ensure the keys and required parameters are present.
1. Create a resource instance that is used as the output of the Get method. This instance is of type `MSFT_FileDirectoryConfiguration`, which is derived from `MI_Instance`.
1. Create the output resource instance from the modified resource instance and return it to the MI client by calling these functions:
- `MSFT_FileDirectoryConfiguration_GetTargetResource_Construct`
- `MSFT_FileDirectoryConfiguration_GetTargetResource_SetPtr_OutputResource`
- `MSFT_FileDirectoryConfiguration_GetTargetResource_Set_MIReturn`
- `MSFT_FileDirectoryConfiguration_GetTargetResource_Post`
- `MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct`
1. Clean up resources, for example, free allocated memory.
## MI implementation references
- [Introducing the management infrastructure (MI) API](/archive/blogs/wmi/introducing-new-management-infrastructure-mi-api)
- [Implementing MI provider (1) - Overview](/archive/blogs/wmi/implementing-mi-provider-1-overview)
- [Implementing MI provider (2) - Define schema](/archive/blogs/wmi/implementing-mi-provider-2-define-schema)
- [Implementing MI provider (3) - Generate code](/archive/blogs/wmi/implementing-mi-provider-3-generate-code)
- [Implementing MI provider (4) - Generate code (continue)](/archive/blogs/wmi/implementing-mi-provider-4-generate-code-continute)
- [Implementing MI provider (5) - Implement](/archive/blogs/wmi/implementing-mi-provider-5-implement)
- [Implementing MI provider (6) - Build, register, and debug](/archive/blogs/wmi/implementing-mi-provider-6-build-register-and-debug)
- [MI interfaces](/previous-versions/windows/desktop/wmi_v2/mi-interfaces)
- [MI datatypes](/previous-versions/windows/desktop/wmi_v2/mi-datatypes)
- [MI structures and unions](/previous-versions/windows/desktop/wmi_v2/mi-structures-and-unions)
- [MI_Result enumeration (mi.h)](/windows/win32/api/mi/ne-mi-mi_result)
- [MI_Type enumeration (mi.h)](/windows/win32/api/mi/ne-mi-mi_type)

65
windows/client-management/declared-configuration.md Normal file
View File

@ -0,0 +1,65 @@
---
title: Declared configuration protocol
description: Learn more about using declared configuration protocol for desired state management of Windows devices.
ms.date: 09/26/2023
ms.topic: overview
---
# What is the declared configuration protocol
The declared configuration protocol is based on a desired state device configuration model, though it still uses the underlying OMA-DM Syncml protocol. Through a dedicated OMA-DM server, it provides all the settings in a single batch through this protocol. The device's declared configuration client stack can reason over the settings to achieve the desired scenario 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. The declared configuration enrollment's first desired state management model feature is called [extensibility](declared-configuration-extensibility.md).
:::image type="content" source="images/declared-configuration-model.png" alt-text="Diagram illustrating the declared configuration model.":::
With the [Declared Configuration CSP](mdm/declaredconfiguration-csp.md), the OMA-DM server can provide the device with the complete collection of setting names and associated values based on a specified scenario. The declared configuration stack on the device is responsible for handling the configuration request, and maintaining its state including updates to the scenario.
The benefit of the declared configuration desired state model is that it's efficient and accurate, especially since it's the responsibility of the declared configuration client to configure the device. The efficiency of declared configuration is because the client can asynchronously process batches of scenario settings, which free up the server resources to do other work. Thus the declared configuration protocol has low latency. As for configuration quality and accuracy, the declared configuration client stack has detailed knowledge of the configuration surface area of the device. This behavior includes the proper handling of continuous device updates that affect the configuration scenario.
## Declared configuration enrollment
[Mobile Device Enrollment Protocol version 2](/openspecs/windows_protocols/ms-mde2/4d7eadd5-3951-4f1c-8159-c39e07cbe692) describes enrollment including discovery, which covers the primary and declared configuration enrollments. The device uses the following new [DMClient CSP](mdm/dmclient-csp.md) policies for declared configuration dual enrollment:
- [LinkedEnrollment/Enroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenroll)
- [LinkedEnrollment/Unenroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentunenroll)
- [LinkedEnrollment/EnrollStatus](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenrollstatus)
- [LinkedEnrollment/LastError](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentlasterror)
- [LinkedEnrollment/DiscoveryEndpoint](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentdiscoveryendpoint)
The following SyncML example sets **LinkedEnrolment/DiscoveryEndpoint** and triggers **LinkedEnrollment/Enroll**:
```xml
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Replace>
<CmdID>2</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/DiscoveryEndpoint</LocURI>
</Target>
<Data>https://discovery.dm.microsoft.com/EnrollmentConfiguration?api-version=1.0</Data>
</Item>
</Replace>
<Final/>
</SyncBody>
</SyncML>
<SyncML xmlns="SYNCML:SYNCML1.1">
<SyncBody>
<Exec>
<CmdID>2</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/DMClient/Provider/MS%20DM%20SERVER/LinkedEnrollment/Enroll</LocURI>
</Target>
</Item>
</Exec>
<Final/>
</SyncBody>
</SyncML>
```
## Related content
- [Declared Configuration extensibility](declared-configuration-extensibility.md)

BIN
windows/client-management/images/declared-configuration-model.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

1049
windows/client-management/mdm/declaredconfiguration-csp.md Normal file
View File

File diff suppressed because it is too large Load Diff

482
windows/client-management/mdm/declaredconfiguration-ddf-file.md Normal file
View File

@ -0,0 +1,482 @@
---
title: DeclaredConfiguration DDF file
description: View the XML file containing the device description framework (DDF) for the DeclaredConfiguration configuration service provider.
author: vinaypamnani-msft
manager: aaroncz
ms.author: vinpa
ms.date: 09/27/2023
ms.localizationpriority: medium
ms.prod: windows-client
ms.technology: itpro-manage
ms.topic: reference
---
<!-- Auto-Generated CSP Document -->
# DeclaredConfiguration DDF file
The following XML file contains the device description framework (DDF) for the DeclaredConfiguration configuration service provider.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MgmtTree PUBLIC " -//OMA//DTD-DM-DDF 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/DM_DDF-V1_2.dtd"[<?oma-dm-ddf-ver supported-versions="1.2"?>]>
<MgmtTree xmlns:MSFT="http://schemas.microsoft.com/MobileDevice/DM">
<VerDTD>1.2</VerDTD>
<MSFT:Diagnostics>
</MSFT:Diagnostics>
<Node>
<NodeName>DeclaredConfiguration</NodeName>
<Path>./Device/Vendor/MSFT</Path>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>The Declared Configuration CSP (Configuration Service Provider) allows the OMA-DM server to provide the device with the complete collection of setting names and associated values based on a specified scenario. The Declared Configuration stack on the device is responsible for handling the configuration request along with maintaining its state including updates to the scenario. It also provides the means to retrieve a scenario’s settings from the device. The configuration request and settings retrieval request are performed asynchronously, freeing up the server’s worker thread to do other useful work. The subsequent results can be retrieved through Declared Configuration’s result nodes.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Permanent />
</Scope>
<DFType>
<MIME />
</DFType>
<MSFT:Applicability>
<MSFT:OsBuildVersion>99.9.99999</MSFT:OsBuildVersion>
<MSFT:CspVersion>9.9</MSFT:CspVersion>
<MSFT:EditionAllowList>0x4;0x1B;0x30;0x31;0x48;0x54;0x62;0x63;0x64;0x65;0x79;0x7A;0x7D;0x7E;0x81;0x82;0x8A;0x8B;0xA1;0xA2;0xA4;0xA5;0xAB;0xAC;0xAF;0xBC;0xBF;0xCA;0xCB;0xCD;</MSFT:EditionAllowList>
</MSFT:Applicability>
</DFProperties>
<Node>
<NodeName>Host</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>The Host internal node indicates that the target of the configuration request or inventory request is the host OS. This node is for scope in case enclaves are ever targeted for configuration.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>Complete</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>This internal node indicates that the configuration has discrete settings values and is self-contained with complete setting and value pairs that do not contain placeholders that the need to be resolved later with additional data. The request is ready to be processed as is.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>Documents</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>The Documents node indicates that the configuration is in the form of a document, which is a collection of settings used to configure a scenario by the Declared Configuration stack.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>
</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>Uniquely identifies the configuration document. No other document can have this id. The Id should be a GUID.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFTitle>DocID</DFTitle>
<DFType>
<DDFName />
</DFType>
<MSFT:DynamicNodeNaming>
<MSFT:ServerGeneratedUniqueIdentifier />
</MSFT:DynamicNodeNaming>
<MSFT:AllowedValues ValueType="RegEx">
<MSFT:Value>[0-9A-Fa-f]{8}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{12}</MSFT:Value>
</MSFT:AllowedValues>
</DFProperties>
<Node>
<NodeName>Document</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
<Replace />
</AccessType>
<Description>The Document node's value is an XML based document containing a collection of settings and values to configure the specified scenario. The Declared Configuration stack verifies the syntax of the document, the stack marks the document to be processed asynchronously by the client. The stack then returns control back to the OMA-DM service. The stack, in turn, asynchronously processes the request. Below is an example of a specified desired state configuration using the Declared Configuration URI ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Complete/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</Description>
<DFFormat>
<chr />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<MIME />
</DFType>
<MSFT:AllowedValues ValueType="None">
</MSFT:AllowedValues>
</DFProperties>
</Node>
<Node>
<NodeName>Properties</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>The Properties node encapsulates the list of properties that apply to the specified document referenced by [DocID].</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>Abandoned</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
<Replace />
</AccessType>
<DefaultValue>0</DefaultValue>
<Description>The Abandoned node allows the OMA-DM server to indicate that the document is no longer managed.</Description>
<DFFormat>
<int />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<MIME />
</DFType>
<MSFT:AllowedValues ValueType="ENUM">
<MSFT:Enum>
<MSFT:Value>0</MSFT:Value>
<MSFT:ValueDescription>The document is no longer managed.</MSFT:ValueDescription>
</MSFT:Enum>
<MSFT:Enum>
<MSFT:Value>1</MSFT:Value>
<MSFT:ValueDescription>The document is managed.</MSFT:ValueDescription>
</MSFT:Enum>
</MSFT:AllowedValues>
</DFProperties>
</Node>
</Node>
</Node>
</Node>
<Node>
<NodeName>Results</NodeName>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>The Results node indicates that this is part of the URI path that will return an XML document containing the results of the configuration request.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Permanent />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>
</NodeName>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>Uniquely identifies the configuration document in which results of the configuration request will be returned.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFTitle>DocID</DFTitle>
<DFType>
<DDFName />
</DFType>
<MSFT:DynamicNodeNaming>
<MSFT:ClientInventory />
</MSFT:DynamicNodeNaming>
</DFProperties>
<Node>
<NodeName>Document</NodeName>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>The Document node's value is an XML based document containing a collection of setting results from the configuration request specified by [DocId].</Description>
<DFFormat>
<chr />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<MIME />
</DFType>
</DFProperties>
</Node>
</Node>
</Node>
</Node>
<Node>
<NodeName>Inventory</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>The Inventory internal node indicates that this is an inventory request. The setting values to be retrieved are specified in an XML document through the Document leaf node.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>Documents</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>The Documents node indicates that the inventory request is in the form of a document, which is a collection of settings used to retrieve their values.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>
</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
</AccessType>
<Description>Uniquely identifies the inventory document. No other document can have this id. The Id should be a GUID.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFTitle>DocID</DFTitle>
<DFType>
<DDFName />
</DFType>
<MSFT:DynamicNodeNaming>
<MSFT:ServerGeneratedUniqueIdentifier />
</MSFT:DynamicNodeNaming>
<MSFT:AllowedValues ValueType="RegEx">
<MSFT:Value>[0-9A-Fa-f]{8}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{4}\-[0-9A-Fa-f]{12}</MSFT:Value>
</MSFT:AllowedValues>
</DFProperties>
<Node>
<NodeName>Document</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
<Replace />
</AccessType>
<Description>The Document node's value is an XML based document containing a collection of settings that will be used to retrieve their values. The Declared Configuration stack verifies the syntax of the document, the stack marks the document to be processed asynchronously by the client. The stack then returns control back to the OMA-DM service. The stack, in turn, asynchronously processes the request. Below is an example of a specified desired state configuration using the Declared Configuration URI ./Device/Vendor/MSFT/DeclaredConfiguration/Host/Inventory/Documents/27FEA311-68B9-4320-9FC4-296F6FDFAFE2/Document</Description>
<DFFormat>
<chr />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<MIME />
</DFType>
<MSFT:AllowedValues ValueType="None">
</MSFT:AllowedValues>
</DFProperties>
</Node>
</Node>
</Node>
<Node>
<NodeName>Results</NodeName>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>The Results node indicates that this is part of the URI path that will return an XML document containing the results of the inventory request.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Permanent />
</Scope>
<DFType>
<DDFName />
</DFType>
</DFProperties>
<Node>
<NodeName>
</NodeName>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>Uniquely identifies the inventory document. No other document can have this id. The Id should be a GUID.</Description>
<DFFormat>
<node />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFTitle>DocID</DFTitle>
<DFType>
<DDFName />
</DFType>
<MSFT:DynamicNodeNaming>
<MSFT:ClientInventory />
</MSFT:DynamicNodeNaming>
</DFProperties>
<Node>
<NodeName>Document</NodeName>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>The Document node's value is an XML based document containing a collection of setting results from the inventory request specified by [DocId].</Description>
<DFFormat>
<chr />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<MIME />
</DFType>
</DFProperties>
</Node>
</Node>
</Node>
</Node>
</Node>
</Node>
</MgmtTree>
```
## Related articles
[DeclaredConfiguration configuration service provider reference](declaredconfiguration-csp.md)

103
windows/client-management/mdm/dmclient-csp.md
View File

@ -4,7 +4,7 @@ description: Learn more about the DMClient CSP.
author: vinaypamnani-msft
manager: aaroncz
ms.author: vinpa
ms.date: 08/10/2023
ms.date: 09/27/2023
ms.localizationpriority: medium
ms.prod: windows-client
ms.technology: itpro-manage
@ -80,10 +80,10 @@ The following list shows the DMClient configuration service provider nodes:
- [HelpWebsite](#deviceproviderprovideridhelpwebsite)
- [HWDevID](#deviceproviderprovideridhwdevid)
- [LinkedEnrollment](#deviceproviderprovideridlinkedenrollment)
- [DiscoveryEndpoint](#deviceproviderprovideridlinkedenrollmentdiscoveryendpoint)
- [Enroll](#deviceproviderprovideridlinkedenrollmentenroll)
- [EnrollStatus](#deviceproviderprovideridlinkedenrollmentenrollstatus)
- [LastError](#deviceproviderprovideridlinkedenrollmentlasterror)
- [Priority](#deviceproviderprovideridlinkedenrollmentpriority)
- [Unenroll](#deviceproviderprovideridlinkedenrollmentunenroll)
- [ManagementServerAddressList](#deviceproviderprovideridmanagementserveraddresslist)
- [ManagementServerToUpgradeTo](#deviceproviderprovideridmanagementservertoupgradeto)
@ -2411,6 +2411,45 @@ The interior node for linked enrollment.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Begin -->
##### Device/Provider/{ProviderID}/LinkedEnrollment/DiscoveryEndpoint
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Applicability-Begin -->
| Scope | Editions | Applicable OS |
|:--|:--|:--|
| ✅ Device <br> ❌ User | ✅ Pro <br> ✅ Enterprise <br> ✅ Education <br> ✅ Windows SE <br> ✅ IoT Enterprise / IoT Enterprise LTSC | ✅ Windows Insider Preview |
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Applicability-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-OmaUri-Begin -->
```Device
./Device/Vendor/MSFT/DMClient/Provider/{ProviderID}/LinkedEnrollment/DiscoveryEndpoint
```
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-OmaUri-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Description-Begin -->
<!-- Description-Source-DDF -->
Endpoint Discovery is the process where a specific URL (the "discovery endpoint") is accessed, which returns a directory of endpoints for using the system including enrollment. On Get, if the endpoint isn't set, client will return an rmpty string with S_OK.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Description-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Editable-Begin -->
<!-- Add any additional information about this policy here. Anything outside this section will get overwritten. -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Editable-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-DFProperties-Begin -->
**Description framework properties**:
| Property name | Property value |
|:--|:--|
| Format | `chr` (string) |
| Access Type | Add, Delete, Get, Replace |
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-DFProperties-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Examples-Begin -->
<!-- Add any examples for this policy here. Examples outside this section will get overwritten. -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-Examples-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-DiscoveryEndpoint-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Enroll-Begin -->
##### Device/Provider/{ProviderID}/LinkedEnrollment/Enroll
@ -2428,12 +2467,12 @@ The interior node for linked enrollment.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Enroll-Description-Begin -->
<!-- Description-Source-DDF -->
Trigger to enroll for the Linked Enrollment.
This is an execution node and will trigger a silent Declared Configuration unenroll, there is no user interaction needed. On un-enrollment, all the settings/resources set by Declared Configuration will be rolled back (rollback details will be covered later).
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Enroll-Description-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Enroll-Editable-Begin -->
<!-- Add any additional information about this policy here. Anything outside this section will get overwritten. -->
This is an execution node and will trigger a silent MMP-C enrollment, using the Azure Active Directory device token pulled from the Azure AD-joined device. There is no user interaction needed.
This is an execution node and will trigger a silent Declared Configuration enrollment, using the AAD device token pulled from the Azure AD-joined device. There is no user interaction needed. When the **DiscoveryEndpoint** is not set, the Enroll node will fail with `ERROR_FILE_NOT_FOUND (0x80070002)` and there is no scheduled task created for dual enrollment.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Enroll-Editable-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Enroll-DFProperties-Begin -->
@ -2468,7 +2507,7 @@ This is an execution node and will trigger a silent MMP-C enrollment, using the
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-EnrollStatus-Description-Begin -->
<!-- Description-Source-DDF -->
Returns the current enrollment or un-enrollment status of the linked enrollment.
Returns the current enrollment or un-enrollment status of the linked enrollment. Supports Get only.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-EnrollStatus-Description-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-EnrollStatus-Editable-Begin -->
@ -2523,7 +2562,7 @@ Returns the current enrollment or un-enrollment status of the linked enrollment.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-LastError-Description-Begin -->
<!-- Description-Source-DDF -->
return the last error for enroll/unenroll.
Supports Get Only. Returns the HRESULT for the last error when enroll/unenroll fails.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-LastError-Description-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-LastError-Editable-Begin -->
@ -2545,54 +2584,6 @@ return the last error for enroll/unenroll.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-LastError-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Begin -->
##### Device/Provider/{ProviderID}/LinkedEnrollment/Priority
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Applicability-Begin -->
| Scope | Editions | Applicable OS |
|:--|:--|:--|
| ✅ Device <br> ❌ User | ✅ Pro <br> ✅ Enterprise <br> ✅ Education <br> ✅ Windows SE <br> ✅ IoT Enterprise / IoT Enterprise LTSC | ✅ Windows 10, version 2009 [10.0.19042.2193] and later <br> ✅ Windows 10, version 21H1 [10.0.19043.2193] and later <br> ✅ Windows 10, version 21H2 [10.0.19044.2193] and later <br> ✅ Windows 11, version 21H2 [10.0.22000.918] and later <br> ✅ Windows 11, version 22H2 [10.0.22621] and later |
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Applicability-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-OmaUri-Begin -->
```Device
./Device/Vendor/MSFT/DMClient/Provider/{ProviderID}/LinkedEnrollment/Priority
```
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-OmaUri-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Description-Begin -->
<!-- Description-Source-DDF -->
Optional. Allowed value is 0 or 1. 0 means the main enrollment has authority for MDM settings and resources, 1 means the linked enrollment has authority.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Description-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Editable-Begin -->
<!-- Add any additional information about this policy here. Anything outside this section will get overwritten. -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Editable-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-DFProperties-Begin -->
**Description framework properties**:
| Property name | Property value |
|:--|:--|
| Format | `int` |
| Access Type | Add, Delete, Get, Replace |
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-DFProperties-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-AllowedValues-Begin -->
**Allowed values**:
| Value | Description |
|:--|:--|
| 0 | The main enrollment has priority over linked enrollment. |
| 1 | The linked enrollment has priority over the main enrollment. |
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-AllowedValues-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Examples-Begin -->
<!-- Add any examples for this policy here. Examples outside this section will get overwritten. -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-Examples-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Priority-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Unenroll-Begin -->
##### Device/Provider/{ProviderID}/LinkedEnrollment/Unenroll
@ -2615,7 +2606,7 @@ Trigger Unenroll for the Linked Enrollment.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Unenroll-Editable-Begin -->
<!-- Add any additional information about this policy here. Anything outside this section will get overwritten. -->
This is an execution node and will trigger a silent MMP-C unenroll, there is no user interaction needed. On un-enrollment, all the settings/resources set by MMPC will be rolled back.
This is an execution node and will trigger a silent Declared Configuration unenroll, without any user interaction. On un-enrollment, all the settings/resources set by Declared Configuration will be rolled back.
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Unenroll-Editable-End -->
<!-- Device-Provider-{ProviderID}-LinkedEnrollment-Unenroll-DFProperties-Begin -->
@ -3973,7 +3964,7 @@ The following SyncML shows how to remotely unenroll the device. This command sho
<LocURI>./Vendor/MSFT/DMClient/Provider/<ProviderID>/Unenroll</LocURI>
</Target>
<Meta>
<Format xmlns=”syncml:metinf”>chr</Format>
<Format xmlns="syncml:metinf">chr</Format>
</Meta>
<Data>TestMDMServer</Data>
<!-- Data Field in Threshold is now IGNORED -->

72
windows/client-management/mdm/dmclient-ddf-file.md
View File

@ -4,7 +4,7 @@ description: View the XML file containing the device description framework (DDF)
author: vinaypamnani-msft
manager: aaroncz
ms.author: vinpa
ms.date: 06/02/2023
ms.date: 09/27/2023
ms.localizationpriority: medium
ms.prod: windows-client
ms.technology: itpro-manage
@ -2548,47 +2548,13 @@ The following XML file contains the device description framework (DDF) for the D
<MSFT:CspVersion>1.6</MSFT:CspVersion>
</MSFT:Applicability>
</DFProperties>
<Node>
<NodeName>Priority</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
<Replace />
</AccessType>
<Description>Optional. Allowed value is 0 or 1. 0 means the main enrollment has authority for mdm settings and resources, 1 means the linked enrollment has authority.</Description>
<DFFormat>
<int />
</DFFormat>
<Occurrence>
<ZeroOrOne />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<MIME />
</DFType>
<MSFT:AllowedValues ValueType="ENUM">
<MSFT:Enum>
<MSFT:Value>0</MSFT:Value>
<MSFT:ValueDescription>The main enrollment has priority over linked enrollment.</MSFT:ValueDescription>
</MSFT:Enum>
<MSFT:Enum>
<MSFT:Value>1</MSFT:Value>
<MSFT:ValueDescription>The linked enrollment has priority over the main enrollment.</MSFT:ValueDescription>
</MSFT:Enum>
</MSFT:AllowedValues>
</DFProperties>
</Node>
<Node>
<NodeName>LastError</NodeName>
<DFProperties>
<AccessType>
<Get />
</AccessType>
<Description>return the last error for enroll/unenroll.</Description>
<Description>Supports Get Only. Returns the HRESULT for the last error when enroll/unenroll fails.</Description>
<DFFormat>
<int />
</DFFormat>
@ -2609,7 +2575,7 @@ The following XML file contains the device description framework (DDF) for the D
<AccessType>
<Get />
</AccessType>
<Description>Returns the current enrollment or un-enrollment status of the linked enrollment.</Description>
<Description>Returns the current enrollment or un-enrollment status of the linked enrollment. Supports Get only.</Description>
<DFFormat>
<int />
</DFFormat>
@ -2668,7 +2634,7 @@ The following XML file contains the device description framework (DDF) for the D
<AccessType>
<Exec />
</AccessType>
<Description>Trigger to enroll for the Linked Enrollment</Description>
<Description>This is an execution node and will trigger a silent Declared Configuration unenroll, there is no user interaction needed. On un-enrollment, all the settings/resources set by Declared Configuration will be rolled back (rollback details will be covered later).</Description>
<DFFormat>
<null />
</DFFormat>
@ -2704,6 +2670,36 @@ The following XML file contains the device description framework (DDF) for the D
</DFType>
</DFProperties>
</Node>
<Node>
<NodeName>DiscoveryEndpoint</NodeName>
<DFProperties>
<AccessType>
<Add />
<Delete />
<Get />
<Replace />
</AccessType>
<Description>Endpoint Discovery is the process where a specific URL (the "discovery endpoint") is accessed, which returns a directory of endpoints for using the system including enrollment. On Get, if the endpoint is not set, client will return an rmpty string with S_OK. </Description>
<DFFormat>
<chr />
</DFFormat>
<Occurrence>
<One />
</Occurrence>
<Scope>
<Dynamic />
</Scope>
<DFType>
<MIME />
</DFType>
<MSFT:Applicability>
<MSFT:OsBuildVersion>99.9.99999</MSFT:OsBuildVersion>
<MSFT:CspVersion>9.9</MSFT:CspVersion>
</MSFT:Applicability>
<MSFT:AllowedValues ValueType="None">
</MSFT:AllowedValues>
</DFProperties>
</Node>
</Node>
<Node>
<NodeName>MultipleSession</NodeName>

2
windows/client-management/mdm/includes/mdm-insider-csp-note.md
View File

@ -7,4 +7,4 @@ ms.date: 05/09/2023
---
> [!IMPORTANT]
> This CSP contains preview policies that are under development and only applicable for [Windows Insider Preview builds](/windows-insider/). These policies are subject to change and may have dependencies on other features or services in preview.
> This CSP contains some settings that are under development and only applicable for [Windows Insider Preview builds](/windows-insider/). These settings are subject to change and may have dependencies on other features or services in preview.

14
windows/client-management/mdm/toc.yml
View File

@ -29,6 +29,15 @@ items:
href: ../structure-of-oma-dm-provisioning-files.md
- name: Server requirements for OMA DM
href: ../server-requirements-windows-mdm.md
- name: Declared Configuration protocol
href: ../declared-configuration.md
items:
- name: Declared Configuration extensibility
href: ../declared-configuration-extensibility.md
- name: DeclaredConfiguration CSP
href: declaredconfiguration-csp.md
- name: DMClient CSP
href: dmclient-csp.md
- name: Configuration service providers (CSPs)
expanded: true
items:
@ -652,6 +661,11 @@ items:
items:
- name: CustomDeviceUI DDF file
href: customdeviceui-ddf.md
- name: DeclaredConfiguration
href: declaredconfiguration-csp.md
items:
- name: DeclaredConfiguration DDF file
href: declaredconfiguration-ddf-file.md
- name: Defender
href: defender-csp.md
items: