Service Fabric manifestos de aplicativo e serviçoService Fabric application and service manifests

Este artigo descreve como Service Fabric aplicativos e serviços são definidos e com controle de versão usando os arquivos ApplicationManifest. xml e manifest. xml.This article describes how Service Fabric applications and services are defined and versioned using the ApplicationManifest.xml and ServiceManifest.xml files. Para obter exemplos mais detalhados, consulte exemplos de manifesto de aplicativo e serviço.For more detailed examples, see application and service manifest examples. O esquema XML para esses arquivos de manifesto está documentado na documentação do esquema ServiceFabricServiceModel. xsd.The XML schema for these manifest files is documented in ServiceFabricServiceModel.xsd schema documentation.

Aviso

O esquema de arquivo XML do manifesto impõe a ordenação correta dos elementos filho.The manifest XML file schema enforces correct ordering of child elements. Como uma solução alternativa parcial, abra "C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd" no Visual Studio durante a criação ou modificação de qualquer um dos manifestos Service Fabric.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. Isso permitirá que você verifique a ordem dos elementos filho e fornecerá o IntelliType.This will allow you to check the ordering of child elements and provides intelli-sense.

Descrever um serviço no Service manifest. xmlDescribe a service in ServiceManifest.xml

O manifesto do serviço declarativamente define o tipo de serviço e a versão.The service manifest declaratively defines the service type and version. Ele especifica os metadados do serviço, como o tipo de serviço, as propriedades de integridade, as métricas de balanceamento de carga, os binários de serviço e os arquivos de configuração.It specifies service metadata such as service type, health properties, load-balancing metrics, service binaries, and configuration files. Em outras palavras, ele descreve o código, a configuração e os pacotes de dados que compõem um pacote de serviço para dar suporte a um ou mais tipos de serviço.Put another way, it describes the code, configuration, and data packages that compose a service package to support one or more service types. Um manifesto de serviço pode conter vários pacotes de código, configuração e dados, que podem ter sua versão independente.A service manifest can contain multiple code, configuration, and data packages, which can be versioned independently. Aqui está um manifesto de serviço para o serviço de front-end da Web ASP.NET Core do aplicativo de exemplo de votação (e aqui estão alguns exemplos mais detalhados):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>

Os atributos de versão são cadeias de caracteres não estruturadas e não analisados pelo sistema.Version attributes are unstructured strings and not parsed by the system. Os atributos de versão são usados para a versão de cada componente para atualizações.Version attributes are used to version each component for upgrades.

Os ServiceName declara quais tipos de serviço são suportados pelo CodePackages neste manifesto.ServiceTypes declares what service types are supported by CodePackages in this manifest. Quando um serviço é instanciado em relação a um desses tipos de serviço, todos os pacotes de código declarados nesse manifesto são ativados executando seus pontos de entrada.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. Os processos resultantes são esperados para registrar os tipos de serviço com suporte em tempo de execução.The resulting processes are expected to register the supported service types at run time. Os tipos de serviço são declarados no nível do manifesto e não no nível do pacote de código.Service types are declared at the manifest level and not the code package level. Assim, quando houver vários pacotes de código, eles serão todos ativados sempre que o sistema procurar por qualquer um dos tipos de serviço declarados.So when there are multiple code packages, they are all activated whenever the system looks for any one of the declared service types.

O executável especificado pelo EntryPoint normalmente é o host de serviço de longa execução.The executable specified by EntryPoint is typically the long-running service host. SetupEntryPoint é um ponto de entrada privilegiado que é executado com as mesmas credenciais que Service Fabric (normalmente a conta LocalSystem ) antes de qualquer outro ponto de entrada.SetupEntryPoint is a privileged entry point that runs with the same credentials as Service Fabric (typically the LocalSystem account) before any other entry point. A presença de um ponto de entrada de instalação separado evita a execução do host de serviço com altos privilégios por longos períodos de tempo.The presence of a separate setup entry point avoids having to run the service host with high privileges for extended periods of time. O executável especificado pelo EntryPoint é executado depois que SetupEntryPoint é encerrado com êxito.The executable specified by EntryPoint is run after SetupEntryPoint exits successfully. Se o processo for encerrado ou falhar, o processo resultante será monitorado e reiniciado (começando novamente com SetupEntryPoint).If the process ever terminates or crashes, the resulting process is monitored and restarted (beginning again with SetupEntryPoint).

