Skip to main content

​
Overview

ConfigurationUnit represents a single unit of configuration - the smallest actionable configuration element. Each unit describes a specific aspect of system configuration, such as installing a package, setting a registry key, or configuring a service.

​
Class Definition

runtimeclass ConfigurationUnit
{
    ConfigurationUnit();
    
    // Identification
    String Type;
    Guid InstanceIdentifier { get; };
    String Identifier;
    
    // Behavior
    ConfigurationUnitIntent Intent;
    IVector<String> Dependencies;
    Boolean IsActive;
    
    // Data
    ValueSet Metadata;
    ValueSet Settings;
    
    // Details
    IConfigurationUnitProcessorDetails Details { get; };
    
    // State
    ConfigurationUnitState State { get; };
    IConfigurationUnitResultInformation ResultInformation { get; };
    
    // Grouping
    Boolean IsGroup;
    IVector<ConfigurationUnit> Units;
    
    // Environment
    ConfigurationEnvironment Environment { get; };
    
    // Operations
    ConfigurationUnit Copy();
}

​
Properties

​
Type

​
Type
String
required
The type of configuration unit (e.g., “Microsoft.WinGet.DSC/WinGetPackage”).
The Type identifies which DSC resource or configuration handler processes this unit. 
var unit = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Identifier = "installVSCode",
    Intent = ConfigurationUnitIntent.Apply
};

unit.Settings["Id"] = "Microsoft.VisualStudioCode";
unit.Settings["Source"] = "winget";

​
Identifier

​
Identifier
String
Unique identifier for this unit within the configuration set.
Used by other units to reference this unit in their Dependencies. 
var unit1 = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Identifier = "installGit"
};

var unit2 = new ConfigurationUnit()
{
    Type = "PSDscResources/Environment",
    Identifier = "setGitPath"
};

// unit2 depends on unit1
unit2.Dependencies.Add("installGit");

​
Intent

​
Intent
ConfigurationUnitIntent
required
Defines how the unit is used within the configuration system.
ConfigurationUnitIntent values:
  • Assert - Only test the current state (don’t modify)
  • Inform - Only get the current state
  • Apply - Test, get, and set the desired state
// Apply intent: will modify system
var applyUnit = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Intent = ConfigurationUnitIntent.Apply
};
applyUnit.Settings["Id"] = "Microsoft.PowerToys";

// Assert intent: only test (won't install)
var assertUnit = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Intent = ConfigurationUnitIntent.Assert
};
assertUnit.Settings["Id"] = "Git.Git";

// Inform intent: only get current state
var informUnit = new ConfigurationUnit()
{
    Type = "PSDscResources/Registry",
    Intent = ConfigurationUnitIntent.Inform
};
informUnit.Settings["Key"] = @"HKLM\Software\MyApp";

​
Dependencies

​
Dependencies
IVector<String>
Identifiers of configuration units that this unit depends on.
Dependencies are processed before this unit. 
var unit = new ConfigurationUnit()
{
    Type = "PSDscResources/Script",
    Identifier = "setupApp"
};

// This unit depends on multiple other units
unit.Dependencies.Add("installGit");
unit.Dependencies.Add("installNode");
unit.Dependencies.Add("installVSCode");

unit.Settings["GetScript"] = "return @{ Result = 'Ready' }";
unit.Settings["SetScript"] = "# Setup application";
unit.Settings["TestScript"] = "return $false";

​
Settings

​
Settings
ValueSet
required
Configuration unit-specific settings.
Settings define the desired state for this configuration unit. The structure depends on the unit Type. 
// WinGet package settings
var packageUnit = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage"
};

packageUnit.Settings["Id"] = "Microsoft.PowerToys";
packageUnit.Settings["Source"] = "winget";
packageUnit.Settings["Version"] = "0.75.0";

// Registry settings
var registryUnit = new ConfigurationUnit()
{
    Type = "PSDscResources/Registry"
};

