Edit

Invoke-DscResource

  • Reference
Module:
PSDesiredStateConfiguration

Runs a method of a specified PowerShell Desired State Configuration (DSC) resource.

Syntax

Invoke-DscResource
      [-Name] <String>
      [[-ModuleName] <ModuleSpecification>]
      [-Method] <String>
      [-Property] <Hashtable>
      [<CommonParameters>]

Description

The Invoke-DscResource cmdlet runs a method of a specified PowerShell Desired State Configuration (DSC) resource.

This cmdlet invokes a DSC resource directly, without creating a configuration document. Using this cmdlet, configuration management products can manage windows or Linux by using DSC resources. This cmdlet also enables debugging of resources when the DSC engine is running with debugging enabled.

Note

Invoke-DscResource is an experimental feature in PowerShell 7. To use the cmdlet, you must enable it using the following command.

Enable-ExperimentalFeature PSDesiredStateConfiguration.InvokeDscResource

Examples

Example 1: Invoke the Set method of a resource by specifying its mandatory properties

This example invokes the Set method of a resource named WindowsProcess and provides the mandatory Path and Arguments properties to start the specified Windows process.

Invoke-DscResource -Name WindowsProcess -Method Set -ModuleName PSDesiredStateConfiguration -Property @{
  Path = 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe'
  Arguments = ''
}

Example 2: Invoke the Test method of a resource for a specified module

This example invokes the Test method of a resource named WindowsProcess, which is in the module named PSDesiredStateConfiguration.

$SplatParam = @{
  Name = 'WindowsProcess'
  ModuleName = 'PSDesiredStateConfiguration'
  Property = @{Path = 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe'; Arguments = ''}
  Method = Test
}

Invoke-DscResource @SplatParam

Parameters

-Method

Specifies the method of the resource that this cmdlet invokes. The acceptable values for this parameter are: Get, Set, and Test.

Type:String
Accepted values:Get, Set, Test
Position:2
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ModuleName

Specifies the name of the module from which this cmdlet invokes the specified resource.

Type:ModuleSpecification
Position:1
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

-Name

Specifies the name of the DSC resource to start.

Type:String
Position:0
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

-Property

Specifies the resource property name and its value in a hash table as key and value, respectively.

Type:Hashtable
Position:3
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Inputs

String

ModuleSpecification

Outputs

Object

Notes

  • Previously, Windows PowerShell 5.1 resources ran under System context unless specified with user context using the key PsDscRunAsCredential. In PowerShell 7.0, Resources run in the user's context, and PsDscRunAsCredential is no longer supported. Previous configurations using this key will throw an exception.

  • As of PowerShell 7, Invoke-DscResource no longer supports invoking WMI DSC resources. This includes the File and Log resources in PSDesiredStateConfiguration.