Register-ServiceFabricApplicationType

  • Reference
Module:
ServiceFabric

Registers a Service Fabric application type.

Syntax

Register-ServiceFabricApplicationType
        [-ApplicationPathInImageStore] <String>
        [-ApplicationPackageCleanupPolicy <ApplicationPackageCleanupPolicy>]
        [-Async]
        [-TimeoutSec <Int32>]
        [<CommonParameters>]
Register-ServiceFabricApplicationType
        [-ApplicationPackageDownloadUri] <Uri>
        -ApplicationTypeName <String>
        -ApplicationTypeVersion <String>
        [-Async]
        [-TimeoutSec <Int32>]
        [<CommonParameters>]

Description

The Register-ServiceFabricApplicationType cmdlet registers a Service Fabric application type. Read more about Service Fabric application deployment.

The application package can exist in a relative location in the image store or can be an sfpkg file previously uploaded to an external location.

When using store relative path, the application package must exist in the image store. The package can be copied to the image store with Copy-ServiceFabricApplicationPackage.

When using an sfpkg file from an external store, the provision must provide the download URI to where the sfpkg was previously uploaded, as well as the application type information. The sfpkg file is a zip that contains the initial application package and has the extension ".sfpkg". Inside the zip, the application package can be compressed or uncompressed. The compression of the application package inside the zip is done at code, package, and data packages.

To create an sfpkg, start with a folder that contains the original application package. If needed, compress the package with Copy-ServiceFabricApplicationPackage with switches -CompressPackage and -SkipCopy. Then, use an utility to zip the folder with the extension ".sfpkg". For example, use ZipFile.CreateFromDirectory on the application package folder.

After you register an application type, you can use the New-ServiceFabricApplication cmdlet to create an application instance. Use the Start-ServiceFabricApplicationUpgrade cmdlet to upgrade an existing application.

When the application type with the specified version is not needed anymore, you can unregister it using Unregister-ServiceFabricApplicationType cmdlet.

To manage Service Fabric clusters, start Windows PowerShell by using the Run as administrator option. 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: Register an application type with image store relative path

PS C:\> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath "c:\work\PersistentToDoListService" -ImageStoreConnectionString "file:C:\SfDevCluster\Data\ImageStoreShare" -ApplicationPackagePathInImageStore "PersistentToDoListService"
PS C:\> Register-ServiceFabricApplicationType -ApplicationPathInImageStore "PersistentToDoListService"

Copy-ServiceFabricApplicationPackage copies the application package found in the "c:\work\PersistentToDoListService" folder to the image store. The package is copied at the relative path "PersistentToDoListService" in image store.

Register-ServiceFabricApplicationType command registers the application type found in the relative path "PersistentToDoListService".

Example 2: Register an application type with image store relative path async

PS C:\> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath "c:\work\PersistentToDoListService" -ImageStoreConnectionString "fabric:ImageStore" -ApplicationPackagePathInImageStore "PersistentToDoListService" -CompressPackage
PS C:\> Register-ServiceFabricApplicationType -ApplicationPathInImageStore "PersistentToDoListService" -Async
PS C:\> Get-ServiceFabricApplicationType

Copy-ServiceFabricApplicationPackage copies the application package found in the "c:\work\PersistentToDoListService" folder to the image store. The application package is copied at the relative path "PersistentToDoListService" in image store. The cmdlet uses compression to reduce the package size.

Register-ServiceFabricApplicationType command registers the application type found in the relative path "PersistentToDoListService". Register is done async, and it returns as soon as the command is accepted by the cluster.

Get-ServiceFabricApplicationType gets the application types registered in the cluster. Each application type includes the registration status. The cmdlet can be used to determine when the registration completes.

Example 3: Register an application type for a large application package with image store relative path

PS C:\> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath "c:\work\PersistentToDoListService" -ImageStoreConnectionString "fabric:ImageStore" -ApplicationPackagePathInImageStore "PersistentToDoListService" -CompressPackage -TimeoutSec 2700
PS C:\> Register-ServiceFabricApplicationType -ApplicationPathInImageStore "PersistentToDoListService" -TimeoutSec 2700

Copy-ServiceFabricApplicationPackage copies the application package found in the "c:\work\PersistentToDoListService" folder to the image store, at the "PersistentToDoListService" image store relative location. Since the initial package is very large, the command compress it and includes a higher timeout to allow enough time for copy.

Register-ServiceFabricApplicationType command registers the application type found in the relative path "PersistentToDoListService". The command includes a higher timeout to allow work to finish even if the application package is large.

Example 4: Register an application type from an external store

