Empacotar e implementar um executável existente no Service Fabric

Artigo
06/01/2023

Ao empacotar um executável existente como executável convidado, pode optar por utilizar um modelo de projeto do Visual Studio ou criar o pacote de aplicação manualmente. Com o Visual Studio, a estrutura do pacote de aplicação e os ficheiros de manifesto são criados pelo novo modelo de projeto.

Dica

A forma mais fácil de empacotar um executável existente do Windows num serviço é utilizar o Visual Studio e o Linux para utilizar o Yeoman

Utilizar o Visual Studio para empacotar e implementar um executável existente

O Visual Studio fornece um modelo de serviço do Service Fabric para o ajudar a implementar um executável convidado num cluster do Service Fabric.

SelecioneNovo Projeto de Ficheiro> e crie uma aplicação do Service Fabric.
Selecione Executável convidado como modelo de serviço.
Clique em Procurar para selecionar a pasta com o executável e preencha os restantes parâmetros para criar o serviço.
- Comportamento do Pacote de Código. Pode ser definido para copiar todo o conteúdo da sua pasta para o Visual Studio Project, o que é útil se o executável não for alterado. Se espera que o executável mude e pretenda a capacidade de recolher novas compilações dinamicamente, pode optar por ligar à pasta. Pode utilizar pastas ligadas ao criar o projeto de aplicação no Visual Studio. Isto liga à localização de origem a partir do projeto, o que lhe permite atualizar o executável convidado no destino de origem. Estas atualizações fazem parte do pacote de aplicações na compilação.
- O programa especifica o executável que deve ser executado para iniciar o serviço.
- Os argumentos especificam os argumentos que devem ser transmitidos para o executável. Pode ser uma lista de parâmetros com argumentos.
- WorkingFolder especifica o diretório de trabalho para o processo que vai ser iniciado. Pode especificar três valores:
  - CodeBase especifica que o diretório de trabalho vai ser definido para o diretório de código no pacote de aplicação (Code diretório mostrado na estrutura de ficheiros anterior).
  - CodePackage especifica que o diretório de trabalho vai ser definido para a raiz do pacote de aplicação (GuestService1Pkg mostrado na estrutura de ficheiros anterior).
  - Work especifica que os ficheiros são colocados num subdiretório chamado work.
Dê um nome ao serviço e clique em OK.
Se o seu serviço precisar de um ponto final para comunicação, agora pode adicionar o protocolo, a porta e o tipo ao ficheiro ServiceManifest.xml. Por exemplo: <Endpoint Name="NodeAppTypeEndpoint" Protocol="http" Port="3000" UriScheme="http" PathSuffix="myapp/" Type="Input" />.
Agora, pode utilizar o pacote e publicar a ação no cluster local ao depurar a solução no Visual Studio. Quando estiver pronto, pode publicar a aplicação num cluster remoto ou dar entrada da solução para o controlo de origem.
Leia a sua aplicação em execução para ver como ver o serviço executável convidado em execução no Service Fabric Explorer.

Para obter instruções de exemplo, veja Criar a sua primeira aplicação executável convidada com o Visual Studio.

Empacotar vários executáveis com o Visual Studio

Pode utilizar o Visual Studio para produzir um pacote de aplicação que contém vários executáveis convidados. Depois de adicionar o primeiro executável convidado, clique com o botão direito do rato no projeto da aplicação e selecione o serviço Add-New> Service Fabric para adicionar o segundo projeto executável convidado à solução.

Nota

Se optar por ligar a origem no projeto do Visual Studio, ao criar a solução do Visual Studio, certifique-se de que o pacote de aplicações está atualizado com as alterações na origem.

Utilizar o Yeoman para empacotar e implementar um executável existente no Linux

O procedimento para criar e implementar um executável convidado no Linux é o mesmo que implementar uma aplicação C# ou Java.

Num terminal, escreva yo azuresfguest.
Dê um nome à aplicação.
Dê um nome ao seu serviço e forneça os detalhes, incluindo o caminho do executável e os parâmetros com os quais tem de ser invocado.

O Yeoman cria um pacote de aplicação com os ficheiros de aplicação e manifesto adequados, juntamente com scripts de instalação e desinstalação.

Empacotar vários executáveis com o Yeoman no Linux

Para adicionar outro serviço a uma aplicação já criada com o yo, execute os seguintes passos:

Altere o diretório para a raiz da aplicação existente. Por exemplo, cd ~/YeomanSamples/MyApplication, se MyApplication é a aplicação criada por Yeoman.
Execute yo azuresfguest:AddService e forneça os detalhes necessários.

Empacotar e implementar manualmente um executável existente

O processo de empacotamento manual de um executável convidado baseia-se nos seguintes passos gerais:

