打包应用程序Package an application

本文介绍如何打包 Service Fabric 应用程序并为部署做好准备。This article describes how to package a Service Fabric application and make it ready for deployment.

包布局Package layout

必须将应用程序清单、一个或多个服务清单和其他必要的包文件组织为一个特定的布局,以部署到 Service Fabric 群集中。The application manifest, one or more service manifests, and other necessary package files must be organized in a specific layout for deployment into a Service Fabric cluster. 本文中的示例清单需要组织为以下目录结构:The example manifests in this article would need to be organized in the following directory structure:

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat

文件夹的名称与每个相应元素的 Name 特性匹配。The folders are named to match the Name attributes of each corresponding element. 例如,如果服务清单包含两个名为 MyCodeAMyCodeB 的代码包,则两个同名的文件夹会包含用于每个代码包的必要二进制文件。For example, if the service manifest contained two code packages with the names MyCodeA and MyCodeB, then two folders with the same names would contain the necessary binaries for each code package.

使用 SetupEntryPointUse SetupEntryPoint

SetupEntryPoint 的典型使用场景是需要在服务启动之前运行可执行文件,或需要使用提升的权限来执行操作时。Typical scenarios for using SetupEntryPoint are when you need to run an executable before the service starts or you need to perform an operation with elevated privileges. 例如:For example:

  • 设置和初始化服务可执行文件所需的环境变量。Setting up and initializing environment variables that the service executable needs. 这并不仅限于通过 Service Fabric 编程模型编写的可执行文件。It is not limited to only executables written via the Service Fabric programming models. 例如,npm.exe 需要配置一些环境变量来部署 node.js 应用程序。For example, npm.exe needs some environment variables configured for deploying a node.js application.
  • 通过安装安全证书设置访问控制。Setting up access control by installing security certificates.

有关如何配置 SetupEntryPoint 的详细信息,请参阅配置服务设置入口点的策略For more information on how to configure the SetupEntryPoint, see Configure the policy for a service setup entry point

配置Configure

使用 Visual Studio 生成包Build a package by using Visual Studio

如果使用 Visual Studio 2015 创建应用程序,可以使用 Package 命令自动创建符合上述布局的包。If you use Visual Studio 2015 to create your application, you can use the Package command to automatically create a package that matches the layout described above.

若要创建包,请在解决方案资源管理器中右键单击应用程序项目,并选择 Package 命令,如下所示:To create a package, right-click the application project in Solution Explorer and choose the Package command, as shown below:

使用 Visual Studio 打包应用程序

打包完成后,该包的位置会显示在“输出”窗口中。When packaging is complete, you can find the location of the package in the Output window. 在 Visual Studio 中部署或调试应用程序时,打包步骤自动发生。The packaging step occurs automatically when you deploy or debug your application in Visual Studio.

通过命令行生成一个包Build a package by command line

还可以使用 msbuild.exe 以编程方式打包应用程序。It is also possible to programmatically package up your application using msbuild.exe. 这是 Visual Studio 实际运行的操作,因此输出是相同的。Under the hood, Visual Studio is running it so the output is same.

D:\Temp> msbuild HelloWorld.sfproj /t:Package

测试包Test the package

可以使用 Test-ServiceFabricApplicationPackage 命令,通过 PowerShell 在本地验证包结构。You can verify the package structure locally through PowerShell by using the Test-ServiceFabricApplicationPackage command. 此命令会检查是否存在清单分析问题,并验证所有引用。This command checks for manifest parsing issues and verify all references. 此命令只验证包中目录与文件结构的正确性。This command only verifies the structural correctness of the directories and files in the package. 它不验证任何代码或数据包内容,而只检查所有必要的文件是否存在。It doesn't verify any of the code or data package contents beyond checking that all necessary files are present.

PS D:\temp> Test-ServiceFabricApplicationPackage .\MyApplicationType
False
Test-ServiceFabricApplicationPackage : The EntryPoint MySetup.bat is not found.
FileName: C:\Users\servicefabric\AppData\Local\Temp\TestApplicationPackage_7195781181\nrri205a.e2h\MyApplicationType\MyServiceManifest\ServiceManifest.xml

此错误显示代码包中缺少服务清单 SetupEntryPoint 中引用的 MySetup.bat 文件。This error shows that the MySetup.bat file referenced in the service manifest SetupEntryPoint is missing from the code package. 添加缺少的文件后,应用程序验证通过:After the missing file is added, the application verification passes:

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │       MySetup.bat
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat

PS D:\temp> Test-ServiceFabricApplicationPackage .\MyApplicationType
True
PS D:\temp>

如果应用程序已定义应用程序参数,则可以将参数传递到 Test-ServiceFabricApplicationPackage 中进行适当验证。If your application has application parameters defined, you can pass them in Test-ServiceFabricApplicationPackage for proper validation.