Cenários típicos para usar SetupEntryPoint são quando você executa um executável antes do início do serviço ou realiza uma operação com privilégios elevados.Typical scenarios for using SetupEntryPoint are when you run an executable before the service starts or you perform an operation with elevated privileges. Por exemplo:For example:

  • Configurar e inicializar variáveis de ambiente que o executável de serviço precisa.Setting up and initializing environment variables that the service executable needs. Isso não se limita apenas a executáveis escritos por meio dos modelos de programação de Service Fabric.This is not limited to only executables written via the Service Fabric programming models. Por exemplo, NPM. exe precisa de algumas variáveis de ambiente configuradas para implantar um aplicativo node. js.For example, npm.exe needs some environment variables configured for deploying a node.js application.
  • Configurando o controle de acesso instalando certificados de segurança.Setting up access control by installing security certificates.

Para obter mais informações sobre como configurar o SetupEntryPoint, consulte Configurar a política para um ponto de entrada de instalação de serviçoFor more information on how to configure the SetupEntryPoint, see Configure the policy for a service setup entry point

EnvironmentVariables (não definido no exemplo anterior) fornece uma lista de variáveis de ambiente que são definidas para este pacote de códigos.EnvironmentVariables (not set in the preceding example) provides a list of environment variables that are set for this code package. As ApplicationManifest.xml variáveis de ambiente podem ser substituídas no para fornecer valores diferentes para diferentes instâncias de serviço.Environment variables can be overridden in the ApplicationManifest.xml to provide different values for different service instances.

DataPackage (não definido no exemplo anterior) declara uma pasta, nomeada pelo atributo Name , que contém dados estáticos arbitrários a serem consumidos pelo processo em tempo de execução.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 declara uma pasta, nomeada pelo atributo Name , que contém um arquivo Settings. xml .ConfigPackage declares a folder, named by the Name attribute, that contains a Settings.xml file. O arquivo de configurações contém seções de configurações de par chave-valor definidas pelo usuário que o processo lê de volta no tempo de execução.The settings file contains sections of user-defined, key-value pair settings that the process reads back at run time. Durante uma atualização, se apenas a versão do ConfigPackage tiver sido alterada, o processo em execução não será reiniciado.During an upgrade, if only the ConfigPackage version has changed, then the running process is not restarted. Em vez disso, um retorno de chamada notifica o processo de que as definições de configuração foram alteradas para que possam ser recarregadas dinamicamente.Instead, a callback notifies the process that configuration settings have changed so they can be reloaded dynamically. Aqui está um exemplo de arquivo 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>

Um ponto de extremidade de serviço Service Fabric é um exemplo de um recurso de Service Fabric.A Service Fabric Service Endpoint is an example of a Service Fabric Resource. Um recurso de Service Fabric pode ser declarado/alterado sem alterar o código compilado.A Service Fabric Resource can be declared/changed without changing the compiled code. O acesso aos recursos de Service Fabric que são especificados no manifesto do serviço pode ser controlado por meio do The de segurança no manifesto do aplicativo.Access to the Service Fabric Resources that are specified in the service manifest can be controlled through the SecurityGroup in the application manifest. Quando um recurso de ponto de extremidade é definido no manifesto do serviço, Service Fabric atribui portas do intervalo de portas do aplicativo reservado quando uma porta não é especificada explicitamente.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. Leia mais sobre como especificar ou substituir recursos de ponto de extremidade.Read more about specifying or overriding endpoint resources.

Aviso

As portas estáticas de design não devem se sobrepor ao intervalo de portas de aplicativo especificado em ClusterManifest.By design static ports should not overlap with application port range specified in the ClusterManifest. Se você especificar uma porta estática, atribua-a fora do intervalo de portas do aplicativo, caso contrário, isso resultará em conflitos de porta.If you specify a static port, assign it outside of application port range, otherwise it will result in port conflicts. Com a versão 6.5 CU2, emitiremos um aviso de integridade quando detectarmos esse conflito, mas permitirá que a implantação continue em sincronia com o comportamento 6,5 enviado.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. No entanto, poderemos impedir a implantação do aplicativo nas próximas versões principais.However, we may prevent the application deployment from the next major releases.

Descrever um aplicativo em ApplicationManifest. xmlDescribe an application in ApplicationManifest.xml

O manifesto do aplicativo descreve declarativamente o tipo e a versão do aplicativo.The application manifest declaratively describes the application type and version. Ele especifica metadados de composição de serviço, como nomes estáveis, esquema de particionamento, fator de replicação/contagem de instâncias, política de segurança/isolamento, restrições de posicionamento, substituições de configuração e tipos de serviço constituintes.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. Os domínios de balanceamento de carga nos quais o aplicativo é colocado também são descritos.The load-balancing domains into which the application is placed are also described.

Assim, um manifesto de aplicativo descreve os elementos no nível do aplicativo e faz referência a um ou mais manifestos do serviço para compor um tipo de aplicativo.Thus, an application manifest describes elements at the application level and references one or more service manifests to compose an application type. Aqui está o manifesto do aplicativo para o aplicativo de exemplo de votação (e aqui estão alguns exemplos mais detalhados):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>

