How to apply a Windows Desired State Configuration package

Deploying Windows devices in an enterprise environment has evolved significantly, especially with the rise of cloud-first strategies and zero-touch provisioning. Windows Autopilot streamlines device setup, but IT admins still face the challenge of ensuring every device meets organizational standards right from the start. This is where a Windows Desired State Configuration (DSC) package comes in.

By applying DSC packages during Windows Autopilot enrollment, IT admins can baseline deployments, remove unnecessary apps, configure essential settings, and deliver a consistent user experience across all Windows devices.

Windows Desired State Configuration packages

A Windows Desired State Configuration package is a deployment artifact that defines and applies a specific configuration state on Windows devices. Think of it as a blueprint that describes how a device should be configured - what apps should be removed, which features should be enabled or disabled, and what settings should be applied.

Image viewer

Image created with help from Microsoft Copilot

Traditionally, device deployment involved manual imaging and post-deployment configuration tasks. Without a standardized approach, devices could end up with unwanted software, inconsistent settings, and varying security postures. This is particularly problematic in Windows Autopilot scenarios where devices come directly from the manufacturer with varying pre-installed software.

A DSC package addresses this by establishing a baseline - a clean starting point that ensures consistency across your device fleet. Unlike policies that enforce configurations users cannot change, a DSC package provides a default state that users may adjust according to their needs.

Benefits of baseline configurations

• Consistency: Every device starts with the same apps and settings
• Efficiency: Automated configuration reduces manual setup time and minimizes errors
• Compliance: Devices align with organizational standards from the start
• Security: Remove unwanted software and apply security hardening out of the box

What can a DSC package configure?

A DSC package can address a wide range of configuration scenarios. The following examples illustrate some common possibilities, though your implementation could include additional configuration artifacts based on organizational requirements:

• App management: Removal of pre-installed apps that don’t align with organizational standards
• Windows features: Enabling or disabling built-in Windows capabilities
• System settings: Registry modifications, service configurations, and security policies
• Localization: Regional settings, timezone, and language preferences
• Branding: OEM information and organizational identity
• Payloads: Deploying files, scripts, or configuration options to the device

There are multiple ways to implement a DSC package, from simple PowerShell scripts to comprehensive solutions with external configuration files. The approach you choose depends on your organization’s complexity, the need for reusability, and maintenance considerations.

Common use cases include standardizing user experience across corporate devices, security hardening by removing trialware and unnecessary services, regulatory compliance (GDPR, HIPAA), and department-specific configurations tailored to HR, Finance, or Engineering needs.

Introducing Windows gecko

To demonstrate these concepts in practice, let me introduce Windows gecko - a community tool I maintain and use in nearly all Windows Autopilot implementations I have been involved in.

GitHub - dotjesper/windows-gecko: This repository contains the …

This repository contains the source code for Windows gecko. Windows gecko is a multifunctional script designed to adapt to various Windows management …

Geckos are small, adapt to the surroundings and have excellent night vision. Like its namesake, Windows gecko is small in size, adapts to multiple Windows management environments, and uses “clicking sounds” (detailed logging) to ensure every step is checked and recorded.

Windows gecko features

Windows gecko is actively maintained with new functionality added regularly. Current features include:

• Windows Apps: Remove Windows In-box Apps and Store Apps.
• Windows Branding: Configure OEM information and Registration (PREVIEW)
• Windows Features:
  • Enable and/or disable Windows features.
  • Enable and/or disable Windows optional features.
• Windows Groups: Add accounts to local groups (Coming soon).
• Windows Files: Copy file(s) to device from payload package.
• Windows Registry: Modifying Windows registry entries (add, change, and remove).
• Windows Run: Run local executables and/or download and run executables.
• Windows Services: Configure/re-configure Windows Services.
• Windows TCR: Windows Time zone, Culture and Regional settings manager (PREVIEW).

Requirements

Windows gecko is developed and tested for Windows 11 24H2 Pro and Enterprise 64-bit/ARM-64, and newer and requires PowerShell 5.1.

Applying a DSC package during Windows Autopilot enrollment

The following steps describe my preferred deployment method: packaging the DSC script as a Win32 app in Microsoft Intune.

This approach provides better control over installation behaviour, detection rules, and assignment options compared to deploying as a platform script. Platform scripts also have a key limitation: they only support a single script file and cannot include configuration files or other payloads.

Step 1: Prepare your DSC configuration

First, create or customize your configuration files. If you’re using Windows gecko, the repository structure looks like this:

