Set-AzureRmVMDscExtension

Configures the DSC extension on a virtual machine.

Warning

The AzureRM PowerShell module has been officially deprecated as of February 29, 2024. Users are advised to migrate from AzureRM to the Az PowerShell module to ensure continued support and updates.

Although the AzureRM module may still function, it's no longer maintained or supported, placing any continued use at the user's discretion and risk. Please refer to our migration resources for guidance on transitioning to the Az module.

Syntax

Set-AzureRmVMDscExtension
   [-ResourceGroupName] <String>
   [-VMName] <String>
   [-Name <String>]
   [-ArchiveBlobName] <String>
   [-ArchiveStorageAccountName] <String>
   [-ArchiveResourceGroupName <String>]
   [-ArchiveStorageEndpointSuffix <String>]
   [-ArchiveContainerName <String>]
   [-ConfigurationName <String>]
   [-ConfigurationArgument <Hashtable>]
   [-ConfigurationData <String>]
   [-Version] <String>
   [-Force]
   [-Location <String>]
   [-AutoUpdate]
   [-WmfVersion <String>]
   [-DataCollection <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The Set-AzureRmVMDscExtension cmdlet configures the Windows PowerShell Desired State Configuration (DSC) extension on a virtual machine in a resource group.

Examples

Example 1: Set a DSC extension

PS C:\> Set-AzureRmVMDscExtension -ResourceGroupName "ResourceGroup001" -VMName "VM07" -ArchiveBlobName "Sample.ps1.zip" -ArchiveStorageAccountName "Stg" -ConfigurationName "ConfigName" -Version "1.10" -Location "West US"

This command sets the DSC extension on the virtual machine named VM07 to download Sample.ps1.zip from the storage account named Stg and the default container. The command invokes the configuration named ConfigName. The Sample.ps1.zip file was previously uploaded by using Publish-AzureRmVMDscConfiguration.

Example 2: Set a DSC extension with configuration data

PS C:\> Set-AzureRmVMDscExtension -ResourceGroupName "ResourceGroup001" -VMName "VM13" -ArchiveBlobName "Sample.ps1.zip" -ArchiveStorageAccountName "Stg" -ConfigurationName "ConfigName" -ConfigurationArgument "@{arg="val"}" -ArchiveContainerName "WindowsPowerShellDSC" -ConfigurationData "SampleData.psd1" -Version "1.10" -Location "West US"

This command sets the extension on the virtual machine named VM13 to download Sample.ps1.zip from the storage account named Stg and the container named WindowsPowerShellDSC. The command the configuration named ConfigName and specifies configuration data and arguments. The Sample.ps1.zip file was previously uploaded by using Publish-AzureRmVMDscConfiguration.

Example 3: Set a DSC extension with configuration data that has auto update

PS C:\> Set-AzureRmVMDscExtension -ResourceGroupName "ResourceGroup001" -VMName "VM22" -ArchiveBlobName "Sample.ps1.zip" -ArchiveStorageAccountName "Stg" -ConfigurationName "ConfigName" -ConfigurationArgument "@{arg="val"}" -ArchiveContainerName WindowsPowerShellDSC -ConfigurationData "SampleData.psd1" -Version "1.10" -Location "West US" -AutoUpdate

This command sets the extension on the virtual machine named VM22 to download Sample.ps1.zip from the storage account named Stg and the container named WindowsPowerShellDSC. The command invokes the configuration named ConfigName and specifies configuration data and arguments. This command also enables auto update of extension handler to the latest version. The Sample.ps1.zip was previously uploaded by using Publish-AzureRmVMDscConfiguration.

Parameters

-ArchiveBlobName

Specifies the name of the configuration file that was previously uploaded by the Publish-AzureRmVMDscConfiguration cmdlet.

Type:String
Aliases:ConfigurationArchiveBlob
Position:5
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-ArchiveContainerName

Species name of the Azure storage container where the configuration archive is located.

Type:String
Aliases:ContainerName
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ArchiveResourceGroupName

Specifies the name of the resource group that contains the storage account that contains the configuration archive. This parameter is optional if the storage account and virtual machine are both in the same resource group.

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

-ArchiveStorageAccountName

Specifies the Azure storage account name that is used to download the ArchiveBlobName.

Type:String
Aliases:StorageAccountName
Position:4
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-ArchiveStorageEndpointSuffix

Specifies the storage endpoint suffix.

Type:String
Aliases:StorageEndpointSuffix
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-AutoUpdate

Specifies the extension handler version specified by the Version parameter. By default extension handler is not autoupdated. Use the AutoUpdate parameter to enable auto update of the extension handler to the latest version as and when it is available.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ConfigurationArgument

Specifies a hash table that contains the arguments to the configuration function.

Type:Hashtable
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ConfigurationData

Specifies the path of a .psd1 file that specifies the data for the configuration.

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

-ConfigurationName

Specifies the name of the configuration that the DSC Extension invokes.

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

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DataCollection

Specifies the data collection type. The acceptable values for this parameter are: Enable and Disable.

Type:String
Accepted values:Enable, Disable
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with azure.

Type:IAzureContextContainer
Aliases:AzureRmContext, AzureCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Forces the command to run without asking for user confirmation.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Location

Specifies the path of the resource extension.

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

-Name

Specifies the name of the Azure Resource Manager resource that represents the extension. The default value is Microsoft.Powershell.DSC.

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

-ResourceGroupName

Specifies the name of the resource group of the virtual machine.

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

-Version

Specifies the version of the DSC extension that Set-AzureRmVMDscExtension applies the settings to.

Type:String
Aliases:HandlerVersion
Position:1
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-VMName

Specifies the name of the virtual machine where DSC extension handler is installed.

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

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WmfVersion

Specifies the WMF version.

Type:String
Accepted values:4.0, 5.0, 5.1, latest
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

Inputs

String

Hashtable

Outputs

PSAzureOperationResponse