您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Service Fabric 应用程序和服务清单Service Fabric application and service manifests

本文介绍如何使用 ApplicationManifest.xml 和 ServiceManifest.xml 文件定义 Service Fabric 应用程序和服务并对其进行版本控制。This article describes how Service Fabric applications and services are defined and versioned using the ApplicationManifest.xml and ServiceManifest.xml files. 有关更多详细示例,请参阅应用程序和服务清单示例For more detailed examples, see application and service manifest examples. 这些清单文件的 XML 架构记录在 ServiceFabricServiceModel.xsd 架构文档中。The XML schema for these manifest files is documented in ServiceFabricServiceModel.xsd schema documentation.

警告

清单 XML 文件架构强制对子元素进行正确排序。The manifest XML file schema enforces correct ordering of child elements. 作为局部解决方法,创作或修改任何 Service Fabric 清单时,请在 Visual Studio中打开“C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd”。As a partial workaround, open "C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd" in Visual Studio while authoring or modifying any of the Service Fabric manifests. 这样一来,可以检查子元素的排序并提供 intelli-sense。This will allow you to check the ordering of child elements and provides intelli-sense.

使用 ServiceManifest.xml 描述服务Describe a service in ServiceManifest.xml

服务清单以声明方式定义服务类型和版本。The service manifest declaratively defines the service type and version. 它指定服务元数据,例如服务类型、运行状况属性、负载均衡度量值、服务二进制文件和配置文件。It specifies service metadata such as service type, health properties, load-balancing metrics, service binaries, and configuration files. 换言之,它描述了组成一个服务包以支持一个或多个服务类型的代码、配置和数据包。Put another way, it describes the code, configuration, and data packages that compose a service package to support one or more service types. 服务清单可以包含多个代码、配置和数据包,可以独立进行版本控制。A service manifest can contain multiple code, configuration, and data packages, which can be versioned independently. 以下是投票示例应用程序的 ASP.NET Core Web 前端服务的服务清单(以下是一些更详细的示例):Here is a service manifest for the ASP.NET Core web front-end service of the Voting sample application (and here are some more detailed examples):

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="VotingWebPkg"
                 Version="1.0.0"
                 xmlns="http://schemas.microsoft.com/2011/01/fabric"
                 xmlns:xsd="https://www.w3.org/2001/XMLSchema"
                 xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
  <ServiceTypes>
    <!-- This is the name of your ServiceType. 
         This name must match the string used in RegisterServiceType call in Program.cs. -->
    <StatelessServiceType ServiceTypeName="VotingWebType" />
  </ServiceTypes>

  <!-- Code package is your service executable. -->
  <CodePackage Name="Code" Version="1.0.0">
    <EntryPoint>
      <ExeHost>
        <Program>VotingWeb.exe</Program>
        <WorkingFolder>CodePackage</WorkingFolder>
      </ExeHost>
    </EntryPoint>
  </CodePackage>

  <!-- Config package is the contents of the Config directory under PackageRoot that contains an 
       independently-updateable and versioned set of custom configuration settings for your service. -->
  <ConfigPackage Name="Config" Version="1.0.0" />

  <Resources>
    <Endpoints>
      <!-- This endpoint is used by the communication listener to obtain the port on which to 
           listen. Please note that if your service is partitioned, this port is shared with 
           replicas of different partitions that are placed in your code. -->
      <Endpoint Protocol="http" Name="ServiceEndpoint" Type="Input" Port="8080" />
    </Endpoints>
  </Resources>
</ServiceManifest>

Version 特性是未结构化的字符串,并且不由系统进行分析。Version attributes are unstructured strings and not parsed by the system. 版本特性用于对每个组件进行版本控制,以进行升级。Version attributes are used to version each component for upgrades.

