Aplicativo do Service Fabric e manifestos de serviço

  • Artigo

Este artigo descreve como os aplicativos e serviços do Service Fabric são definidos e versionados usando os arquivos ApplicationManifest.xml e ServiceManifest.xml. Para obter exemplos mais detalhados, consulte Exemplos de manifesto de aplicativos e serviços. O esquema XML para esses arquivos de manifesto está documentado na documentação do esquema ServiceFabricServiceModel.xsd.

Aviso

O esquema de arquivo XML de manifesto impõe a ordenação correta dos elementos filho. Como uma solução parcial, abra "C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd" no Visual Studio enquanto cria ou modifica qualquer um dos manifestos do Service Fabric. Isso permitirá que você verifique a ordem dos elementos filho e fornece intelli-sense.

Descrever um serviço no ServiceManifest.xml

O manifesto de serviço define declarativamente o tipo e a versão do serviço. Ele especifica metadados de serviço, como tipo de serviço, propriedades de integridade, métricas de balanceamento de carga, binários de serviço e arquivos de configuração. Dito de outra forma, ele descreve o código, a configuração e os pacotes de dados que compõem um pacote de serviço para oferecer suporte a um ou mais tipos de serviço. Um manifesto de serviço pode conter vários pacotes de código, configuração e dados, que podem ser versionados independentemente. Aqui está um manifesto de serviço para o serviço front-end da Web ASP.NET Core do aplicativo de exemplo Voting (e aqui estão alguns exemplos mais detalhados):

<?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 analisadas pelo sistema. Os atributos de versão são usados para fazer a versão de cada componente para atualizações.

ServiceTypes declara quais tipos de serviço são suportados por CodePackages neste manifesto. Quando um serviço é instanciado em relação a um desses tipos de serviço, todos os pacotes de código declarados neste manifesto são ativados executando seus pontos de entrada. Espera-se que os processos resultantes registrem os tipos de serviço suportados em tempo de execução. Os tipos de serviço são declarados no nível do manifesto e não no nível do pacote de código. Assim, quando há vários pacotes de código, todos eles são ativados sempre que o sistema procura qualquer um dos tipos de serviço declarados.

O executável especificado pelo EntryPoint é normalmente o host de serviço de longa execução. SetupEntryPoint é um ponto de entrada privilegiado que é executado com as mesmas credenciais do Service Fabric (normalmente a conta LocalSystem ) antes de qualquer outro ponto de entrada. A presença de um ponto de entrada de configuração separado evita ter que executar o host de serviço com altos privilégios por longos períodos de tempo. O executável especificado por EntryPoint é executado depois que SetupEntryPoint é encerrado com êxito. Se o processo for encerrado ou falhar, o processo resultante será monitorado e reiniciado (começando novamente com SetupEntryPoint).

Cenários típicos para usar SetupEntryPoint são quando você executa um executável antes do serviço iniciar ou executa uma operação com privilégios elevados. Por exemplo:

  • Configuração e inicialização de variáveis de ambiente de que o executável do serviço precisa. Isso não se limita apenas aos executáveis escritos por meio dos modelos de programação do Service Fabric. Por exemplo, npm.exe precisa de algumas variáveis de ambiente configuradas para implantar um aplicativo Node.js.
  • Configurar o controlo de acesso através da instalação de certificados de segurança.

Para obter mais informações sobre como configurar o SetupEntryPoint, consulte Configurar a política para um ponto de entrada de configuração de serviço.

EnvironmentVariables (não definido no exemplo anterior) fornece uma lista de variáveis de ambiente definidas para este pacote de código. As variáveis de ApplicationManifest.xml ambiente podem ser substituídas no para fornecer valores diferentes para instâncias de serviço diferentes.

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.

ConfigPackage declara uma pasta, nomeada pelo atributo Name , que contém um arquivo Settings.xml . 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 em tempo de execução. Durante uma atualização, se apenas a versão do ConfigPackagefor alterada, o processo em execução não será reiniciado. 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. Aqui está um exemplo Settings.xml arquivo:

<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 do Service Fabric é um exemplo de um Recurso do Service Fabric. Um recurso do Service Fabric pode ser declarado/alterado sem alterar o código compilado. O acesso aos Recursos do Service Fabric especificados no manifesto de serviço pode ser controlado por meio do SecurityGroup no manifesto do aplicativo. Quando um recurso de ponto de extremidade é definido no manifesto de serviço, o Service Fabric atribui portas do intervalo de portas reservadas do aplicativo quando uma porta não é especificada explicitamente. Leia mais sobre como especificar ou substituir recursos de ponto de extremidade.

