Share via

Start-ServiceFabricApplicationUpgrade

Module:
ServiceFabric Module

Upgrades a Service Fabric application to specified ApplicationTypeVersion.

Syntax

UnmonitoredAuto (Default) 

Start-ServiceFabricApplicationUpgrade
    [-ApplicationName] <Uri>
    [-ApplicationTypeVersion] <String>
    [[-ApplicationParameter] <Hashtable>]
    [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
    [[-SortOrder] <UpgradeSortOrder>]
    [-ForceRestart]
    [-ReplicaQuorumTimeoutSec <UInt32>]
    [-RestartProcess]
    [-InstanceCloseDelayDurationSec <UInt32>]
    [-UnmonitoredAuto]
    [-Force]
    [-TimeoutSec <Int32>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

UnmonitoredManual 

Start-ServiceFabricApplicationUpgrade
    [-ApplicationName] <Uri>
    [-ApplicationTypeVersion] <String>
    [[-ApplicationParameter] <Hashtable>]
    [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
    [[-SortOrder] <UpgradeSortOrder>]
    [-ForceRestart]
    [-ReplicaQuorumTimeoutSec <UInt32>]
    [-RestartProcess]
    [-InstanceCloseDelayDurationSec <UInt32>]
    [-UnmonitoredManual]
    [-Force]
    [-TimeoutSec <Int32>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Monitored 

Start-ServiceFabricApplicationUpgrade
    [-ApplicationName] <Uri>
    [-ApplicationTypeVersion] <String>
    [[-ApplicationParameter] <Hashtable>]
    [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
    [[-SortOrder] <UpgradeSortOrder>]
    -FailureAction <UpgradeFailureAction>
    [-ForceRestart]
    [-ReplicaQuorumTimeoutSec <UInt32>]
    [-RestartProcess]
    [-InstanceCloseDelayDurationSec <UInt32>]
    [-Monitored]
    [-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.

Parameter properties

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

Parameter sets

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

-ApplicationParameter

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

Parameter properties

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

Parameter sets

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

-ApplicationTypeVersion

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

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:False
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

-ConsiderWarningAsError

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

Parameter properties

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

Parameter sets

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

Parameter properties

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

Parameter sets

Monitored
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-FailureAction

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

  • Rollback
  • Manual

Parameter properties

Type:UpgradeFailureAction
Default value:None
Accepted values:Invalid, Rollback, Manual
Supports wildcards:False
DontShow:False

Parameter sets

Monitored
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Force

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

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

-ForceRestart

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

Parameter properties

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

Parameter sets

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

-HealthCheckRetryTimeoutSec

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

Parameter properties

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

Parameter sets

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

Parameter properties

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

Parameter sets

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

Parameter properties

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

Parameter sets

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

Parameter properties

Type:UInt32
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

-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.

Parameter properties

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

Parameter sets

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

Parameter properties

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

Parameter sets

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

Parameter properties

Type:UInt32
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

-RestartProcess

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

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

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

-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" }

Parameter properties

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

Parameter sets

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

Parameter properties

Type:UpgradeSortOrder
Default value:None
Accepted values:Invalid, Default, Numeric, Lexicographical, ReverseNumeric, ReverseLexicographical
Supports wildcards:False
DontShow:False

Parameter sets

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

-TimeoutSec

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

Parameter properties

Type:Int32
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

-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.

Parameter properties

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

Parameter sets

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

Parameter properties

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

Parameter sets

UnmonitoredManual
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-UpgradeDomainTimeoutSec

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

Parameter properties

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

Parameter sets

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

Parameter properties

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

Parameter sets

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

-UpgradeTimeoutSec

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

Parameter properties

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

Parameter sets

Monitored
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
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

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.

Inputs

None

Outputs

System.Object