Crie a estrutura do diretório do pacote.
Adicione o código e os ficheiros de configuração da aplicação.
Edite o ficheiro de manifesto do serviço.
Edite o ficheiro de manifesto da aplicação.

Criar a estrutura do diretório do pacote

Pode começar por criar a estrutura do diretório, conforme descrito em Empacotar uma Aplicação do Azure Service Fabric.

Adicionar o código e os ficheiros de configuração da aplicação

Depois de criar a estrutura do diretório, pode adicionar os ficheiros de código e configuração da aplicação nos diretórios de código e configuração. Também pode criar diretórios ou subdiretórios adicionais nos diretórios de código ou configuração.

O Service Fabric faz um xcopy dos conteúdos do diretório de raiz da aplicação, pelo que não existe uma estrutura predefinida para utilizar além de criar dois diretórios, código e definições principais. (Se quiser, pode escolher nomes diferentes. Estão disponíveis mais detalhes na secção seguinte.)

Nota

Certifique-se de que inclui todos os ficheiros e dependências de que a aplicação precisa. O Service Fabric copia o conteúdo do pacote de aplicação em todos os nós do cluster onde os serviços da aplicação vão ser implementados. O pacote deve conter todo o código que a aplicação precisa de executar. Não suponha que as dependências já estão instaladas.

Editar o ficheiro de manifesto do serviço

O próximo passo é editar o ficheiro de manifesto do serviço para incluir as seguintes informações:

O nome do tipo de serviço. Este é um ID que o Service Fabric utiliza para identificar um serviço.
O comando a utilizar para iniciar a aplicação (ExeHost).
Qualquer script que precise de ser executado para configurar a aplicação (SetupEntrypoint).

Segue-se um exemplo de um ServiceManifest.xml ficheiro:

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" Name="NodeApp" Version="1.0.0.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">
   <ServiceTypes>
      <StatelessServiceType ServiceTypeName="NodeApp" UseImplicitHost="true"/>
   </ServiceTypes>
   <CodePackage Name="code" Version="1.0.0.0">
      <SetupEntryPoint>
         <ExeHost>
             <Program>scripts\launchConfig.cmd</Program>
         </ExeHost>
      </SetupEntryPoint>
      <EntryPoint>
         <ExeHost>
            <Program>node.exe</Program>
            <Arguments>bin/www</Arguments>
            <WorkingFolder>CodePackage</WorkingFolder>
         </ExeHost>
      </EntryPoint>
   </CodePackage>
   <Resources>
      <Endpoints>
         <Endpoint Name="NodeAppTypeEndpoint" Protocol="http" Port="3000" Type="Input" />
      </Endpoints>
   </Resources>
</ServiceManifest>

As secções seguintes passam por cima das diferentes partes do ficheiro que precisa de atualizar.

Atualizar ServiceTypes

<ServiceTypes>
  <StatelessServiceType ServiceTypeName="NodeApp" UseImplicitHost="true" />
</ServiceTypes>

Pode escolher qualquer nome que pretenda para ServiceTypeName. O valor é utilizado no ApplicationManifest.xml ficheiro para identificar o serviço.
Especifique UseImplicitHost="true". Este atributo indica ao Service Fabric que o serviço se baseia numa aplicação autónoma, pelo que tudo o que o Service Fabric precisa de fazer é iniciou-o como um processo e monitorizar o seu estado de funcionamento.

Atualizar CodePackage

O elemento CodePackage especifica a localização (e a versão) do código do serviço.

<CodePackage Name="Code" Version="1.0.0.0">

O Name elemento é utilizado para especificar o nome do diretório no pacote de aplicação que contém o código do serviço. CodePackage também tem o version atributo. Isto pode ser utilizado para especificar a versão do código e também pode potencialmente ser utilizado para atualizar o código do serviço através da infraestrutura de gestão do ciclo de vida da aplicação no Service Fabric.

Opcional: Update SetupEntrypoint

<SetupEntryPoint>
   <ExeHost>
       <Program>scripts\launchConfig.cmd</Program>
   </ExeHost>
</SetupEntryPoint>

O elemento SetupEntryPoint é utilizado para especificar qualquer ficheiro executável ou em lote que deve ser executado antes de o código do serviço ser iniciado. É um passo opcional, pelo que não precisa de ser incluído se não for necessária inicialização. O SetupEntryPoint é executado sempre que o serviço é reiniciado.

Existe apenas um SetupEntryPoint, pelo que os scripts de configuração têm de ser agrupados num único ficheiro de lote se a configuração da aplicação necessitar de vários scripts. O SetupEntryPoint pode executar qualquer tipo de ficheiro: ficheiros executáveis, ficheiros em lote e cmdlets do PowerShell. Para obter mais detalhes, veja Configurar SetupEntryPoint.