Aviso

Por design, as portas estáticas não devem se sobrepor ao intervalo de portas do aplicativo especificado no 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. Com a versão 6.5CU2, emitiremos um Aviso de Integridade quando detetarmos tal conflito, mas deixaremos que a implantação continue em sincronia com o comportamento 6.5 enviado. No entanto, podemos impedir a implantação do aplicativo nas próximas versões principais.

Descrever um aplicativo no ApplicationManifest.xml

O manifesto do aplicativo descreve declarativamente o tipo e a versão do aplicativo. Ele especifica metadados de composição de serviço, como nomes estáveis, esquema de particionamento, contagem de instâncias/fator de replicação, política de segurança/isolamento, restrições de posicionamento, substituições de configuração e tipos de serviço constituintes. Os domínios de balanceamento de carga nos quais o aplicativo é colocado também são descritos.

Assim, um manifesto de aplicativo descreve elementos no nível do aplicativo e faz referência a um ou mais manifestos de serviço para compor um tipo de aplicativo. Aqui está o manifesto do aplicativo para o aplicativo de exemplo de votação (e aqui estão alguns exemplos mais detalhados):

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

Como os manifestos de serviço, os atributos Version são cadeias de caracteres não estruturadas e não são analisados pelo sistema. Os atributos de versão também são usados para fazer a versão de cada componente para atualizações.

Parameters define os parâmetros usados em todo o manifesto do aplicativo. Os valores desses parâmetros podem ser fornecidos quando o aplicativo é instanciado e podem substituir as definições de configuração do aplicativo ou serviço. O valor do parâmetro padrão será usado se o valor não for alterado durante a instanciação do aplicativo. Para saber como manter diferentes parâmetros de aplicativo e serviço para ambientes individuais, consulte Gerenciando parâmetros de aplicativo para vários ambientes.

ServiceManifestImport contém referências a manifestos de serviço que compõem esse tipo de aplicativo. Um manifesto de aplicativo pode conter várias importações de manifesto de serviço e cada uma pode ser versionada independentemente. Os manifestos de serviço importados determinam quais tipos de serviço são válidos nesse tipo de aplicativo. Dentro do ServiceManifestImport, você substitui valores de configuração em variáveis de Settings.xml e ambiente em arquivos ServiceManifest.xml. As políticas (não definidas no exemplo anterior) para vinculação de ponto final, segurança e acesso, e compartilhamento de pacotes podem ser definidas em manifestos de serviço importados. Para obter mais informações, consulte Configurar políticas de segurança para seu aplicativo.

DefaultServices declara instâncias de serviço que são criadas automaticamente sempre que um aplicativo é instanciado em relação a esse tipo de aplicativo. Os serviços padrão são apenas uma conveniência e se comportam como serviços normais em todos os aspetos depois de serem criados. Eles são atualizados junto com quaisquer outros serviços na instância do aplicativo e também podem ser removidos. Um manifesto de aplicativo pode conter vários serviços padrão.

Aviso

DefaultServices foi preterido em favor de StartupServices.xml. Você pode ler sobre StartupServices.xml em Apresentando StartupServices.xml no aplicativo Service Fabric.

Certificados (não definidos no exemplo anterior) declara os certificados usados para configurar pontos de extremidade HTTPS ou criptografar segredos no manifesto do aplicativo.

Restrições de posicionamento são as instruções que definem onde os serviços devem ser executados. Essas instruções são anexadas a serviços individuais selecionados para uma ou mais propriedades de nó. Para obter mais informações, consulte Restrições de posicionamento e sintaxe de propriedade do nó.

As políticas (não definidas no exemplo anterior) descrevem a coleção de logs, a execução padrão, a integridade e as políticas de acesso de segurança a serem definidas no nível do aplicativo, incluindo se o(s) serviço(s) têm acesso ao tempo de execução do Service Fabric.

Nota

Um cluster do Service Fabric é um único locatário por design e os aplicativos hospedados são considerados confiáveis. Se você estiver pensando em hospedar aplicativos não confiáveis, consulte Hospedando aplicativos não confiáveis em um cluster do Service Fabric.

Entidades ( não definidas no exemplo anterior) descrevem as entidades de segurança (usuários ou grupos) necessárias para executar serviços e proteger recursos de serviço. Os principais são referenciados nas seções Políticas .

Próximos passos