Invoke-DscResource: Your Gateway to Learning DSC in PowerShell

Prior to Windows Management Framework (WMF) v5, people that wanted to use Desired State Configuration (DSC) in PowerShell to apply configurations to their machines were forced to go through the same procedure if they wanted to provision an entire server or just install a single Windows feature. That’s no more with the Invoke-DscResource cmdlet.

To use DSC, you typically have to:

1. Create the DSC configuration script
2. Compile the script into a MOF file
3. Deliver the MOF file somehow to the machine
4. Invoke the Local Configuration Manager (LCM) to consume that MOF
   file

This process works, but there are times when you’d rather not going through all the hassle of building a configuration in the first place. Wouldn’t it be nice if you just want to apply a minor change via DSC without having to create a configuration and deal with a MOF file? That’s what the PowerShell Team gave us in WMF 5.0 in the form of the Invoke-DscResource command.

In this article, we’re going to cover the difference between building a configuration to install a single Windows feature on the local machine and doing so via Invoke DscResource to see the difference in these two approaches.

Building and Applying a DSC Configuration

Let’s first enable the telnet client Windows feature via the “old-fashioned” way of creating a configuration, delivering the MOF and telling the LCM to consume the MOF. To do so, we’ll start out with a simple DSC configuration.

Configuration InstallWindowsFeature {
    param()
    Node 'localhost' {
        WindowsFeature 'TelnetClient' {
            Ensure = 'Present'
            Name = 'Telnet-Client'
        }
    }
}
InstallWindowsFeature

Once we’ve got the configuration built, we’ll then convert this into a MOF file that the LCM can understand by executing the script. This gives us a localhost.mof file.

Once we’ve got the MOF file, I can now run Start-DscConfigurationManager
to tell the LCM it has a new configuration to process.

The Telnet-Client Windows feature is now under the control of DSC.

Using the DSC in PowerShell Cmdlet Invoke-DscResource

Let’s now see how this is done by just using the Invoke-DscResource command with DSC in PowerShell.

PS> Invoke-DscResource -Name WindowsFeature -Method Set -Property @{Name ='Telnet-Client'} -Verbose -ModuleName PSDesiredStateConfiguration

Done.

Well, not technically but you get the point here. Invoke-DscResource can forego the configuration and MOF manipulation all together and allow you to invoke the Get, Set, and Test methods manually. It gives you granular control over the DSC resources.

Notice by using this method though that you’re not getting one of the biggest benefits of DSC which is the “set it and forget it” mentality. At this point, you are taking on the responsibility that the LCM previously had by running the Test method first to see what kind of state the machine is in and then, and only then, running the Set method if the machine is not in the desired state.

Technically, using Invoke-DscResource like below would be the same workflow that the LCM goes through when applied via a configuration.

$commonParams = @{
    Name = 'WindowsFeature'
    Property = @{ Name = 'Telnet-Client' }
    ModuleName = 'PSDesiredStateConfiguration'
    Verbose = $true
}

$state = Invoke-DscResource @commonParams -Method Test

if (-not $state.InDesiredState) {
    Invoke-DscResource @commonParams -Method Set
}

When this is run, you’ll see that the Test method is run first and only if the LCM detects that the machine isn’t in the correct state that the Set method will then run.

Note that when using Invoke-DscResource in a larger capacity Microsoft recommends disabling the LCM. After all, you are replacing what the LCM does when calling methods directly, so this makes sense. Although Invoke-DscResource will work while the LCM is enabled, you’ll find that your scripts referencing Invoke-DscResource will begin to fight with the automatic nature of the LCM.

Summary

If you’re tired of building DSC configurations and just want to get the job done, the Invoke-DscResource command may be for you. This command is great at simple DSC configuration changes. If you find yourself beginning to write DSC scripts like PowerShell though without the idempotency that DSC provides, you should probably start looking into configurations though.