Especificar recursos num manifesto do serviço

Descrição geral

Os aplicativos e serviços do Service Fabric são definidos e versionados usando arquivos de manifesto. Para obter uma visão geral de nível superior de ServiceManifest.xml e ApplicationManifest.xml, consulte Aplicativo e manifestos de serviço do Service Fabric.

O manifesto de serviço permite que os recursos usados pelo serviço sejam declarados ou alterados sem alterar o código compilado. O Service Fabric oferece suporte à configuração de recursos de ponto de extremidade para o serviço. O acesso aos recursos especificados no manifesto de serviço pode ser controlado por meio do SecurityGroup no manifesto do aplicativo. A declaração de recursos permite que esses recursos sejam alterados no momento da implantação, o que significa que o serviço não precisa introduzir um novo mecanismo de configuração. A definição de esquema para o arquivo ServiceManifest.xml é instalada com o SDK e as ferramentas do Service Fabric para C:\Arquivos de Programas\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd e está documentada na documentação do esquema ServiceFabricServiceModel.xsd.

Pontos finais

Quando um recurso de ponto de extremidade é definido no manifesto do serviço, o Service Fabric atribui portas do intervalo de portas reservadas do aplicativo quando uma porta não é especificada explicitamente. Por exemplo, examine o ponto de extremidade ServiceEndpoint1 especificado no trecho de manifesto fornecido após este parágrafo. Além disso, os serviços também podem solicitar uma porta específica em um recurso. As réplicas de serviço em execução em nós de cluster diferentes podem receber números de porta diferentes, enquanto as réplicas de um serviço em execução no mesmo nó compartilham a porta. As réplicas de serviço podem usar essas portas conforme necessário para replicação e escuta de solicitações de clientes.

Ao ativar um serviço que especifica um ponto de extremidade https, o Service Fabric definirá a entrada de controle de acesso para a porta, vinculará o certificado de servidor especificado à porta e também concederá a identidade de que o serviço está sendo executado como permissões para a chave privada do certificado. O fluxo de ativação é invocado sempre que o Service Fabric é iniciado ou quando a declaração de certificado do aplicativo é alterada por meio de uma atualização. O certificado de ponto de extremidade também será monitorado quanto a alterações/renovações e as permissões serão periodicamente reaplicadas conforme necessário.

Após o término do serviço, o Service Fabric limpará a entrada de controle de acesso do ponto de extremidade e removerá a vinculação do certificado. No entanto, quaisquer permissões aplicadas à chave privada do certificado não serão limpas.

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint1" Protocol="http"/>
    <Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
    <Endpoint Name="ServiceEndpoint3" Protocol="https"/>
  </Endpoints>
</Resources>

Se houver vários pacotes de código em um único pacote de serviço, o pacote de código também precisará ser referenciado na seção Pontos de extremidade . Por exemplo, se ServiceEndpoint2a e ServiceEndpoint2b forem pontos de extremidade do mesmo pacote de serviço fazendo referência a pacotes de código diferentes, o pacote de código correspondente a cada ponto de extremidade será esclarecido da seguinte maneira:

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint2a" Protocol="http" Port="802" CodePackageRef="Code1"/>
    <Endpoint Name="ServiceEndpoint2b" Protocol="http" Port="801" CodePackageRef="Code2"/>
  </Endpoints>
</Resources>

Consulte Configurando serviços confiáveis com monitoração de estado para ler mais sobre como referenciar pontos de extremidade a partir do arquivo de configurações do pacote de configuração (settings.xml).

Exemplo: especificar um ponto de extremidade HTTP para o seu serviço

O manifesto <de serviço a seguir define um recurso de ponto de extremidade TCP e dois recursos de ponto de extremidade HTTP no elemento Resources> .

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="Stateful1Pkg"
                 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 the RegisterServiceType call in Program.cs. -->
    <StatefulServiceType ServiceTypeName="Stateful1Type" HasPersistedState="true" />
  </ServiceTypes>

  <!-- Code package is your service executable. -->
  <CodePackage Name="Code" Version="1.0.0">
    <EntryPoint>
      <ExeHost>
        <Program>Stateful1.exe</Program>
      </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 number on which to
           listen. Note that if your service is partitioned, this port is shared with
           replicas of different partitions that are placed in your code. -->
      <Endpoint Name="ServiceEndpoint1" Protocol="http"/>
      <Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
      <Endpoint Name="ServiceEndpoint3" Protocol="https"/>
      <Endpoint Name="ServiceEndpoint4" Protocol="https" Port="14023"/>

      <!-- This endpoint is used by the replicator for replicating the state of your service.
           This endpoint is configured through the ReplicatorSettings config section in the Settings.xml
           file under the ConfigPackage. -->
      <Endpoint Name="ReplicatorEndpoint" />
    </Endpoints>
  </Resources>
</ServiceManifest>

Exemplo: especificar um ponto de extremidade HTTPS para o seu serviço

O protocolo HTTPS fornece autenticação de servidor e também é usado para criptografar a comunicação cliente-servidor. Para habilitar HTTPS em seu serviço do Service Fabric, especifique o protocolo na seção Recursos -> Pontos de extremidade - Ponto de extremidade do> manifesto do serviço, conforme mostrado anteriormente para o ponto de extremidade ServiceEndpoint3.

