Share via

Start-ServiceFabricApplicationUpgrade

  • Reference
Module:
ServiceFabric

Upgrades a Service Fabric application to specified ApplicationTypeVersion.

Syntax

Start-ServiceFabricApplicationUpgrade
     [-ApplicationName] <Uri>
     [-ApplicationTypeVersion] <String>
     [[-ApplicationParameter] <Hashtable>]
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredAuto]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]
Start-ServiceFabricApplicationUpgrade
     [-ApplicationName] <Uri>
     [-ApplicationTypeVersion] <String>
     [[-ApplicationParameter] <Hashtable>]
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredManual]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]
Start-ServiceFabricApplicationUpgrade
     [-ApplicationName] <Uri>
     [-ApplicationTypeVersion] <String>
     [[-ApplicationParameter] <Hashtable>]
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-Monitored]
     -FailureAction <UpgradeFailureAction>
     [-HealthCheckRetryTimeoutSec <UInt32>]
     [-HealthCheckWaitDurationSec <UInt32>]
     [-HealthCheckStableDurationSec <UInt32>]
     [-UpgradeDomainTimeoutSec <UInt32>]
     [-UpgradeTimeoutSec <UInt32>]
     [-ConsiderWarningAsError <Boolean>]
     [-DefaultServiceTypeHealthPolicy <String>]
     [-MaxPercentUnhealthyDeployedApplications <Byte>]
     [-ServiceTypeHealthPolicyMap <Hashtable>]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Description

The Start-ServiceFabricApplicationUpgrade cmdlet upgrades a Service Fabric application. Before using this cmdlet you need to copy the updated application package to the image store and register the updated application type. Use the Copy-ServiceFabricApplicationPackage to copy the application package to image store. Use the Register-ServiceFabricApplicationType cmdlet to register the updated application type.

This cmdlet starts the upgrade on the cluster.

ApplicationParameters are not preserved across an application upgrade. In order to preserve current application parameters, the user should get the parameters first and pass them into the upgrade API call, as shown in Example 1 below.

For more information on Service Fabric application upgrades, see the conceptual documentation.

Before you perform any operation on a Service Fabric cluster, establish a connection to the cluster by using the Connect-ServiceFabricCluster cmdlet.

Examples

Example 1: Get the application parameters to pass into the upgrade call

$myApplication = Get-ServiceFabricApplication -ApplicationName fabric:/myApplication
$appParamCollection = $myApplication.ApplicationParameters
$applicationParameterMap = @{}

foreach ($pair in $appParamCollection)
{ $applicationParameterMap.Add($pair.Name, $pair.Value); }

Start-ServiceFabricApplicationUpgrade -ApplicationName fabric:/myApplication -ApplicationTypeVersion 2.0.0 -ApplicationParameter $applicationParameterMap -Monitored -FailureAction Rollback

Example 2: Upgrade an application

PS C:\> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath "C:\PersistentToDoListServiceV2" -ImageStoreConnectionString "file:C:\ProgramData\ServiceFabric\ImageStore"
PS C:\> Register-ServiceFabricApplicationType -ApplicationPathInImageStore "PersistentToDoListServiceV2"
PS C:\> Start-ServiceFabricApplicationUpgrade -ApplicationName fabric:/myapp/persistenttodolist -ApplicationTypeVersion "2.0" -ForceRestart -UnMonitoredManual

The first command uses the Copy-ServiceFabricApplicationPackage cmdlet to copy the updated application package to the image store.

The second command uses the Register-ServiceFabricApplicationType cmdlet to register the updated application type.

The third command upgrades the application. The command performs an unmonitored manual upgrade, which includes a restart of the server that hosts the application.

Parameters

-ApplicationName

Specifies the Uniform Resource Identifier (URI) of a Service Fabric application. The cmdlet upgrades the application that has the URI that you specify.

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

-ApplicationParameter

Specifies the overrides for application parameters as name/value pairs.

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

-ApplicationTypeVersion

Specifies the version of a Service Fabric application type. The cmdlet upgrades the application to the version that you specify.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
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

-ConsiderWarningAsError

Indicates whether to treat a warning health event as an error event during health evaluation.

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

-DefaultServiceTypeHealthPolicy

Specifies the health policy for the default service type to use for the monitored upgrade in the format MaxPercentUnhealthyPartitionsPerService, MaxPercentUnhealthyReplicasPerPartition, MaxPercentUnhealthyServices. For example, 5,10,15 indicates the following values:

  • MaxPercentUnhealthyPartitionsPerService = 5
  • MaxPercentUnhealthyReplicasPerPartition = 10
  • MaxPercentUnhealthyServices = 15
Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-FailureAction

Specifies the action to take if the monitored upgrade fails. The acceptable values for this parameter are:

  • Rollback
  • Manual
Type:UpgradeFailureAction
Accepted values:Invalid, Rollback, Manual
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Force

Indicates that this cmdlet skips the warning message and forces the upgrade.

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

-ForceRestart

Indicates that the service host restarts even if the upgrade is a configuration-only change.

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

-HealthCheckRetryTimeoutSec

Specifies the duration, in seconds, after which Service Fabric retries the health check if the previous health check fails.

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

-HealthCheckStableDurationSec

Specifies the duration, in seconds, that Service Fabric waits in order to verify that the application is stable before moving to the next upgrade domain or completing the upgrade. This wait duration prevents undetected changes of health right after the health check is performed.

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

-HealthCheckWaitDurationSec

Specifies the duration, in seconds, that Service Fabric waits before it performs the initial health check after it finishes the upgrade on the upgrade domain.

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

-InstanceCloseDelayDurationSec

Specifies the duration in seconds, to wait before a stateless instance which is impacted by application upgrade is closed, to allow the active requests to drain gracefully. This wait duration is effective only for the instances of those stateless services which have a non-zero value configured for the InstanceCloseDelayDuration, and will override the pre-configured value. See InstanceCloseDelayDuration (in New-ServiceFabricService) for details.

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

-MaxPercentUnhealthyDeployedApplications

Specifies the maximum percentage of the application instances deployed on the nodes in the cluster that have a health state of error before the application health state for the cluster is error.

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

-Monitored

Indicates that the upgrade mode is monitored. After the cmdlet finishes an upgrade for an upgrade domain, if the health of the upgrade domain and the cluster meet the health policies that you define, Service Fabric upgrades the next upgrade domain. If the upgrade domain or cluster fails to meet health policies, the upgrade fails and Service Fabric rolls back the upgrade for the upgrade domain or reverts to manual mode per the policy specified. This is the recommended mode for application upgrades in a production environment.

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

-ReplicaQuorumTimeoutSec

Specifies the time-out period, in seconds, to check whether the replica set has quorum. After the time-out period, the upgrade proceeds.

This parameter has been deprecated. Specify the UpgradeReplicaSetCheckTimeoutSec parameter instead.

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

-RestartProcess

Indicates that the service host restarts as part of the upgrade.

This parameter has been deprecated. Specify the ForceRestart parameter instead.

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

-ServiceTypeHealthPolicyMap

Specifies the map of the health policy to use for different service types as a hash table in the following format: @ {"ServiceTypeName" : "MaxPercentUnhealthyPartitionsPerService,MaxPercentUnhealthyReplicasPerPartition,MaxPercentUnhealthyServices"}. For example:

@{ "ServiceTypeName01" = "5,10,5"; "ServiceTypeName02" = "5,5,5" }

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

-SortOrder

Defines the order in which an upgrade proceeds through the cluster.

Possible values are:

  • Invalid - Indicates that this sort order is not valid. All Service Fabric enumerations have the invalid type.
  • Default - Indicates that the default sort order (as specified in cluster manifest) will be used.
  • Numeric - Indicates that forward numeric sort order (UD names sorted as numbers) will be used.
  • Lexicographical - Indicates that forward lexicographical sort order (UD names sorted as strings) will be used.
  • ReverseNumeric - Indicates that reverse numeric sort order (UD names sorted as numbers) will be used.
  • ReverseLexicographical- Indicates that reverse lexicographical sort order (UD names sorted as strings) will be used.
Type:UpgradeSortOrder
Accepted values:Invalid, Default, Numeric, Lexicographical, ReverseNumeric, ReverseLexicographical
Position:5
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TimeoutSec

Specifies the time-out period, in seconds, for the operation.

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

-UnmonitoredAuto

Indicates that the upgrade mode is unmonitored automatic. After Service Fabric upgrades an upgrade domain, Service Fabric upgrades the next upgrade domain irrespective of the application health state. This mode is not recommended for production, and is only useful during development of an application.

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

-UnmonitoredManual

Indicates that the upgrade mode is unmonitored manual. After Service Fabric upgrades an upgrade domain, it waits for you to upgrade the next upgrade domain by using the Resume-ServiceFabricApplicationUpgrade cmdlet.

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

-UpgradeDomainTimeoutSec

Specifies the maximum time, in seconds, that Service Fabric takes to upgrade a single upgrade domain. After this period, the upgrade fails.

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

-UpgradeReplicaSetCheckTimeoutSec

Specifies the maximum time that Service Fabric waits for a service to reconfigure into a safe state, if not already in a safe state, before Service Fabric proceeds with the upgrade.

Type:UInt32
Position:4
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UpgradeTimeoutSec

Specifies the maximum time, in seconds, that Service Fabric takes for the entire upgrade. After this period, the upgrade fails.

Type:UInt32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
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

Inputs

None

Outputs

System.Object