如果知道要在其中部署应用程序的群集,则建议传入 ImageStoreConnectionString 参数。If you know the cluster where the application will be deployed, it is recommended you pass in the ImageStoreConnectionString parameter. 在这种情况下,还需要针对已在群集中运行的前一应用程序版本对包进行验证。In this case, the package is also validated against previous versions of the application that are already running in the cluster. 例如,验证可检测是否部署了版本相同但内容不同的包。For example, the validation can detect whether a package with the same version but different content was already deployed.

在应用程序正确打包并通过验证后,可以考虑将包进行压缩以便更快地执行部署操作。Once the application is packaged correctly and passes validation, consider compressing the package for faster deployment operations.

压缩包Compress a package

包较大或包含大量文件时,可压缩该包以提高部署速度。When a package is large or has many files, you can compress it for faster deployment. 压缩可以减少文件的数量和包大小。Compression reduces the number of files and the package size. 与上传未压缩的包相比,对于压缩的应用程序包,上传应用程序包可能要花费更长的时间,尤其是当压缩是在复制过程中执行的时。For a compressed application package, uploading the application package may take longer compared to uploading the uncompressed package, especially if compression is done as part of copy. 使用压缩,注册注销应用程序类型时速度会更快。With compression, registering and un-registering the application type are faster.

压缩包和未压缩包的部署机制相同。The deployment mechanism is same for compressed and uncompressed packages. 如果为压缩包,则存储在群集映像存储等位置,并且在应用程序运行前在节点上解压缩。If the package is compressed, it is stored as such in the cluster image store and it's uncompressed on the node before the application is run. 压缩会将有效的 Service Fabric 包替换为已压缩版本。The compression replaces the valid Service Fabric package with the compressed version. 文件夹必须允许写入操作。The folder must allow write permissions. 对已压缩的包运行压缩不会产生任何更改。Running compression on an already compressed package yields no changes.

可以通过使用 CompressPackage 开关运行 Powershell 命令 Copy-ServiceFabricApplicationPackage 来压缩包。You can compress a package by running the Powershell command Copy-ServiceFabricApplicationPackage with CompressPackage switch. 可以通过使用 UncompressPackage 开关运行同一命令来解压缩包。You can uncompress the package with the same command, using UncompressPackage switch.

以下命令可压缩包,但不会将包复制到映像存储区。The following command compresses the package without copying it to the image store. 通过使用不带 SkipCopy 标志的 Copy-ServiceFabricApplicationPackage 将压缩的包复制到一个或多个 Service Fabric 群集中。You can copy a compressed package to one or more Service Fabric clusters, as needed, using Copy-ServiceFabricApplicationPackage without the SkipCopy flag. 包中现在包括 codeconfigdata 包的压缩文件。The package now includes zipped files for the code, config, and data packages. 应用程序清单和服务清单不会被压缩,因为它们是许多内部操作所必需的。The application manifest and the service manifests are not zipped, because they are needed for many internal operations. 例如,进行某些验证时的包共享、应用程序类型名称和版本提取都需要访问清单。For example, package sharing, application type name and version extraction for certain validations all need to access the manifests. 压缩清单会使这些操作无效。Zipping the manifests would make these operations inefficient.

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │       MySetup.bat
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat
PS D:\temp> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath .\MyApplicationType -CompressPackage -SkipCopy

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
       ServiceManifest.xml
       MyCode.zip
       MyConfig.zip
       MyData.zip

或者,也可以使用 Copy-ServiceFabricApplicationPackage 一步压缩并复制包。Alternatively, you can compress and copy the package with Copy-ServiceFabricApplicationPackage in one step. 如果包较大,请提供足够的超时时间,以为包压缩和上传到群集预留时间。If the package is large, provide a high enough timeout to allow time for both the package compression and the upload to the cluster.

PS D:\temp> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath .\MyApplicationType -ApplicationPackagePathInImageStore MyApplicationType -ImageStoreConnectionString fabric:ImageStore -CompressPackage -TimeoutSec 5400

在内部,Service Fabric 将计算应用程序包的校验和以进行验证。Internally, Service Fabric computes checksums for the application packages for validation. 使用压缩时,会对每个包的压缩版本计算校验和。When using compression, the checksums are computed on the zipped versions of each package. 基于同一个应用程序包生成新 zip 会创建不同的校验和。Generating a new zip from the same application package creates different checksums. 若要防止验证错误,请使用差异预配To prevent validation errors, use diff provisioning. 使用此选项时,不要在新版本中包括未更改的包。With this option, do not include the unchanged packages in the new version. 相反,请直接从新的服务清单中引用它们。Instead, reference them directly from the new service manifest.

