Set-AzureVMDscExtension

Reference

Module:: Azure

Configures the DSC extension on a virtual machine.

Note

The cmdlets referenced in this documentation are for managing legacy Azure resources that use Service Management APIs. See the Az PowerShell module for cmdlets to manage Azure Resource Manager resources.

Syntax

Set-AzureVMDscExtension
   [-ReferenceName <String>]
   [-ConfigurationArgument <Hashtable>]
   [-ConfigurationDataPath <String>]
   [-ConfigurationArchive] <String>
   [-ConfigurationName <String>]
   [-ContainerName <String>]
   [-Force]
   [-StorageContext <AzureStorageContext>]
   [-Version <String>]
   [-StorageEndpointSuffix <String>]
   [-WmfVersion <String>]
   [-DataCollection <String>]
   -VM <IPersistentVM>
   [-Profile <AzureSMProfile>]
   [-InformationAction <ActionPreference>]
   [-InformationVariable <String>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The Set-AzureVMDscExtension cmdlet configures the Desired State Configuration (DSC) extension on a virtual machine.

Examples

Example 1: Configure the DSC extension on a virtual machine

PS C:\> Set-AzureVMDscExtension -VM $VM -ConfigurationArchive MyConfiguration.ps1.zip  -ConfigurationName MyConfiguration -ConfigurationArgument @{ Path = 'C:\MyDirectory' }
DeploymentName              : my-vm-svc
Name                        : my-vm
Label                       :
VM                          : Microsoft.WindowsAzure.Commands.ServiceManagement.Model.PersistentVM
InstanceStatus              : ReadyRole
IpAddress                   : 10.10.10.10
InstanceStateDetails        :
PowerState                  : Started
InstanceErrorCode           :
InstanceFaultDomain         : 0
InstanceName                : my-vm
InstanceUpgradeDomain       : 0
InstanceSize                : Small
AvailabilitySetName         :
DNSName                     : http://my-vm-svc.cloudapp.net/
Status                      : ReadyRole
GuestAgentStatus            : Microsoft.WindowsAzure.Commands.ServiceManagement.Model.PersistentVMModel.GuestAgentStatus
ResourceExtensionStatusList : {Contoso.Compute.BGInfo}
PublicIPAddress             :
PublicIPName                :
ServiceName                 : my-vm-svc
OperationDescription        : Get-AzureVM
OperationId                 : a0217a7af900c1f8a212299a3333cdbd6
OperationStatus             : OK

This command configures the DSC extension on a virtual machine.

The MyConfiguration.ps1.zip package must have been previously uploaded to Azure storage using the Publish-AzureVMDscConfiguration command and includes the MyConfiguration.ps1 script and the modules it depends on.

The MyConfiguration argument indicates the specific DSC configuration within the script to execute. The -ConfigurationArgument parameter specifies a hashtable with the arguments that is passed to the configuration function.

Example 2: Configure the DSC extension on a virtual machine using a path to the configuration data

PS C:\> $VM | Set-AzureVMDscExtension -ConfigurationArchive MyConfiguration.ps1.zip  -ConfigurationName MyConfiguration -ConfigurationArgument @{ Credential = Get-Credential } -ConfigurationDataPath MyConfigurationData.psd1
DeploymentName              : my-vm-svc
Name                        : my-vm
Label                       :
VM                          : Microsoft.WindowsAzure.Commands.ServiceManagement.Model.PersistentVM
InstanceStatus              : ReadyRole
IpAddress                   : 10.10.10.10
InstanceStateDetails        :
PowerState                  : Started
InstanceErrorCode           :
InstanceFaultDomain         : 0
InstanceName                : my-vm
InstanceUpgradeDomain       : 0
InstanceSize                : Small
AvailabilitySetName         :
DNSName                     : http://my-vm-svc.cloudapp.net/
Status                      : ReadyRole
GuestAgentStatus            : Microsoft.WindowsAzure.Commands.ServiceManagement.Model.PersistentVMModel.GuestAgentStatus
ResourceExtensionStatusList : {Microsoft.Compute.BGInfo, Microsoft.Powershell.DSC}
PublicIPAddress             :
PublicIPName                :
ServiceName                 : my-vm-svc
OperationDescription        : Get-AzureVM
OperationId                 : a0217a7af900c1f8a212299a3333cdbd7
OperationStatus             : OK

This command configures the DSC extension on a virtual machine using a path to the configuration data.

Parameters

-ConfigurationArchive

Specifies the name of the configuration package (.zip file) that was previously uploaded by Publish-AzureVMDscConfiguration. This parameter must specify only the name of the file, without any path.

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

-ConfigurationArgument

Specifies a hashtable specifying the arguments to the configuration function. The keys correspond to the parameter names and the values to the parameter values.

The acceptable values for this parameter are:

primitive types
string
array
PSCredential

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

-ConfigurationDataPath

Specifies the path of a .psd1 file that specifies the data for the configuration function. This file must contain a hashtable as described in Separating Configuration and Environment Datahttps://msdn.microsoft.com/en-us/PowerShell/DSC/configData.

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

-ConfigurationName

Specifies the name of the configuration script or module that is invoked by the DSC extension.

The value of this parameter must be the name of one of the configuration functions contained in the scripts or modules packaged in ConfigurationArchive.

This cmdlet defaults to the name of the file given by the ConfigurationArchive parameter if you omit this parameter, excluding any extension. For instance, if ConfigurationArchive is "SalesWebSite.ps1.zip", the default value for ConfigurationName is "SalesWebSite".

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

-ContainerName

Specifies the name of the Azure storage container where the ConfigurationArchive is located.

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

-DataCollection

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

-Force

Indicates that this cmdlet overwrites existing blobs.

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

-InformationAction

Specifies how this cmdlet responds to an information event.

The acceptable values for this parameter are:

Continue
Ignore
Inquire
SilentlyContinue
Stop
Suspend

Type:	ActionPreference
Aliases:	infa
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InformationVariable

Specifies an information variable.

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

-Profile

Specifies the Azure profile from which this cmdlet reads. If you do not specify a profile, this cmdlet reads from the local default profile.

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

-ReferenceName

Specifies a user-defined string that can be used to refer to an extension. This parameter is specified when the extension is added to the virtual machine for the first time. For subsequent updates, you should specify the previously used reference name while you update the extension. The ReferenceName assigned to an extension is returned using the Get-AzureVM cmdlet.

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

-StorageContext

Specifies the Azure storage context that provides the security settings used to access the configuration script. This context provides read access to the container specified by the ContainerName parameter.

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

-StorageEndpointSuffix

Specifies the DNS endpoint suffix for all storage services, for instance, "core.contoso.net".

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

-Version

Specifies the specific version of the DSC extension to use. The default value is set to "1.*" if this parameter is not specified.

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

-VM

Specifies the persistent virtual machine object.

Type:	IPersistentVM
Aliases:	InputObject
Position:	Named
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 version of the Windows Management Framework (WMF) to install on the virtual machine. The DSC Extension depends on DSC features that are only available in the WMF updates. This parameter specifies which version of the update to install on the virtual machine. The acceptable values for this parameter are:

4.0. Installs WMF 4.0 unless a newer version is already installed.
5.0. Installs the latest release of WMF 5.0.
latest. Installs the latest WMF, currently WMF 5.0.

The default value is latest.

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