Aqui está um exemplo de ApplicationManifest demonstrando a configuração necessária para um ponto de extremidade HTTPS. O certificado de servidor/ponto de extremidade pode ser declarado por impressão digital ou nome comum do assunto, e um valor deve ser fornecido. O EndpointRef é uma referência a EndpointResource em ServiceManifest e cujo protocolo deve ter sido definido para o protocolo 'https'. Você pode adicionar mais de um EndpointCertificate.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest ApplicationTypeName="Application1Type"
                     ApplicationTypeVersion="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">
  <Parameters>
    <Parameter Name="Stateful1_MinReplicaSetSize" DefaultValue="3" />
    <Parameter Name="Stateful1_PartitionCount" DefaultValue="1" />
    <Parameter Name="Stateful1_TargetReplicaSetSize" DefaultValue="3" />
  </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="Stateful1Pkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <Policies>
      <EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint3"/>
      <EndpointBindingPolicy CertificateRef="SslCertByCN" EndpointRef="ServiceEndpoint4"/>
    </Policies>
  </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 by using the
         Service Fabric PowerShell module.

         The attribute ServiceTypeName below must match the name defined in the imported ServiceManifest.xml file. -->
    <Service Name="Stateful1">
      <StatefulService ServiceTypeName="Stateful1Type" TargetReplicaSetSize="[Stateful1_TargetReplicaSetSize]" MinReplicaSetSize="[Stateful1_MinReplicaSetSize]">
        <UniformInt64Partition PartitionCount="[Stateful1_PartitionCount]" LowKey="-9223372036854775808" HighKey="9223372036854775807" />
      </StatefulService>
    </Service>
  </DefaultServices>
  <Certificates>
    <EndpointCertificate Name="SslCertByTP" X509FindValue="FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F0" X509StoreName="MY" />  
    <EndpointCertificate Name="SslCertByCN" X509FindType="FindBySubjectName" X509FindValue="ServiceFabric-EndpointCertificateBinding-Test" X509StoreName="MY" />  
  </Certificates>
</ApplicationManifest>

Para clusters Linux, o armazenamento MY assume como padrão a pasta /var/lib/sfcerts.

Para obter um exemplo de um aplicativo completo que faz uso de um ponto de extremidade HTTPS, consulte Adicionar um ponto de extremidade HTTPS a um serviço front-end da API Web Core do ASP.NET usando o Kestrel.

ACLing de porta para pontos de extremidade HTTP

O Service Fabric automaticamente terá pontos de extremidade ACL HTTP(S) especificados por padrão. Ele não executará ACLing automática se um ponto de extremidade não tiver uma SecurityAccessPolicy associada a ele e o Service Fabric estiver configurado para ser executado usando uma conta com privilégios de Administrador.

Substituindo pontos de extremidade no ServiceManifest.xml

No ApplicationManifest, adicione uma seção ResourceOverrides, que será irmã da seção ConfigOverrides. Nesta seção, você pode especificar a substituição para a seção Pontos de extremidade na seção de recursos especificada no manifesto do serviço. A substituição de pontos de extremidade é suportada no tempo de execução 5.7.217/SDK 2.7.217 e superior.

Para substituir EndPoint em ServiceManifest usando ApplicationParameters, altere o ApplicationManifest como tal:

Na seção ServiceManifestImport, adicione uma nova seção "ResourceOverrides".

<ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="Stateless1Pkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <ResourceOverrides>
      <Endpoints>
        <Endpoint Name="ServiceEndpoint" Port="[Port]" Protocol="[Protocol]" Type="[Type]" />
        <Endpoint Name="ServiceEndpoint1" Port="[Port1]" Protocol="[Protocol1] "/>
      </Endpoints>
    </ResourceOverrides>
        <Policies>
           <EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint"/>
        </Policies>
  </ServiceManifestImport>

Nos parâmetros adicione abaixo:

  <Parameters>
    <Parameter Name="Port" DefaultValue="" />
    <Parameter Name="Protocol" DefaultValue="" />
    <Parameter Name="Type" DefaultValue="" />
    <Parameter Name="Port1" DefaultValue="" />
    <Parameter Name="Protocol1" DefaultValue="" />
  </Parameters>

Ao implantar o aplicativo, você pode passar esses valores como ApplicationParameters. Por exemplo:

PS C:\> New-ServiceFabricApplication -ApplicationName fabric:/myapp -ApplicationTypeName "AppType" -ApplicationTypeVersion "1.0.0" -ApplicationParameter @{Port='1001'; Protocol='https'; Type='Input'; Port1='2001'; Protocol='http'}

Nota: Se o valor fornecido para um determinado ApplicationParameter estiver vazio, voltaremos ao valor padrão fornecido no ServiceManifest para o EndPointName correspondente.

Por exemplo:

Se no ServiceManifest você especificou

  <Resources>
    <Endpoints>
      <Endpoint Name="ServiceEndpoint1" Protocol="tcp"/>
    </Endpoints>
  </Resources>

Suponha que o valor Port1 e Protocol1 para parâmetros Application é nulo ou vazio. A porta será decidida pelo ServiceFabric e o protocolo será tcp.

Suponha que você especifique um valor errado. Digamos que para Port você especificou um valor de string "Foo" em vez de um int. O comando New-ServiceFabricApplication falhará com um erro: The override parameter with name 'ServiceEndpoint1' attribute 'Port1' in section 'ResourceOverrides' is invalid. The value specified is 'Foo' and required is 'int'.

Passos Seguintes

Este artigo explicou como definir pontos de extremidade no manifesto de serviço do Service Fabric. Para exemplos mais pormenorizados, consulte:

Para obter um passo a passo sobre empacotamento e implantação de um aplicativo existente em um cluster do Service Fabric, consulte: