Edit

Share via

Set-AzureVMDscExtension

Module:
Azure Module

Configures the DSC extension on a virtual machine.

Note

The cmdlets referenced in this documentation are for managing legacy Azure resources that use Azure Service Manager (ASM) APIs. This legacy PowerShell module isn't recommended when creating new resources since ASM is scheduled for retirement. For more information, see Azure Service Manager retirement.

The Az PowerShell module is the recommended PowerShell module for managing Azure Resource Manager (ARM) resources with PowerShell.

Syntax

Default (Default) 

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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:1
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments: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

Parameter properties

Type:Hashtable
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments: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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments: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".

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False
Aliases:cf

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ContainerName

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-DataCollection

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Force

Indicates that this cmdlet overwrites existing blobs.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InformationAction

Specifies how this cmdlet responds to an information event.

The acceptable values for this parameter are:

  • Continue
  • Ignore
  • Inquire
  • SilentlyContinue
  • Stop
  • Suspend

Parameter properties

Type:ActionPreference
Default value:None
Supports wildcards:False
DontShow:False
Aliases:infa

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InformationVariable

Specifies an information variable.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:iv

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments: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.

Parameter properties

Type:AzureSMProfile
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments: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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments: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.

Parameter properties

Type:AzureStorageContext
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-StorageEndpointSuffix

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

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments: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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-VM

Specifies the persistent virtual machine object.

Parameter properties

Type:IPersistentVM
Default value:None
Supports wildcards:False
DontShow:False
Aliases:InputObject

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:True
Value from remaining arguments:False

-WhatIf

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

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False
Aliases:wi

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments: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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.