ServiceTypes 声明此清单中的 CodePackages 支持哪些服务类型。ServiceTypes declares what service types are supported by CodePackages in this manifest. 当一种服务针对这些服务类型之一进行实例化时,可激活此清单中声明的所有代码包,方法是运行这些代码包的入口点。When a service is instantiated against one of these service types, all code packages declared in this manifest are activated by running their entry points. 生成的进程应在运行时注册所支持的服务类型。The resulting processes are expected to register the supported service types at run time. 在清单级别而不是代码包级别声明服务类型。Service types are declared at the manifest level and not the code package level. 因此,当存在多个代码包时,每当系统查找任何一种声明的服务类型时,它们都会被激活。So when there are multiple code packages, they are all activated whenever the system looks for any one of the declared service types.

EntryPoint 指定的可执行文件通常是长时间运行的服务主机。The executable specified by EntryPoint is typically the long-running service host. SetupEntryPoint 是特权入口点,以与 Service Fabric(通常是 LocalSystem 帐户)相同的凭据先于任何其他入口点运行。SetupEntryPoint is a privileged entry point that runs with the same credentials as Service Fabric (typically the LocalSystem account) before any other entry point. 提供单独的设置入口点可避免长时间使用高特权运行服务主机。The presence of a separate setup entry point avoids having to run the service host with high privileges for extended periods of time. EntryPoint 指定的可执行文件在 SetupEntryPoint 成功退出后运行。The executable specified by EntryPoint is run after SetupEntryPoint exits successfully. 如果进程总是终止或出现故障,则监视并重启所产生的过程(再次从“SetupEntryPoint”开始)。If the process ever terminates or crashes, the resulting process is monitored and restarted (beginning again with SetupEntryPoint).

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

  • 设置和初始化服务可执行文件所需的环境变量。Setting up and initializing environment variables that the service executable needs. 这并不限于通过 Service Fabric 编程模型编写的可执行文件。This 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

EnvironmentVariables(上一示例中未设置),提供为此代码包设置的环境变量列表。EnvironmentVariables (not set in the preceding example) provides a list of environment variables that are set for this code package. 环境变量可以在 ApplicationManifest.xml 中重写,以便为不同的服务实例提供不同的值。Environment variables can be overridden in the ApplicationManifest.xml to provide different values for different service instances.

DataPackage(上一示例中未设置),声明一个由 Name 属性命名的文件夹,该文件夹中包含进程会在运行时使用的任意静态数据。DataPackage (not set in the preceding example) declares a folder, named by the Name attribute, that contains arbitrary static data to be consumed by the process at run time.

ConfigPackage 声明一个由 Name 特性命名的文件夹,该文件夹中包含 Settings.xml 文件。ConfigPackage declares a folder, named by the Name attribute, that contains a Settings.xml file. 此设置文件包含用户定义的键值对设置部分,进程可在运行时读回这些设置。The settings file contains sections of user-defined, key-value pair settings that the process reads back at run time. 升级期间,如果仅更改了 ConfigPackage 版本,则不重启正在运行的进程。During an upgrade, if only the ConfigPackage version has changed, then the running process is not restarted. 相反,回调会向进程通知配置设置已更改,以便可以重新动态加载这些设置。Instead, a callback notifies the process that configuration settings have changed so they can be reloaded dynamically. 下面是 Settings.xml 文件的一个示例:Here is an example Settings.xml file:

<Settings xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Section Name="MyConfigurationSection">
    <Parameter Name="MySettingA" Value="Example1" />
    <Parameter Name="MySettingB" Value="Example2" />
  </Section>
</Settings>

Service Fabric 服务“终结点”是 Service Fabric 资源的一个示例。A Service Fabric Service Endpoint is an example of a Service Fabric Resource. 无需更改已编译的代码,即可声明/更改 Service Fabric 资源。A Service Fabric Resource can be declared/changed without changing the compiled code. 可以通过应用程序清单中的 SecurityGroup 控制对服务清单中指定 Service Fabric 资源的访问。Access to the Service Fabric Resources that are specified in the service manifest can be controlled through the SecurityGroup in the application manifest. 在服务清单中定义了终结点资源时,如果未显式指定端口,则 Service Fabric 从保留的应用程序端口范围中分配端口。When an Endpoint Resource is defined in the service manifest, Service Fabric assigns ports from the reserved application port range when a port isn't specified explicitly. 详细了解指定或替代终结点资源Read more about specifying or overriding endpoint resources.