PS C:\> Register-ServiceFabricApplicationType -ApplicationPackageDownloadUri "https://sftestresources.blob.core.windows.net:443/sfpkgholder/MyAppPackage.sfpkg" -ApplicationTypeName MyApp -ApplicationTypeVersion V1 -TimeoutSec 2700

Registers the application package found at the specified URI. The application package must have been previously uploaded at that location and must allow READ access. Since the package may be large, the command specifies a large provision timeout.

Example 5: Register an application type from an external store async

PS C:\> Register-ServiceFabricApplicationType -ApplicationPackageDownloadUri "https://sftestresources.blob.core.windows.net:443/sfpkgholder/MyAppPackage.sfpkg" -ApplicationTypeName MyApp -ApplicationTypeVersion V1 -Async
PS C:\> Get-ServiceFabricApplicationType -ApplicationTypeName MyApp -ApplicationTypeVersion V1

Registers the application package found at the specified URI. The application package must have been previously uploaded at that location and must allow READ access. Because -Async is specified, the command returns as soon as the cluster accepts it. Get-ServiceFabricApplicationType gets the application types registered in the cluster that match the filter. Each application type includes the registration status. The cmdlet can be used to follow the registration progress and to determine when the registration completes.

Example 6: Register an application type with image store relative path and automatic package cleanup

PS C:\> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath "c:\work\PersistentToDoListService"

PS C:\> Register-ServiceFabricApplicationType -ApplicationPathInImageStore "PersistentToDoListService" -ApplicationPackageCleanupPolicy Automatic

[Copy-ServiceFabricApplicationPackage](./Copy-ServiceFabricApplicationPackage.yml) copies the application package found in the "c:\work\PersistentToDoListService" folder to the image store. The package is copied at the relative path "PersistentToDoListService" in image store.

[Register-ServiceFabricApplicationType](./Register-ServiceFabricApplicationType.yml) command registers the application type found in the relative path "PersistentToDoListService" and deletes the application package "PersistentToDoListService" in the image store after successfully registering the application type. Deleting the application package from the image store after [Register-ServiceFabricApplicationType](./Register-ServiceFabricApplicationType.yml) command is recommended because it removes the temporary package as soon as it's not needed, which ensures that disk space is not consumed unnecessarily.

Parameters

-ApplicationPackageCleanupPolicy

Determines the cleanup policy of the application package used for registering the application type. If not cleaned up, the application packages consume disk space and can lead to failures. This parameter specifies how to manage the application package after successfully registering the application type (successful provision).

When set to Automatic, Service Fabric runtime determines when to perform application package cleanup. Current runtime implementation deletes the application package after successfully registering the application type. If registration fails, then the application package is not deleted from the image store.

When set to Manual, the application package is not deleted from the image store and the users have to explicitly call Remove-ServiceFabricApplicationPackage cmdlet to remove it from the image store.

A Service Fabric cluster is configured with a clean up policy. To use the cluster's policy, specify Default option. The cluster config CleanupApplicationPackageOnProvisionSuccess under Management section determines how the cleanup should occur. If set to true, the application packages are automatically deleted by the service fabric runtime after successful provision. If set to false, the application package is not deleted from the image store. The default value of this cluster config have been set to false up to v6.4, but there are plans to set it to true for future releases.

Type:ApplicationPackageCleanupPolicy
Accepted values:Invalid, Default, Automatic, Manual
Position:Named
Default value:Default
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationPackageDownloadUri

Represents the path to the sfpkg application package from where the application package can be downloaded using HTTP or HTTPS protocols. The package must have been previously uploaded to this external location. The URI must allow READ access so Service Fabric can download the file. The sfpkg file is a zip that contains the initial application package. Inside the zip, the application package can be compressed or uncompressed. The compression of the application package inside the zip is done at code, package, and data packages. This compression can be achieved using Copy-ServiceFabricApplicationPackage with switch -CompressPackage. The sfpkg file must have the extension ".sfpkg".

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

-ApplicationPathInImageStore

Specifies the relative path of the application type package in the image store. This path was specified by the Copy-ServiceFabricApplicationPackage cmdlet when the application package was copied to the image store.

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

-ApplicationTypeName

Specifies the application type name, as it is defined in the application manifest. The application type name and the application type version uniquely identify the application type. This is needed when provisioning an sfpkg from an external store.

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

-ApplicationTypeVersion

Specifies the application type version, as it was defined in the application manifest. The application type name and the application type version uniquely identify the application type. This is needed when provisioning an sfpkg application package file from an external store.

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

-Async

The command returns as soon as the registration request is accepted by the cluster. Use the Get-ServiceFabricApplicationType command to query the status of the registration request. Using this switch avoids having to provide large -TimeoutSec values when registering large application packages.

Type:SwitchParameter
Position:Named
Default value:False
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

Inputs

None

Outputs

System.Object