registryUnit.Settings["Key"] = @"HKCU\Software\MyApp";
registryUnit.Settings["ValueName"] = "InstallPath";
registryUnit.Settings["ValueData"] = @"C:\Program Files\MyApp";
registryUnit.Settings["ValueType"] = "String";
registryUnit.Settings["Ensure"] = "Present";

// File settings
var fileUnit = new ConfigurationUnit()
{
    Type = "PSDscResources/File"
};

fileUnit.Settings["DestinationPath"] = @"C:\Configs\app.config";
fileUnit.Settings["Contents"] = "setting1=value1\nsetting2=value2";
fileUnit.Settings["Ensure"] = "Present";

​
Metadata

​
Metadata
ValueSet
Additional metadata about the configuration unit.
var unit = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage"
};

// Add metadata
unit.Metadata["description"] = "Install Visual Studio Code";
unit.Metadata["module"] = "Microsoft.WinGet.DSC";
unit.Metadata["version"] = "1.0";

​
State

​
State
ConfigurationUnitState
Current state of the configuration unit.
ConfigurationUnitState values:
  • Unknown - State unknown (not applied)
  • Pending - Queued but not started
  • InProgress - Currently being applied
  • Completed - Application completed
  • Skipped - Skipped due to external factors
foreach (var unit in configSet.Units)
{
    Console.WriteLine($"{unit.Type}: {unit.State}");
    
    if (unit.State == ConfigurationUnitState.Completed)
    {
        var result = unit.ResultInformation;
        if (result.ResultCode == 0)
        {
            Console.WriteLine("  Success");
        }
        else
        {
            Console.WriteLine($"  Failed: {result.Description}");
        }
    }
    else if (unit.State == ConfigurationUnitState.Skipped)
    {
        Console.WriteLine($"  Skipped: {unit.ResultInformation.Description}");
    }
}

​
IsActive

​
IsActive
Boolean
default:"true"
Controls whether this unit is processed when the set is applied.
// Disable a unit temporarily
var unit = configSet.Units.First(u => u.Identifier == "optionalFeature");
unit.IsActive = false;

// This unit will be skipped during apply
var result = await processor.ApplySetAsync(configSet, ApplyConfigurationSetFlags.None);

​
Details

​
Details
IConfigurationUnitProcessorDetails
Detailed information about the configuration unit processor.
Details are populated by calling ConfigurationProcessor.GetSetDetailsAsync() or GetUnitDetailsAsync(). 
// Get details for a unit
var detailsResult = await processor.GetUnitDetailsAsync(
    unit,
    ConfigurationUnitDetailFlags.Load
);

if (detailsResult.Details != null)
{
    var details = detailsResult.Details;
    
    Console.WriteLine($"Unit Type: {details.UnitType}");
    Console.WriteLine($"Description: {details.UnitDescription}");
    Console.WriteLine($"Module: {details.ModuleName}");
    Console.WriteLine($"Version: {details.Version}");
    Console.WriteLine($"Author: {details.Author}");
    Console.WriteLine($"Publisher: {details.Publisher}");
    
    if (details.UnitDocumentationUri != null)
    {
        Console.WriteLine($"Documentation: {details.UnitDocumentationUri}");
    }
    
    Console.WriteLine("\nSettings:");
    foreach (var setting in details.Settings)
    {
        Console.WriteLine($"  {setting.Identifier}:");
        Console.WriteLine($"    Type: {setting.Type}");
        Console.WriteLine($"    Description: {setting.Description}");
        Console.WriteLine($"    Required: {setting.IsRequired}");
        Console.WriteLine($"    Is Key: {setting.IsKey}");
    }
}

​
IsGroup and Units

​
IsGroup
Boolean
default:"false"
Indicates if this unit is a group containing child units.
​
Units
IVector<ConfigurationUnit>
Child units when IsGroup is true.
// Create a group unit
var group = new ConfigurationUnit()
{
    Type = "MyModule/Group",
    Identifier = "devTools",
    IsGroup = true
};

