mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-06-15 18:33:43 +00:00
Some changes
This commit is contained in:
Vinay Pamnani
@ -49,22 +49,22 @@ uint32 SetTargetResource(
|
||||
|
||||
## Author DSC 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 generating the source code for MI interface using Convert-MofToProvider.exe tool to generate the DLL and prepare it for placement.
|
||||
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 generating the source code for MI interface using `Convert-MofToProvider.exe` tool to generate the DLL and prepare it for placement.
|
||||
|
||||
1. Create a MOF file that defines the schema for DSC 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 provided tools directory, i.e. ProviderGenerationTool.
|
||||
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 provider's project files.
|
||||
5. Copy the generated files into the provider's project folder.
|
||||
6. Start the development process.
|
||||
|
||||
### Example
|
||||
## Example
|
||||
|
||||
This example shows how to generate the initial source code for a sample resource.
|
||||
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 File in MOF Format
|
||||
|
||||
This is the sample schema MOF file used to generate the initial source code for the `MSFT_FileDirectoryConfiguration` native resource.
|
||||
Create a sample schema MOF file used to generate the initial source code for the `MSFT_FileDirectoryConfiguration` native resource and place it in the project directory named `MSFT_FileDirectoryConfiguration`.
|
||||
|
||||
```mof
|
||||
#pragma include ("cim_schema_2.26.0.mof")
|
||||
@ -124,26 +124,26 @@ class MSFT_FileDirectoryConfiguration : OMI_BaseResource
|
||||
};
|
||||
```
|
||||
|
||||
Note the following about the schema MOF files:
|
||||
|
||||
- Class name and DLL file name should be the same; as defined in `Provider.DEF` file.
|
||||
- The type qualifier, `[Key]`, on a property indicates that this property will uniquely identify the resource instance. At least one `[Key]` property is required.
|
||||
- The `[Required]` qualifier indicates that the property is required (a value must be specified in any configuration script that uses this resource).
|
||||
- The `[write]` qualifier indicates that this property is optional when using the custom resource in a configuration script. The `[read]` qualifier indicates that a property cannot be set by a configuration, and is for reporting purposes only.
|
||||
- `[Values]` qualifier restricts the values that can be assigned to the property to the list of values defined 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.
|
||||
> [!NOTE]
|
||||
>
|
||||
> - Class name and DLL file name should be the same; as defined in `Provider.DEF` file.
|
||||
> - The type qualifier, `[Key]`, on a property indicates that this property will uniquely identify the resource instance. At least one `[Key]` property is required.
|
||||
> - The `[Required]` qualifier indicates that the property is required (a value must be specified in any configuration script that uses this resource).
|
||||
> - The `[write]` qualifier indicates that this property is optional when using the custom resource in a configuration script. The `[read]` qualifier indicates that a property cannot be set by a configuration, and is for reporting purposes only.
|
||||
> - `[Values]` qualifier restricts the values that can be assigned to the property to the list of values defined 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 all the required files and folders to the project directory:
|
||||
Copy these required files and folders to the project directory you created in step 1:
|
||||
|
||||
- CIM-2.26.0
|
||||
- codegen.cmd
|
||||
@ -155,14 +155,14 @@ Copy all the required files and folders to the project directory:
|
||||
- Provider.DEF
|
||||
- wmicodegen.dll
|
||||
|
||||
For more information, see [How to Implement an MI Provider](/previous-versions/windows/desktop/wmi_v2/how-to-implement-an-mi-provider).
|
||||
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: This is the file that was created in step 1.
|
||||
- Provider.DEF: This file contains the DLL name, e.g. `MSFT_FileDirectoryConfiguration.dll`.
|
||||
- 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
|
||||
@ -179,17 +179,18 @@ Modify the following files in the project directory:
|
||||
|
||||
### Step 4: Invoke the provider generator tool
|
||||
|
||||
Run `codegen.cmd` which invokes the `convert-moftoprovider.exe` command. Alternatively, you can run the command directly.
|
||||
Run `codegen.cmd`, which invokes the `convert-moftoprovider.exe` command. Alternatively, you can run the command directly.
|
||||
|
||||
### Step 5: Copy generated source files
|
||||
|
||||
This example uses a `temp` folder that was specified as `-OutPath` parameter in the command from step 3 as the output and renames it to `MSFT_FileDirectoryConfiguration`. This is useful when resource parameters in the schema MOF file are modified. Because with each update to the schema MOF file, the codegen.cmd script to regenerate the source files must be executed again and this tool will overwrite the source files if they exist. So, to prevent that from overwriting the implementation, a temporary folder could be used.
|
||||
Copy the generated files from the `temp` folder that was specified with `-OutPath` parameter in the command from step 3 to the project directory you created in step 1.
|
||||
|
||||
Moreover, it is best to minimize the updates to the schema MOF file since the main implementation should be merged with the most recent auto-generated source files.
|
||||
> [!NOTE]
|
||||
> With each update to the schema MOF file, `codegen.cmd` script to regenerate the source files must be executed again, which overwrites the source files if they exist. To prevent this, this example uses a temporary folder. It is best to minimize the updates to the schema MOF file since the main implementation should be merged with the most recent auto-generated source files.
|
||||
|
||||
### Example MSFT_FileDirectoryConfiguration Resource
|
||||
### Auto-generated MSFT_FileDirectoryConfiguration Resource
|
||||
|
||||
After running the provider generator tool, it creates several source and header files including:
|
||||
After you run the provider generator tool, several source and header files are created, including:
|
||||
|
||||
- MSFT_FileDirectoryConfiguration.c
|
||||
- MSFT_FileDirectoryConfiguration.h
|
||||
@ -215,13 +216,13 @@ From these three functions, only MSFT_FileDirectoryConfiguration_Invoke_GetTarge
|
||||
- MSFT_FileDirectoryConfiguration_ModifyInstance
|
||||
- MSFT_FileDirectoryConfiguration_DeleteInstance
|
||||
|
||||
### Details on MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
|
||||
### About MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource
|
||||
|
||||
MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource performs these steps to complete its task:
|
||||
MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource function performs these 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 will be used as the output of the Get method. This instance is of type MSFT_FileDirectoryConfiguration which is derived from MI_Instance.
|
||||
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
|
||||
@ -230,7 +231,7 @@ MSFT_FileDirectoryConfiguration_Invoke_GetTargetResource performs these steps to
|
||||
- MSFT_FileDirectoryConfiguration_GetTargetResource_Post
|
||||
- MSFT_FileDirectoryConfiguration_GetTargetResource_Destruct
|
||||
|
||||
1. Make sure to clean up, e.g. free allocated memory.
|
||||
1. Clean up resources, for example, free allocated memory.
|
||||
|
||||
## MI implementation references
|
||||
|
||||
|
||||
@ -9,17 +9,17 @@ ms.topic: overview
|
||||
|
||||
The Declared Configuration protocol is based on a desired state device configuration model though it still utilizes the underlying OMA-DM and Syncml protocol. Through a dedicated OMA-DM server, it provides all the settings in a single batch through this new 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 completely 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. The new 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).
|
||||
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. The new 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 new [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 is very efficient and accurate, especially given it is the responsibility of the Declared Configuration client to configure the device. The efficiency of Declared Configuration is in the fact that the batch of scenario settings are processed by the client asynchronously, freeing 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 intimate knowledge of the configuration surface area of the device including the proper handling of continuous device updates affecting the configuration 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 in the fact that the batches of scenario settings are processed by the client asynchronously, freeing 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 intimate knowledge of the configuration surface area of the device including the proper handling of continuous device updates affecting 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 Declared Configuration dual enrollment is managed by new DMClient CSP nodes which are shown below:
|
||||
[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 Declared Configuration dual enrollment is performed by new DMClient CSP nodes, which are listed here:
|
||||
|
||||
- [LinkedEnrollment/Priority](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentpriority)
|
||||
- [LinkedEnrollment/Enroll](mdm/dmclient-csp.md#deviceproviderprovideridlinkedenrollmentenroll)
|
||||
|
||||
Reference in New Issue
Block a user