This section explains how you can take a Microsoft365DSC configuration file you have written (or captured using the snapshot feature) and apply the settings it defines onto a Microsoft 365 tenant. It is very important to understand that at this stage, we are using PowerShell Desired State (DSC) out-of-the-box and that the process of applying a DSC configuration is not something specific to Microsoft365DSC.
Creating your own DSC Configuration¶
Microsoft365DSC is build on top of the PowerShell Desired State Configuration framework. Before you get started with Microsoft365DSC, it is therefore important to know the basics and best practices of PowerShell Desired State Configuration (DSC). Here a small introduction into PowerShell DSC:
PowerShell DSC is a declarative approach for configuring servers and environments. It is based on the Open Management Infrastructure (implemented in Windows as WMI). PowerShell offers a way to declare a desired state in PowerShell syntax, compile this to a so called MOF file and publish that to a target machine.
On that target machine the Local Configuration Manager will to the heavy lifting and make sure you server gets into the desired state, it is detected when the server deviates from the desired state or even automatically corrected back to the desired state.
To create and deploy your own Desired State:
- You create a DSC Configuration
- You compile your PowerShell configuration to a MOF file (see paragraph below)
- Last you apply the MOF file to your target server (see paragraph below)
We highly recommend that you watch the "Getting Started with PowerShell Desired State Configuration" training on Microsoft Learn.
For more information and more advanced topics, please make sure you review the following articles:
- Add Parameters to a Configuration
- Separating configuration and environment data
- Using configuration data in DSC
- Want to secure credentials in Windows PowerShell Desired State Configuration?
- Securing the MOF File
- Securing your Compiled Configuration (Next chapter in this guide)
Compiling and Validating the Configuration¶
The first step in trying to deploy a DSC configuration is to compile the configuration file into what is called a Managed Object Format (MOF) file. To do so, simply execute the .ps1 file that contains your configuration. The process of compiling your configuration will also perform some level of validation on the configuration such as ensuring that every component defined in the file has all of their mandatory parameters defined and that there are no typos in components or property names. If the compilation process is successful, you should see a mention that the .mof file was created. This file gets created in the same location where your configuration file is located by default and will create a new folder based on the name of the configuration object defined within your file.
Deploying the Configuration¶
To initiate the deployment of a MOF file onto a Microsoft 365 tenant, you need to use the out-of-the-box cmdlet provided by PowerShell DSC named Start-DSCConfiguration. By default, this cmdlet will execute as a background job. If you wish to monitor the execution of the process, you need to use the -Wait switch, which will make the process synchronous. We also recommend using the -Verbose switch with the command to get additional details on the progression of the process. The cmdlet takes in the path to the folder that contains the compiled .MOF file. For example:
Start-DSCConfiguration -Path C:\DemoM365DSC\M365TenantConfig -Wait -Verbose -Force
Executing the cmdlet will automatically authenticate against the affected workload using the authentication parameters provided at compilation time and will apply the configuration settings defined in the file.
It is normal for this process to take several minutes if not hours to complete, based on how many components are defined in your configuration. It is important to understand that once the configuration completes its deployment, this will configure the PowerShell DSC engine on the current system to perform frequent checks against your Microsoft 365 tenant to check for configuration drifts. By default, the engine will wake up every 15 minutes (minimum value possible). For more details on how to configure this, please refer to Configuring the Local Configuration Manager.
If you simply want to apply the configuration on the tenant as a one off and prevent the system form doing frequent checks for configuration drifts, you can remove the configuration you have applied from memory by running the following PowerShell commands:
Stop-DSCConfiguration -Force Remove-DSCConfigurationDocument -Stage Current