Set-AzureResource

  • Article

Set-AzureResource

Changes the properties of an Azure resource.

Syntax

Parameter Set: Default
Set-AzureResource -ApiVersion <String> -Name <String> -ResourceGroupName <String> -ResourceType <String> [-ParentResource <String> ] [-Profile <Microsoft.Azure.Common.Authentication.Models.AzureProfile> ] [-PropertyObject <Hashtable> ] [-Tag <Hashtable[]> ] [ <CommonParameters>]

Detailed Description

The Set-AzureResource cmdlet changes the properties of an Azure resource. To use the cmdlet, use the Name, ResourceGroupName, ResourceGroupType, and ParentResource parameters to identify the resource, and the PropertyObject parameter to specify the new property names and values.

If the command succeeds, it returns the resource with the new properties and values.

An Azure resource is a user-managed entity, such as an Azure Website or Azure SQL Database. Some resources have properties, which are user-configured values, like sizes and operational modes. You can specify these values when you create the resource, such as by using the New-AzureResource, New-AzureResourceGroup, or New-AzureResourceGroupDeployment cmdlets. And, you can change the properties by using this cmdlet.

To get the properties of a resource, use the Get-AzureResource cmdlet to get the resource. Then use the dot method to get the Properties property collection and a particular named property. For example, to get the siteMode property of an object, type (Get-AzureResource -Name MyWebSite -ResourceGroupName RG -ResourceType Microsoft.Web/sites -ApiVersion 2015-04-01).Properties.siteMode

Parameters

-ApiVersion<String>

Specifies the API version that is supported by the resource provider. This parameter is required.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Name<String>

Specifies the name of the Azure resource. The name is case-sensitive. Wildcards are not permitted. This value identifies the resource. You cannot use this cmdlet to change the resource name.

Aliases

ResourceName

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ParentResource<String>

Specifies the names of the logical parent of a resource. Enter the fully qualified name of the parent resource, such as " Microsoft.Sql/servers/ContosoSQLSvr". Wildcards are not permitted. This value identifies the resource. You cannot use this cmdlet to change the resource parent.

Use this parameter when the resource is a type that has parents. For example, every SQL Azure database has a parent SQL Azure database server. A resource group is not a parent of its resources.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Profile<Microsoft.Azure.Common.Authentication.Models.AzureProfile>

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

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-PropertyObject<Hashtable>

Specifies the new property values. Enter a hash table of property names and values. The names and values are case-sensitive.

Aliases

Properties

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ResourceGroupName<String>

Specifies the name of the resource group of the resource. Wildcards are not permitted. This value identifies the resource. You cannot use this cmdlet to change the resource group of a resource.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-ResourceType<String>

Specifies the resource type. Wildcards are not permitted. This value identifies the resource. You cannot use this cmdlet to change the resource type.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

-Tag<Hashtable[]>

Replaces the tags for the resource with the specified new or predefined tags. To change any resource tag, you must replace the collection of tags for the resource.

A "tag" is a name-value pair that you can apply to resources and resource groups. Use tags to categorize your resources, such as by department or cost center, or to track notes or comments about the resources. After you assign tags to resources, you can use the Tag parameters of Get-AzureResource and Get-AzureResourceGroup to search for resources and groups by tag name or name and value.

Each tag must have a Name key. It can also have an optional Value key with one value. To specify a new tag, use a hash table, such as @{Name="FY2015"} or @{Name="Department";Value="IT"}. To specify multiple tags, use commas to separate the hash tables, such as -Tag @{Name="FY2015"}, @{Name="Department";Value="IT"}. To specify a predefined tag, use the Get-AzureTag cmdlet.

To delete a tag, enter a hash table with all tags currently applied to the resource (from Get-AzureResource), except for the tag you want to delete. To delete all tags from the resource, enter an empty hash table (-Tag @{}).

Aliases

Tags

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

True (ByPropertyName)

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see    about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • None

    You can pipe input to the cmdlet by property name, but not by value.

Outputs

The output type is the type of the objects that the cmdlet emits.

  • Microsoft.Azure.Commands.ResourceManager.Models.PSResource

Notes

  • The Set-AzureResource cmdlet is included in the Azure Resource Manager module beginning in module version 0.8.0.

Examples

Example 1: Change the properties of a resource

This example shows how to change the properties of an Azure resource. In this case, we'll shift a web site from one server farm to another. To do that, we have to change the web site properties to be compatible with the new server farm.

The first command uses the Get-AzureResource cmdlet to get the ContosoLabWeb2 web site. The command saves the resource in the $r variable.

$r = Get-AzureResource -Name ContosoLabWeb2 -ResourceGroupName ContosoLabsRG -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01

The second command saves the Properties property (and its properties) of the resource in the $p variable. The Properties object is a Dictionary, but because it is convertible to a hash table, you can use it as the value of the PropertyObject parameter of Set-AzureResource without casting.

$p = $r.Properties

The third command displays the properties in the $p variable.