// Add child units
group.Units.Add(new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Settings = new ValueSet
    {
        ["Id"] = "Git.Git"
    }
});

group.Units.Add(new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Settings = new ValueSet
    {
        ["Id"] = "Microsoft.VisualStudioCode"
    }
});

configSet.Units.Add(group);

​
Environment

​
Environment
ConfigurationEnvironment
Environment settings for processing this unit.
var unit = new ConfigurationUnit()
{
    Type = "PSDscResources/Registry"
};

// Require elevated privileges
unit.Environment = new ConfigurationEnvironment()
{
    Context = SecurityContext.Elevated,
    ProcessorIdentifier = "pwsh"
};

unit.Settings["Key"] = @"HKLM\Software\MyApp";
unit.Settings["ValueName"] = "InstallPath";
unit.Settings["ValueData"] = @"C:\Program Files\MyApp";

​
Methods

​
Copy()

Creates a copy of the configuration unit.
​
Returns
ConfigurationUnit
New configuration unit with copied values
The copy has a new InstanceIdentifier, empty Identifier, and default State. Settings, Metadata, and Dependencies are copied to new containers.
var original = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Identifier = "installGit",
    Intent = ConfigurationUnitIntent.Apply
};

original.Settings["Id"] = "Git.Git";
original.Metadata["description"] = "Install Git";

var copy = original.Copy();

// Copy has new instance ID and empty identifier
Console.WriteLine($"Original ID: {original.InstanceIdentifier}");
Console.WriteLine($"Copy ID: {copy.InstanceIdentifier}");
Console.WriteLine($"Copy Identifier: '{copy.Identifier}'"); // Empty

// Settings and metadata are copied
Console.WriteLine($"Copy Settings Id: {copy.Settings["Id"]}");
Console.WriteLine($"Copy Metadata: {copy.Metadata["description"]}");

​
Common Configuration Unit Types

​
Microsoft.WinGet.DSC/WinGetPackage

Install, upgrade, or uninstall packages using WinGet. 
var unit = new ConfigurationUnit()
{
    Type = "Microsoft.WinGet.DSC/WinGetPackage",
    Intent = ConfigurationUnitIntent.Apply
};

unit.Settings["Id"] = "Microsoft.PowerToys";
unit.Settings["Source"] = "winget";
unit.Settings["Version"] = "0.75.0"; // Optional: specific version
unit.Settings["Ensure"] = "Present"; // or "Absent" to uninstall

​
PSDscResources/Registry

Manage Windows registry keys and values. 
var unit = new ConfigurationUnit()
{
    Type = "PSDscResources/Registry",
    Intent = ConfigurationUnitIntent.Apply
};

unit.Settings["Key"] = @"HKCU\Software\MyApp";
unit.Settings["ValueName"] = "Theme";
unit.Settings["ValueData"] = "Dark";
unit.Settings["ValueType"] = "String";
unit.Settings["Ensure"] = "Present";

​
PSDscResources/Environment

Manage environment variables. 
var unit = new ConfigurationUnit()
{
    Type = "PSDscResources/Environment",
    Intent = ConfigurationUnitIntent.Apply
};

unit.Settings["Name"] = "DEV_ENV";
unit.Settings["Value"] = "Production";
unit.Settings["Ensure"] = "Present";
unit.Settings["Path"] = false; // Not a PATH variable
unit.Settings["Target"] = new[] { "Process", "User" };

​
PSDscResources/Script

Execute custom PowerShell scripts. 
var unit = new ConfigurationUnit()
{
    Type = "PSDscResources/Script",
    Intent = ConfigurationUnitIntent.Apply
};

unit.Settings["GetScript"] = @"
    return @{ Result = (Test-Path 'C:\MyApp') }
";

unit.Settings["TestScript"] = @"
    return (Test-Path 'C:\MyApp')
";

unit.Settings["SetScript"] = @"
    New-Item -Path 'C:\MyApp' -ItemType Directory -Force
";

Build docs developers (and LLMs) love

Get started for freeTalk to us