警告

设计静态端口不应与 Clustermanifest.xml 中指定的应用程序端口范围重叠。By design static ports should not overlap with application port range specified in the ClusterManifest. 如果指定静态端口, 请将其分配到应用程序端口范围外, 否则将导致端口冲突。If you specify a static port, assign it outside of application port range, otherwise it will result in port conflicts. 使用 release 6.5 CU2, 我们将在检测到此类冲突时发出运行状况警告, 但允许部署与发货6.5 行为保持同步。With release 6.5CU2 we will issue a Health Warning when we detect such a conflict but let the deployment continue in sync with the shipped 6.5 behaviour. 但是, 我们可能会阻止应用程序在下一个主要版本中进行部署。However, we may prevent the application deployment from the next major releases.

使用 ApplicationManifest.xml 描述应用程序Describe an application in ApplicationManifest.xml

应用程序清单以声明方式描述应用程序类型和版本。The application manifest declaratively describes the application type and version. 它指定服务组合元数据(如稳定名称、分区方案、实例计数/复制因子、安全/隔离策略、布置约束、配置替代和成分服务类型)。It specifies service composition metadata such as stable names, partitioning scheme, instance count/replication factor, security/isolation policy, placement constraints, configuration overrides, and constituent service types. 此外还描述用于容纳应用程序的负载均衡域。The load-balancing domains into which the application is placed are also described.

因此,应用程序清单在应用程序级别描述元素,并引用了一个或多个服务清单,以组成应用程序类型。Thus, an application manifest describes elements at the application level and references one or more service manifests to compose an application type. 以下是投票示例应用程序的应用程序清单(以下是一些更详细的示例):Here is the application manifest for the Voting sample application (and here are some more detailed examples):

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" ApplicationTypeName="VotingType" ApplicationTypeVersion="1.0.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Parameters>
    <Parameter Name="VotingData_MinReplicaSetSize" DefaultValue="3" />
    <Parameter Name="VotingData_PartitionCount" DefaultValue="1" />
    <Parameter Name="VotingData_TargetReplicaSetSize" DefaultValue="3" />
    <Parameter Name="VotingWeb_InstanceCount" DefaultValue="-1" />
  </Parameters>
  <!-- Import the ServiceManifest from the ServicePackage. The ServiceManifestName and ServiceManifestVersion 
       should match the Name and Version attributes of the ServiceManifest element defined in the 
       ServiceManifest.xml file. -->
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="VotingDataPkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
  </ServiceManifestImport>
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="VotingWebPkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
  </ServiceManifestImport>
  <DefaultServices>
    <!-- The section below creates instances of service types, when an instance of this 
         application type is created. You can also create one or more instances of service type using the 
         ServiceFabric PowerShell module.
         
         The attribute ServiceTypeName below must match the name defined in the imported ServiceManifest.xml file. -->
    <Service Name="VotingData">
      <StatefulService ServiceTypeName="VotingDataType" TargetReplicaSetSize="[VotingData_TargetReplicaSetSize]" MinReplicaSetSize="[VotingData_MinReplicaSetSize]">
        <UniformInt64Partition PartitionCount="[VotingData_PartitionCount]" LowKey="0" HighKey="25" />
      </StatefulService>
    </Service>
    <Service Name="VotingWeb" ServicePackageActivationMode="ExclusiveProcess">
      <StatelessService ServiceTypeName="VotingWebType" InstanceCount="[VotingWeb_InstanceCount]">
        <SingletonPartition />
         <PlacementConstraints>(NodeType==NodeType0)</PlacementConstraints
      </StatelessService>
    </Service>
  </DefaultServices>
</ApplicationManifest>

类似于服务清单,Version 特性是未结构化的字符串,并且不由系统进行分析。Like service manifests, Version attributes are unstructured strings and are not parsed by the system. 版本特性也用于对每个组件进行版本控制,以进行升级。Version attributes are also used to version each component for upgrades.