No exemplo anterior, o SetupEntryPoint executa um ficheiro de lote chamado LaunchConfig.cmd que está localizado no scripts subdiretório do diretório de código (partindo do princípio de que o elemento WorkingFolder está definido como CodeBase).

Atualizar o EntryPoint

<EntryPoint>
  <ExeHost>
    <Program>node.exe</Program>
    <Arguments>bin/www</Arguments>
    <WorkingFolder>CodeBase</WorkingFolder>
  </ExeHost>
</EntryPoint>

O EntryPoint elemento no ficheiro de manifesto de serviço é utilizado para especificar como iniciar o serviço.

O ExeHost elemento especifica o executável (e os argumentos) que devem ser utilizados para iniciar o serviço. Opcionalmente, pode adicionar o IsExternalExecutable="true" atributo a para ExeHost indicar que o programa é um executável externo fora do pacote de código. Por exemplo, <ExeHost IsExternalExecutable="true">.

Program especifica o nome do executável que deve iniciar o serviço.
Arguments especifica os argumentos que devem ser transmitidos para o executável. Pode ser uma lista de parâmetros com argumentos.
WorkingFolder especifica o diretório de trabalho para o processo que vai ser iniciado. Pode especificar três valores:
- CodeBase especifica que o diretório de trabalho vai ser definido para o diretório de código no pacote de aplicação (Code diretório na estrutura de ficheiros anterior).
- CodePackage especifica que o diretório de trabalho vai ser definido como a raiz do pacote de aplicação (GuestService1Pkg na estrutura de ficheiros anterior).
  - Work especifica que os ficheiros são colocados num subdiretório chamado work.

A WorkingFolder é útil para definir o diretório de trabalho correto para que os caminhos relativos possam ser utilizados pela aplicação ou pelos scripts de inicialização.

Atualizar Pontos Finais e registar-se no Serviço de Nomenclatura para comunicação

<Endpoints>
   <Endpoint Name="NodeAppTypeEndpoint" Protocol="http" Port="3000" Type="Input" />
</Endpoints>

No exemplo anterior, o Endpoint elemento especifica os pontos finais em que a aplicação pode escutar. Neste exemplo, a aplicação Node.js escuta em http na porta 3000.

Além disso, pode pedir ao Service Fabric para publicar este ponto final no Serviço de Nomenclatura para que outros serviços possam detetar o endereço de ponto final deste serviço. Isto permite-lhe comunicar entre serviços que são executáveis convidados. O endereço do ponto final publicado é do formulário UriScheme://IPAddressOrFQDN:Port/PathSuffix. UriScheme e PathSuffix são atributos opcionais. IPAddressOrFQDN é o endereço IP ou o nome de domínio completamente qualificado do nó em que este executável é colocado e é calculado para si.

No exemplo seguinte, assim que o serviço for implementado, no Service Fabric Explorer verá um ponto final semelhante ao http://10.1.4.92:3000/myapp/ publicado para a instância de serviço. Em alternativa, se este for um computador local, verá http://localhost:3000/myapp/.

<Endpoints>
   <Endpoint Name="NodeAppTypeEndpoint" Protocol="http" Port="3000"  UriScheme="http" PathSuffix="myapp/" Type="Input" />
</Endpoints>

Pode utilizar estes endereços com proxy inverso para comunicar entre serviços.

Editar o ficheiro de manifesto da aplicação

Depois de configurar o Servicemanifest.xml ficheiro, tem de fazer algumas alterações ao ApplicationManifest.xml ficheiro para garantir que o tipo de serviço e o nome corretos são utilizados.

<?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="NodeAppType" ApplicationTypeVersion="1.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">
   <ServiceManifestImport>
      <ServiceManifestRef ServiceManifestName="NodeApp" ServiceManifestVersion="1.0.0.0" />
   </ServiceManifestImport>
</ApplicationManifest>

ServiceManifestImport

ServiceManifestImport No elemento, pode especificar um ou mais serviços que pretende incluir na aplicação. Os serviços são referenciados com ServiceManifestName, que especifica o nome do diretório onde o ServiceManifest.xml ficheiro está localizado.

<ServiceManifestImport>
  <ServiceManifestRef ServiceManifestName="NodeApp" ServiceManifestVersion="1.0.0.0" />
</ServiceManifestImport>

Configurar o registo

Para executáveis convidados, é útil poder ver os registos da consola para saber se os scripts de configuração e a aplicação apresentam erros. O redirecionamento da consola pode ser configurado no ServiceManifest.xml ficheiro com o ConsoleRedirection elemento .

Aviso

Nunca utilize a política de redirecionamento da consola numa aplicação implementada em produção, uma vez que esta ação pode afetar a ativação pós-falha da aplicação. Utilize-o apenas para fins locais de desenvolvimento e depuração.