📂 solution
├── 📦 assets.zip           # Payload files (optional)
├── 📄 configC.json         # Configuration for SYSTEM context
├── 📄 configU.json         # Configuration for USER context
└── 📜 gecko.ps1            # Main script

Windows gecko solution folder structure

The configuration files (JSON) define what actions the script should perform.

Configuration options for SYSTEM context

The following configuration options are available when running Windows gecko in SYSTEM context (requires local administrative rights):

• Remove pre-installed apps: Use the windowsApps section to remove Windows In-box Apps and Store Apps system-wide (e.g., Xbox, Clipchamp, Microsoft News).
• Configure Windows features: Enable or disable built-in Windows capabilities using the windowsFeatures section.
• Deploy files: Use the windowsFiles section to copy files from the payload package to system locations on the device.
• Registry modifications: Apply registry settings via the windowsRegistry section. SYSTEM context supports both system registry (HKLM) and the default user profile registry, ensuring new users inherit your configured settings.
• Run scripts or executables: Use the windowsRun section to execute local or downloaded scripts/programs with elevated privileges.
• Configure services: Adjust Windows service startup types using the windowsServices section.
• Configure Timezone, Culture, and Regional settings: Use the windowsTCR section to set timezone, locale, and keyboard layout.
• Configure branding: Use the windowsBranding section to set OEM information and registration details.
• Add accounts to local groups: Use the windowsGroups section to manage local group membership (Coming soon).

Configuration options for USER context

The following configuration options are available when running Windows gecko in USER context:

• Remove user-provisioned apps: Use the windowsApps section to remove Store Apps provisioned for the current user.
• Deploy files: Use the windowsFiles section to copy files from the payload package to user-accessible locations.
• Registry modifications: Apply registry settings via the windowsRegistry section. USER context writes to the current user registry (HKCU) only.
• Run scripts or executables: Use the windowsRun section to execute scripts/programs in the user’s security context.
• Configure Timezone, Culture, and Regional settings: Use the windowsTCR section to configure user-specific regional settings, though some options (such as system timezone) require SYSTEM context.

Step 2: Create the .intunewin package

To deploy the DSC package via Microsoft Intune, you need to wrap the PowerShell script and payload files into an .intunewin package using the Microsoft Win32 Content Prep Tool .

1. Download the IntuneWinAppUtil.exe  tool.

2. Organize your source files in a folder structure:

   📂 source
   ├── 📜 gecko.ps1
   ├── 📄 configC.json
   └── 📦 assets.zip

3. Run the content prep tool:

   IntuneWinAppUtil.exe -c "C:\source" -s "gecko.ps1" -o "C:\output"

   This creates a gecko.intunewin file ready for upload to Microsoft Intune.

Step 3: Upload the package to Microsoft Intune

1. Sign in to the Microsoft Intune admin center .
2. Navigate to Apps > All apps > Add.
3. Select Windows app (Win32) as the app type.
4. Upload the .intunewin package file.
5. Configure the app information:
   • Name: Windows Desired State Configuration (or similar)
   • Description: Applies baseline configuration to Windows devices
   • Publisher: Your organization

Step 4: Configure the program settings

Configure the install and uninstall commands:

• Install command: powershell.exe -NoLogo -ExecutionPolicy Bypass -File ".\gecko.ps1" -configFile ".\configC.json"
• Uninstall command: powershell.exe -NoLogo -ExecutionPolicy Bypass -File ".\gecko.ps1" -configFile ".\configC.json" -uninstall
• Install behavior: System
• Device restart behavior: No specific action

%SystemRoot%\sysnative\WindowsPowerShell\v1.0\powershell.exe -NoLogo -ExecutionPolicy Bypass -File "gecko.ps1" -configFile "configC.json"

Step 5: Configure detection rules

Create a detection rule to verify successful installation. Options include:

• File-based detection: Check for the existence of a log file or marker file created by the script.
• Registry-based detection: Check for a registry key set by the script upon completion.

Windows gecko uses the Windows uninstall registry area to register each configuration as an installed application. The GUID is defined in the JSON configuration file, allowing each configuration to have its own unique install entry. This approach makes the script multipurpose - you can deploy multiple DSC configurations to the same device, each tracked independently - and is designed to support future uninstall functionality.

Example registry detection rule for Windows gecko:

• Key path: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{your-config-guid}
• Value name: Version
• Detection method: String comparison
• Value: The version defined in your configuration file

The {your-config-guid} should match the guid value within the metadata section specified in your JSON configuration file.