Assim como os manifestos de serviço, os atributos de versão são cadeias de caracteres não estruturados e não são analisados pelo sistema.Like service manifests, Version attributes are unstructured strings and are not parsed by the system. Os atributos de versão também são usados para a versão de cada componente para atualizações.Version attributes are also used to version each component for upgrades.

Parâmetros define os parâmetros usados em todo o manifesto do aplicativo.Parameters defines the parameters used throughout the application manifest. Os valores desses parâmetros podem ser fornecidos quando o aplicativo é instanciado e pode substituir as definições de configuração de aplicativo ou serviço.The values of these parameters can be supplied when the application is instantiated and can override application or service configuration settings. O valor do parâmetro padrão será usado se o valor não for alterado durante a instanciação do aplicativo.The default parameter value is used if the value is not changed during application instantiation. Para saber como manter diferentes parâmetros de aplicativo e de serviço para ambientes individuais, consulte Gerenciando parâmetros de aplicativo para vários ambientes.To learn how to maintain different application and service parameters for individual environments, see Managing application parameters for multiple environments.

ServiceManifestImport contém referências a manifestos de serviço que compõem esse tipo de aplicativo.ServiceManifestImport contains references to service manifests that compose this application type. Um manifesto de aplicativo pode conter várias importações de manifesto de serviço, cada uma delas pode ter sua versão independente.An application manifest can contain multiple service manifest imports, each one can be versioned independently. Os manifestos do serviço importados determinam quais tipos de serviço são válidos nesse tipo de aplicativo.Imported service manifests determine what service types are valid within this application type. Dentro do ServiceManifestImport, você substitui os valores de configuração em Settings. xml e variáveis de ambiente nos arquivos do arquivo manifest. xml.Within the ServiceManifestImport, you override configuration values in Settings.xml and environment variables in ServiceManifest.xml files. Políticas do (não definido no exemplo anterior) para associação de ponto de extremidade, segurança e acesso e compartilhamento de pacotes podem ser definidos em manifestos de serviço importados.Policies (not set in the preceding example) for end-point binding, security and access, and package sharing can be set on imported service manifests. Para obter mais informações, consulte Configurar políticas de segurança para seu aplicativo.For more information, see Configure security policies for your application.

DefaultServices declara as instâncias de serviço que são criadas automaticamente sempre que um aplicativo é instanciado em relação a esse tipo de aplicativo.DefaultServices declares service instances that are automatically created whenever an application is instantiated against this application type. Os serviços padrão são apenas uma conveniência e se comportam como serviços normais em todos os aspectos depois de terem sido criados.Default services are just a convenience and behave like normal services in every respect after they have been created. Eles são atualizados juntamente com quaisquer outros serviços na instância do aplicativo e também podem ser removidos.They are upgraded along with any other services in the application instance and can be removed as well. Um manifesto de aplicativo pode conter vários serviços padrão.An application manifest can contain multiple default services.

Certificados do (não definido no exemplo anterior) declara os certificados usados para Configurar pontos de extremidade https ou criptografar segredos no manifesto do aplicativo.Certificates (not set in the preceding example) declares the certificates used to setup HTTPS endpoints or encrypt secrets in the application manifest.

As restrições de posicionamento são as instruções que definem onde os serviços devem ser executados.Placement Constraints are the statements that define where services should run. Essas instruções são anexadas a serviços individuais que você seleciona para uma ou mais propriedades de nó.These statements are attached to individual services that you select for one or more node properties. Para obter mais informações, consulte restrição de posicionamento e sintaxe de propriedade de nóFor more information, see Placement constraints and node property syntax

Políticas do (não definido no exemplo anterior) descreve a coleta de log, execução padrão, integridadee políticas de acesso de segurança para definir no nível do aplicativo, incluindo se os serviços têm acesso ao tempo de execução de 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.

Nota

Por padrão, os aplicativos Service Fabric têm acesso ao tempo de execução do Service Fabric, na forma de um ponto de extremidade que aceita solicitações específicas do aplicativo e variáveis de ambiente apontando para caminhos de arquivo no host que contém arquivos específicos de aplicativo e de malha .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. Considere desabilitar esse acesso quando o aplicativo hospedar código não confiável (ou seja, código cuja comprovação é desconhecida ou que o proprietário do aplicativo sabe que não deve ser seguro de ser executado).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). Para obter mais informações, consulte práticas recomendadas de segurança em Service Fabric.For more information, please see security best practices in Service Fabric.

Entidades de segurança (não definido no exemplo anterior) descreva as entidades de segurança (usuários ou grupos) necessárias para executar serviços e proteger os recursos de serviço.Principals (not set in the preceding example) describe the security principals (users or groups) required to run services and secure service resources. As entidades de segurança são referenciadas nas seções de políticas .Principals are referenced in the Policies sections.

Passos seguintesNext steps