$pName                           Value----                           -----name                           ContosoLabWeb2storageRecoveryDefaultState    RunningavailabilityState              0trafficManagerHostNamesrepositorySiteName             ContosoLabWeb2runtimeAvailabilityState       0siteMode                       LimitedruntimeADUserlastModifiedTimeUtc            3/25/2014 6:00:04 PMusageState                     0hostNames                      {contosolabweb2.antares-int.windows-int.net}adminEnabled                   TruehostNameSslStates              {System.Collections.Generic.Dictionary`2[System.String,System.Object], System.Collect...runtimeADUserDomainenabled                        TruedeploymentId                   ContosoLabWeb2selfLink                       https://antpreview2.api.admin-antares-int.windows-int.net:454/20130801/websystems/web...computeMode                    0webSpace                       ContosoLabsRG-NorthEuropewebspacecsrs                           {}siteConfigintegratedSqlAuthEnabled       Falsestate                          RunningruntimeADUserPasswordserverFarm                     Default1sslCertificates                {}cerscontentAvailabilityState       0enabledHostNames               {contosolabweb2.antares-int.windows-int.net, contosolabweb2.scm.antares-int.windows-i...windowsAuthEnabled             0ownersiteProperties                 {[metadata, ], [properties, System.Collections.Generic.List`1[System.Object]], [appSe...sku                            Free

The fourth command is actually a series of commands (delimited by semi-colons) that change the values of the properties in the $p variable.

$p.siteMode = "Basic"; $p.sku = "Basic"; $p.computeMode = "Dedicated"; $p.serverFarm = "Default2"

The fifth command uses the Set-AzureResource cmdlet to change the change the properties of the ContosoLabWeb2 web site. The value of the PropertyObject parameter is the $p variable that contains the Properties object and the new values. The command saves the output (the updated resource) in the $r2 variable.

$r2 = Set-AzureResource -Name ContosoLabWeb2 -ResourceGroupName ContosoLabsRG -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01 -PropertyObject $p

The sixth command displays the Properties property of the resource in the $r2 variable. You can see that the properties have the new values.

$r2.PropertiesName                           Value----                           -----storageRecoveryDefaultState    RunningavailabilityState              0trafficManagerHostNamesrepositorySiteName             ContosoLabWeb2runtimeAvailabilityState       0siteMode                       BasicruntimeADUserlastModifiedTimeUtc            3/25/2014 6:00:04 PMusageState                     0hostNames                      {contosolabweb2.antares-int.windows-int.net}adminEnabled                   TruehostNameSslStates              {System.Collections.Generic.Dictionary`2[System.String,System.Object], System.Collect...runtimeADUserDomainenabled                        TruedeploymentId                   ContosoLabWeb2selfLink                       https://antpreview2.api.admin-antares-int.windows-int.net:454/20130801/websystems/web...computeMode                    DedicatedwebSpace                       ContosoLabsRG-NorthEuropewebspacecsrs                           {}siteConfigintegratedSqlAuthEnabled       Falsestate                          RunningruntimeADUserPasswordserverFarm                     Default2sslCertificates                {}cerscontentAvailabilityState       0enabledHostNames               {contosolabweb2.antares-int.windows-int.net, contosolabweb2.scm.antares-int.windows-i...windowsAuthEnabled             0ownersiteProperties                 {[metadata, ], [properties, System.Collections.Generic.List`1[System.Object]], [appSe...sku                            Basicname                           ContosoLabWeb2

Example 2: Apply a tag to a resource

This command uses the Tag parameter to add a CostCenter tag with a value of "Sales" to a resource that did not have any existing tags.

Get-AzureResource -Name ContosoLabWeb2 -ResourceGroupName ContosoLabsRG -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01 -Tag @{Name="CostCenter";Value="Sales"}

Example 3: Add tags to a resource

This command adds a "Status" tag with a value of "Approved" and an "FY2016" tag to a resource that has existing tags. Because the tags you specify replace the existing tags, you must include the existing tags in the new tag collection or you will lose them.

The first command gets all existing tags of the ContosoWeb resource. It uses the Get-AzureResource cmdlet to get the resource and then uses the dot method to get the value of its Tags property. It saves the existing tags in a $tags variable.

The second command gets the tags in the $tags variable.

The third command uses a "+=" operator to add the Status and FY2016 tags to the collection (array) of tags in the $tags variable.

The fourth command uses the Tag parameter of Set-AzureResource to apply the tags in the $tags variable to the ContosoWeb resource.

The fifth command shows the effect of the change. It gets all of the tags applied to the ContosoWeb resource. The output shows that the resource has the Department tag and the two new tags, Status and FY2015.

$tags = (Get-AzureResource -Name ContosoWeb -ResourceGroupName ContosoLabsRG -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01).Tags

PS C:\>$tags


Tags: 

      Name        Value
      ====        ======
      Department  IT


PS C:\>$tags += @{Name="Status";Value="Approved"}, @{Name="FY2016"}

PS C:\>Set-AzureResource -Name ContosoWeb -ResourceGroupName ContosoLabsRG -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01 -Tag $tags

PS C:>(Get-AzureResource -Name ContosoWeb -ResourceGroupName ContosoLabsRG -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01).Tags


Tags: 

      Name        Value
      ====        ======
      Department  IT
      Status      Approved
      FY2016

Example 4: Delete all tags

This command uses the Tag parameter and an empty hash table value to delete all tags from a resource.

Get-AzureResource -Name ContosoLabWeb2 -ResourceGroupName ContosoLabsRG -ResourceType "Microsoft.Web/sites" -ApiVersion 2015-04-01 -Tag @{}