<EntryPoint>
  <ExeHost>
    <Program>node.exe</Program>
    <Arguments>bin/www</Arguments>
    <WorkingFolder>CodeBase</WorkingFolder>
    <ConsoleRedirection FileRetentionCount="5" FileMaxSizeInKb="2048"/>
  </ExeHost>
</EntryPoint>

ConsoleRedirection pode ser utilizado para redirecionar a saída da consola (stdout e stderr) para um diretório de trabalho. Isto fornece a capacidade de verificar se não existem erros durante a configuração ou execução da aplicação no cluster do Service Fabric.

FileRetentionCount determina quantos ficheiros são guardados no diretório de trabalho. Um valor de 5, por exemplo, significa que os ficheiros de registo das cinco execuções anteriores são armazenados no diretório de trabalho.

FileMaxSizeInKb especifica o tamanho máximo dos ficheiros de registo.

Os ficheiros de registo são guardados num dos diretórios de trabalho do serviço. Para determinar onde estão localizados os ficheiros, utilize Service Fabric Explorer para determinar em que nó o serviço está a ser executado e em que diretório de trabalho está a ser utilizado. Este processo é abordado mais adiante neste artigo.

Implementação

O último passo é implementar a sua aplicação. O seguinte script do PowerShell mostra como implementar a sua aplicação no cluster de desenvolvimento local e iniciar um novo serviço do Service Fabric.


Connect-ServiceFabricCluster localhost:19000

Write-Host 'Copying application package...'
Copy-ServiceFabricApplicationPackage -ApplicationPackagePath 'C:\Dev\MultipleApplications' -ImageStoreConnectionString 'file:C:\SfDevCluster\Data\ImageStoreShare' -ApplicationPackagePathInImageStore 'nodeapp'

Write-Host 'Registering application type...'
Register-ServiceFabricApplicationType -ApplicationPathInImageStore 'nodeapp'

New-ServiceFabricApplication -ApplicationName 'fabric:/nodeapp' -ApplicationTypeName 'NodeAppType' -ApplicationTypeVersion 1.0

New-ServiceFabricService -ApplicationName 'fabric:/nodeapp' -ServiceName 'fabric:/nodeapp/nodeappservice' -ServiceTypeName 'NodeApp' -Stateless -PartitionSchemeSingleton -InstanceCount 1

Dica

Comprima o pacote antes de copiar para o arquivo de imagens se o pacote for grande ou tiver muitos ficheiros. Leia mais aqui.

Um serviço do Service Fabric pode ser implementado em várias "configurações". Por exemplo, pode ser implementado como uma única ou múltiplas instâncias ou pode ser implementado de forma a que exista uma instância do serviço em cada nó do cluster do Service Fabric.

O InstanceCount parâmetro do New-ServiceFabricService cmdlet é utilizado para especificar quantas instâncias do serviço devem ser iniciadas no cluster do Service Fabric. Pode definir o InstanceCount valor, consoante o tipo de aplicação que está a implementar. Os dois cenários mais comuns são:

InstanceCount = "1". Neste caso, apenas uma instância do serviço é implementada no cluster. O agendador do Service Fabric determina em que nó o serviço vai ser implementado.
InstanceCount ="-1". Neste caso, uma instância do serviço é implementada em todos os nós do cluster do Service Fabric. O resultado é ter uma (e apenas uma) instância do serviço para cada nó no cluster.

Esta é uma configuração útil para aplicações de front-end (por exemplo, um ponto final REST), porque as aplicações cliente precisam de "ligar" a qualquer um dos nós no cluster para utilizar o ponto final. Esta configuração também pode ser utilizada quando, por exemplo, todos os nós do cluster do Service Fabric estão ligados a um balanceador de carga. Em seguida, o tráfego de cliente pode ser distribuído pelo serviço que está em execução em todos os nós do cluster.

Verificar a aplicação em execução

No Service Fabric Explorer, identifique o nó onde o serviço está em execução. Neste exemplo, é executado no Node1:

Nó onde o serviço está em execução

Se navegar para o nó e navegar para a aplicação, verá as informações essenciais do nó, incluindo a respetiva localização no disco.

Localização no disco

Se navegar para o diretório com o Explorador de Servidores, pode encontrar o diretório de trabalho e a pasta de registo do serviço, conforme mostrado na seguinte captura de ecrã:

Localização do registo

Passos seguintes

Neste artigo, aprendeu a empacotar um executável convidado e a implementá-lo no Service Fabric. Veja os seguintes artigos para obter informações e tarefas relacionadas.

Exemplo para empacotar e implementar um executável convidado, incluindo uma ligação para o pré-lançamento da ferramenta de empacotamento
Exemplo de dois executáveis convidados (C# e nodejs) a comunicar através do serviço Naming com REST
Criar a sua primeira aplicação do Service Fabric com o Visual Studio