如果差异预配不是一个选项并且你必须包括这些包,请为 codeconfigdata 包生成新版本以避免校验和不匹配。If diff provisioning is not an option and you must include the packages, generate new versions for the code, config, and data packages to avoid checksum mismatch. 当使用压缩的包时,无论以前的版本是否使用压缩,都需要为未更改的包生成新版本。Generating new versions for unchanged packages is necessary when a compressed package is used, regardless of whether previous version uses compression or not.

现在已将包进行了正确打包、验证和压缩(如需要),因此可以将其部署到一个或多个 Service Fabric 群集。The package is now packaged correctly, validated, and compressed (if needed), so it is ready for deployment to one or more Service Fabric clusters.

使用 Visual Studio 部署时压缩包Compress packages when deploying using Visual Studio

可以指示 Visual Studio 在部署时压缩包,具体方法为将 CopyPackageParameters 元素添加到发布配置文件,并将 CompressPackage 属性设置为 trueYou can instruct Visual Studio to compress packages on deployment, by adding the CopyPackageParameters element to your publish profile, and set the CompressPackage attribute to true.

<PublishProfile xmlns="http://schemas.microsoft.com/2015/05/fabrictools">
    <ClusterConnectionParameters ConnectionEndpoint="mycluster.chinanorth.cloudapp.chinacloudapi.cn" />
    <ApplicationParameterFile Path="..\ApplicationParameters\Cloud.xml" />
    <CopyPackageParameters CompressPackage="true"/>
</PublishProfile>

创建 sfpkgCreate an sfpkg

从版本 6.1 开始,Service Fabric 允许从外部存储区进行预配。Starting with version 6.1, Service Fabric allows provisioning from an external store. 使用此选项时,不必将应用程序包复制到映像存储区。With this option, the application package doesn't have to be copied to the image store. 相反,你可以创建一个 sfpkg 并将其上传到外部存储区,然后在预配时将下载 URI 提供给 Service Fabric。Instead, you can create an sfpkg and upload it to an external store, then provide the download URI to Service Fabric when provisioning. 可以将同一个包预配给多个群集。The same package can be provisioned to multiple clusters. 从外部存储区进行预配会节省将包复制到每个群集所需的时间。Provisioning from the external store saves the time needed to copy the package to each cluster.

sfpkg 文件是一个 zip 文件,其中包含初始应用程序包并具有扩展名“.sfpkg”。The sfpkg file is a zip that contains the initial application package and has the extension ".sfpkg". 在此 zip 文件内,应用程序包可以是压缩的,也可以是未压缩的。Inside the zip, the application package can be compressed or uncompressed. 前文所述,zip 文件内应用程序包的压缩是在代码、配置和数据包级别执行的。The compression of the application package inside the zip is done at code, config, and data package levels, as mentioned earlier.

若要创建 sfpkg,请首先创建包含原始应用程序包(压缩的或未压缩的)的文件夹。To create an sfpkg, start with a folder that contains the original application package, compressed or not. 然后,使用任何实用程序以扩展名“.sfpkg”压缩该文件夹。Then, use any utility to zip the folder with the extension ".sfpkg". 例如,使用 ZipFile.CreateFromDirectoryFor example, use ZipFile.CreateFromDirectory.

ZipFile.CreateFromDirectory(appPackageDirectoryPath, sfpkgFilePath);

必须在带外将 sfpkg 上传到 Service Fabric 外部的外部存储区。The sfpkg must be uploaded to the external store out of band, outside of Service Fabric. 外部存储区可以是公开了 REST http 或 https 终结点的任何存储区。The external store can be any store that exposes a REST http or https endpoint. 在预配期间,Service Fabric 执行 GET 操作来下载 sfpkg 应用程序包,因此该存储区必须允许对该包进行读取访问。During provisioning, Service Fabric executes a GET operation to download the sfpkg application package, so the store must allow READ access for the package.

若要预配该包,请使用外部预配,这需要使用下载 URI 和应用程序类型信息。To provision the package, use external provision, which requires the download URI and the application type information.

Note

基于映像存储区相对路径进行预配当前不支持 sfpkg 文件。Provisioning based on image store relative path doesn't currently support sfpkg files. 因此,不应当将 sfpkg 复制到映像存储区。Therefore, the sfpkg should not be copied to the image store.

后续步骤Next steps

部署和删除应用程序 介绍如何使用 PowerShell 来管理应用程序实例Deploy and remove applications describes how to use PowerShell to manage application instances

管理多个环境的应用程序参数 介绍如何为不同的应用程序实例配置参数和环境变量。Managing application parameters for multiple environments describes how to configure parameters and environment variables for different application instances.

配置应用程序的安全策略 介绍如何根据安全策略运行服务,从而限制访问。Configure security policies for your application describes how to run services under security policies to restrict access.