{
  "metadata": {
    "enabled": true,
    "installBehavior": "SYSTEM",
    "guid": "{DC34940C-EAAC-4E24-B84A-B405871451AC}",
    "title": "Windows gecko-DSC-SYSTEM",
    "description": "Windows desired state configuration",
    "url": "",
    "version": "1.7.0.2",
    "date": "2023-11-07",
    "publisher": "dotjesper.com",
    "developer": "Jesper Nielsen"
  },
  "runConditions": {
    "runScriptIn64bitPowerShell": true,
    "requireReboot": false
  }
  ...
}

Example JSON configuration snippet for Windows gecko

Step 6: Assign the package

1. Navigate to the Assignments tab.
2. Under Required, click Add group and select the device groups that should receive the DSC package. For Windows Autopilot scenarios, assign to the same device groups used for your Autopilot deployment profiles.
3. Click Edit assignment (or the three dots) to configure the assignment settings:
   • App availability: Set to As soon as possible to ensure the package downloads during enrollment.
   • App install deadline: Set to As soon as possible.
   • Delivery optimization priority: Set to Content download in foreground to prioritize the download during the Enrollment Status Page.
   • End user notifications: Set to Hide all toast notifications to avoid interrupting the user experience during enrollment.
4. Click OK to save the assignment settings, then Save the assignments.

Step 7: Configure Enrollment Status Page (ESP)

To ensure the DSC package is applied before the user reaches the desktop, configure the Enrollment Status Page:

1. Navigate to Devices > Enrollment > Windows > Enrollment Status Page.
2. Select your ESP profile (or create a new one if needed).
3. Ensure Show app and profile configuration progress is set to Yes.
4. Set Block device use until all apps and profiles are installed to Yes (or use the selective blocking option below).
5. Under Block device use until required apps are installed if they are assigned to the user/device, click Select apps.
6. Add your DSC package (Windows Desired State Configuration) to the blocking apps list.
7. Click Save to apply the ESP configuration.

Monitoring the deployment

After deploying your DSC package, it’s important to verify that installations complete successfully across your device fleet. There are two primary ways to monitor the deployment: through the Microsoft Intune admin center and by reviewing log files on the device.

Microsoft Intune admin center

Monitor the deployment status in the Microsoft Intune admin center:

1. Navigate to Apps > All apps > select your DSC app.
2. Review the Device install status and User install status reports.

Local log files

Windows gecko creates detailed log files for troubleshooting:

• Default log location: %ProgramData%\Microsoft\IntuneManagementExtension\Logs\
• Custom log location: Specify using the -logFile parameter

The Microsoft Intune Management Extension (IME) logs are also helpful:

• %ProgramData%\Microsoft\IntuneManagementExtension\Logs\IntuneManagementExtension.log

Troubleshooting common issues

If you encounter problems when deploying Windows gecko, here are common issues and solutions:

Apps not removed as expected:

• Context mismatch: Ensure you’re running in the correct context (SYSTEM vs USER) for the target apps
• App package names: Verify the package names in your configuration match the actual installed apps
• Timing during Autopilot: The DSC package may run before certain apps are provisioned

Configuration not applied:

• JSON syntax errors: Validate your configuration files are valid JSON
• Permission issues: Ensure the script has sufficient permissions for the requested operations
• Review logs: Check the Windows gecko log file for specific error messages

Best practices

Over the years, I’ve found these practices help ensure successful DSC deployments:

1. Keep configurations modular: Create reusable configuration modules for common tasks to simplify updates and maintenance.
2. Test thoroughly: Validate DSC packages in a staging environment before rolling out to production.
3. Use version control: Store scripts and configuration files in a version-controlled repository to track changes and enable rollback.
4. Code signing: Sign your PowerShell scripts for production deployments to ensure integrity and meet security requirements.
5. Monitor compliance: Use monitoring tools and Microsoft Intune reports to verify devices maintain their desired state.
6. Document configurations: Maintain clear documentation for each DSC package, including the rationale for included settings.

Conclusion

Applying DSC packages during Windows Autopilot enrollment enables IT admins to deliver secure, consistent, and compliant devices from day one. By automating baseline configurations, organizations reduce manual effort, speed up deployments, and ensure every device meets their standards.

GitHub - dotjesper/windows-gecko: This repository contains the …

This repository contains the source code for Windows gecko. Windows gecko is a multifunctional script designed to adapt to various Windows management …

Whether you use Windows gecko or build your own solution, the key is establishing a consistent baseline that aligns with your organization’s requirements. Feel free to fork the project and adapt it to your needs - and reach out if you have questions or suggestions.

–Jesper

Header image attribution: Image created with help from Microsoft Copilot