Parameters,定义整个应用程序清单中使用的参数。Parameters defines the parameters used throughout the application manifest. 当应用程序已实例化并可替代应用程序或服务配置设置时,可以提供这些参数的值。The values of these parameters can be supplied when the application is instantiated and can override application or service configuration settings. 如果在应用程序实例化期间该值未更改,则使用默认参数值。The default parameter value is used if the value is not changed during application instantiation. 若要了解如何维护不同的应用程序和用于单个环境的服务参数,请参阅管理多个环境的应用程序参数To learn how to maintain different application and service parameters for individual environments, see Managing application parameters for multiple environments.

ServiceManifestImport 包含对组成此应用程序类型的服务清单的引用。ServiceManifestImport contains references to service manifests that compose this application type. 应用程序清单可以包含多个服务清单导入,每个导入都可独立进行版本控制。An application manifest can contain multiple service manifest imports, each one can be versioned independently. 导入的服务清单将确定此应用程序类型中哪些服务类型有效。Imported service manifests determine what service types are valid within this application type. 在 ServiceManifestImport 中,可以重写 Settings.xml 中的配置值和 ServiceManifest.xml 文件中的环境变量。Within the ServiceManifestImport, you override configuration values in Settings.xml and environment variables in ServiceManifest.xml files. Policies(上一示例中未设置),用于终结点绑定、安全性和访问以及包共享,可以在导入的服务清单上进行设置。Policies (not set in the preceding example) for end-point binding, security and access, and package sharing can be set on imported service manifests. 有关详细信息,请参阅配置应用程序的安全策略For more information, see Configure security policies for your application.

DefaultServices 声明每当一个应用程序依据此应用程序类型进行实例化时自动创建的服务实例。DefaultServices declares service instances that are automatically created whenever an application is instantiated against this application type. 默认服务只是提供便利,创建后,它们的行为在每个方面都与常规服务类似。Default services are just a convenience and behave like normal services in every respect after they have been created. 它们与应用程序实例中的任何其他服务一起升级,并且也可以将它们删除。They are upgraded along with any other services in the application instance and can be removed as well. 应用程序清单可以包含多个默认服务。An application manifest can contain multiple default services.

Certificates(上一示例中未设置),声明用于设置 HTTPS 终结点或用于加密应用程序清单中的机密的证书。Certificates (not set in the preceding example) declares the certificates used to setup HTTPS endpoints or encrypt secrets in the application manifest.

放置约束是定义服务运行位置的语句。Placement Constraints are the statements that define where services should run. 这些语句附加到您为一个或多个节点属性选择的各个服务。These statements are attached to individual services that you select for one or more node properties. 有关详细信息, 请参阅放置约束和节点属性语法For more information, see Placement constraints and node property syntax

Policies(在前面的示例中未设置)描述要在应用程序级别设置的日志收集、默认运行方式帐户运行状况安全访问策略,包括服务是否可以访问 Service Fabric 运行时。Policies (not set in the preceding example) describes the log collection, default run-as, health, and security access policies to set at the application level, including whether the service(s) have access to the Service Fabric runtime.

备注

默认情况下,Service Fabric 应用程序可以通过以下形式访问 Service Fabric 运行时:终结点(接受应用程序特定请求)和环境变量(指向包含 Fabric 和应用程序特定文件的主机上的文件路径)。By default, Service Fabric applications have access to the Service Fabric runtime, in the form of an endpoint accepting application-specific requests, and environment variables pointing to file paths on the host containing Fabric and application-specific files. 在应用程序托管不受信任的代码(即其出处未知或应用程序所有者知道其执行起来不安全)时,请考虑禁止进行此访问。Consider disabling this access when the application hosts untrusted code (i.e. code whose provenance is unknown, or which the application owner knows not to be safe to execute). 有关详细信息,请参阅 Service Fabric 中的安全最佳做法For more information, please see security best practices in Service Fabric.

Principals(上一示例中未设置),描述运行服务并确保服务资源安全所需的安全主体(用户或组)。Principals (not set in the preceding example) describe the security principals (users or groups) required to run services and secure service resources. Policies 部分中会引用 Principals。Principals are referenced in the Policies sections.

后续步骤Next steps