Introdução ao Reliable ServicesGet started with Reliable Services

Um aplicativo de Service Fabric do Azure contém um ou mais serviços que executam seu código.An Azure Service Fabric application contains one or more services that run your code. Este guia mostra como criar aplicativos de Service Fabric com e sem estado com Reliable Services.This guide shows you how to create both stateless and stateful Service Fabric applications with Reliable Services.

Conceitos básicosBasic concepts

Para começar a usar o Reliable Services, você só precisa entender alguns conceitos básicos:To get started with Reliable Services, you only need to understand a few basic concepts:

  • Tipo de serviço: Esta é a implementação do seu serviço.Service type: This is your service implementation. Ele é definido pela classe que você escreve que se StatelessService estende e quaisquer outros códigos ou dependências usados nele, juntamente com um nome e um número de versão.It is defined by the class you write that extends StatelessService and any other code or dependencies used therein, along with a name and a version number.
  • Instância de serviço nomeada: Para executar o serviço, você cria instâncias nomeadas do seu tipo de serviço, de forma semelhante a criar instâncias de objeto de um tipo de classe.Named service instance: To run your service, you create named instances of your service type, much like you create object instances of a class type. Uma instância de serviço tem um nome na forma de um URI usando a "Fabric:/" esquema, como "Fabric:/MyApp/MyService".A service instance has a name in the form of a URI using the "fabric:/" scheme, such as "fabric:/MyApp/MyService".
  • Host de serviço: As instâncias de serviço nomeado que você cria precisam ser executadas dentro de um processo de host.Service host: The named service instances you create need to run inside a host process. O host de serviço é apenas um processo em que as instâncias do serviço podem ser executadas.The service host is just a process where instances of your service can run.
  • Registro de serviço: O registro faz tudo junto.Service registration: Registration brings everything together. O tipo de serviço deve ser registrado com o tempo de execução de Service Fabric em um host de serviço para permitir que Service Fabric criem instâncias dele para serem executados.The service type must be registered with the Service Fabric runtime in a service host to allow Service Fabric to create instances of it to run.

Criar um serviço sem estadoCreate a stateless service

Um serviço sem estado é um tipo de serviço que é atualmente a norma em aplicativos em nuvem.A stateless service is a type of service that is currently the norm in cloud applications. Ele é considerado sem estado porque o serviço em si não contém dados que precisam ser armazenados de maneira confiável ou tornarem-se altamente disponíveis.It is considered stateless because the service itself does not contain data that needs to be stored reliably or made highly available. Se uma instância de um serviço sem estado for desligada, todo o seu estado interno será perdido.If an instance of a stateless service shuts down, all of its internal state is lost. Nesse tipo de serviço, o estado deve ser persistido em um repositório externo, como tabelas do Azure ou um banco de dados SQL, para que ele se tornará altamente disponível e confiável.In this type of service, state must be persisted to an external store, such as Azure Tables or a SQL database, for it to be made highly available and reliable.

Inicie o Visual Studio 2017 ou o Visual Studio 2019 como administrador e crie um novo projeto de aplicativo Service Fabric chamado HelloWorld:Launch Visual Studio 2017 or Visual Studio 2019 as an administrator, and create a new Service Fabric application project named HelloWorld:

Use a caixa de diálogo novo projeto para criar um novo aplicativo Service Fabric

Em seguida, crie um projeto de serviço sem estado usando o .NET Core 2,0 chamado HelloWorldStateless:Then create a stateless service project using .NET Core 2.0 named HelloWorldStateless:

Na segunda caixa de diálogo, crie um projeto de serviço sem estado

Sua solução agora contém dois projetos:Your solution now contains two projects:

  • HelloWorld.HelloWorld. Este é o projeto de aplicativo que contém seus Serviços.This is the application project that contains your services. Ele também contém o manifesto do aplicativo que descreve o aplicativo, bem como vários scripts do PowerShell que ajudam você a implantar seu aplicativo.It also contains the application manifest that describes the application, as well as a number of PowerShell scripts that help you to deploy your application.
  • HelloWorldStateless.HelloWorldStateless. Este é o projeto de serviço.This is the service project. Ele contém a implementação do serviço sem estado.It contains the stateless service implementation.

Implementar o serviçoImplement the service

Abra o arquivo HelloWorldStateless.cs no projeto de serviço.Open the HelloWorldStateless.cs file in the service project. No Service Fabric, um serviço pode executar qualquer lógica de negócios.In Service Fabric, a service can run any business logic. A API de serviço fornece dois pontos de entrada para seu código:The service API provides two entry points for your code:

  • Um método de ponto de entrada aberto, chamado RunAsync, no qual você pode começar a executar qualquer carga de trabalho, incluindo cargas de trabalho de computação de longa execução.An open-ended entry point method, called RunAsync, where you can begin executing any workloads, including long-running compute workloads.
protected override async Task RunAsync(CancellationToken cancellationToken)
{
    ...
}
  • Um ponto de entrada de comunicação no qual você pode conectar sua pilha de comunicação de sua escolha, como ASP.NET Core.A communication entry point where you can plug in your communication stack of choice, such as ASP.NET Core. É aí que você pode começar a receber solicitações de usuários e outros serviços.This is where you can start receiving requests from users and other services.
protected override IEnumerable<ServiceInstanceListener> CreateServiceInstanceListeners()
{
    ...
}

Neste tutorial, iremos nos concentrar no método de RunAsync() ponto de entrada.In this tutorial, we will focus on the RunAsync() entry point method. É aí que você pode iniciar imediatamente a execução do código.This is where you can immediately start running your code. O modelo de projeto inclui uma implementação de RunAsync() exemplo do que incrementa uma contagem sem interrupção.The project template includes a sample implementation of RunAsync() that increments a rolling count.

Nota

Para obter detalhes sobre como trabalhar com uma pilha de comunicação, consulte Service Fabric serviços de API Web com hospedagem interna OWINFor details about how to work with a communication stack, see Service Fabric Web API services with OWIN self-hosting

RunAsyncRunAsync

protected override async Task RunAsync(CancellationToken cancellationToken)
{
    // TODO: Replace the following sample code with your own logic
    //       or remove this RunAsync override if it's not needed in your service.

    long iterations = 0;

    while (true)
    {
        cancellationToken.ThrowIfCancellationRequested();

        ServiceEventSource.Current.ServiceMessage(this.Context, "Working-{0}", ++iterations);

        await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
    }
}

A plataforma chama esse método quando uma instância de um serviço é colocada e está pronta para ser executada.The platform calls this method when an instance of a service is placed and ready to execute. Para um serviço sem estado, isso simplesmente significa quando a instância do serviço é aberta.For a stateless service, that simply means when the service instance is opened. Um token de cancelamento é fornecido para coordenar quando sua instância de serviço precisa ser fechada.A cancellation token is provided to coordinate when your service instance needs to be closed. Em Service Fabric, esse ciclo de abertura/fechamento de uma instância de serviço pode ocorrer muitas vezes durante o tempo de vida do serviço como um todo.In Service Fabric, this open/close cycle of a service instance can occur many times over the lifetime of the service as a whole. Isso pode ocorrer por vários motivos, incluindo:This can happen for various reasons, including:

  • O sistema move as instâncias de serviço para o balanceamento de recursos.The system moves your service instances for resource balancing.
  • As falhas ocorrem em seu código.Faults occur in your code.
  • O aplicativo ou o sistema é atualizado.The application or system is upgraded.
  • O hardware subjacente passa por uma interrupção.The underlying hardware experiences an outage.

Essa orquestração é gerenciada pelo sistema para manter seu serviço altamente disponível e equilibrado corretamente.This orchestration is managed by the system to keep your service highly available and properly balanced.

RunAsync()Não deve bloquear de forma síncrona.RunAsync() should not block synchronously. Sua implementação de RunAsync deve retornar uma tarefa ou Await em operações de execução longa ou de bloqueio para permitir que o tempo de execução continue.Your implementation of RunAsync should return a Task or await on any long-running or blocking operations to allow the runtime to continue. Observação no while(true) loop no exemplo anterior, um retorno await Task.Delay() de tarefa é usado.Note in the while(true) loop in the previous example, a Task-returning await Task.Delay() is used. Se a carga de trabalho precisar ser bloqueada de forma síncrona, você Task.Run() deverá agendar uma nova tarefa com em sua RunAsync implementação.If your workload must block synchronously, you should schedule a new Task with Task.Run() in your RunAsync implementation.

O cancelamento de sua carga de trabalho é um esforço cooperativo orquestrado pelo token de cancelamento fornecido.Cancellation of your workload is a cooperative effort orchestrated by the provided cancellation token. O sistema aguardará que a tarefa seja encerrada (com êxito na conclusão, cancelamento ou falha) antes de se mover.The system will wait for your task to end (by successful completion, cancellation, or fault) before it moves on. É importante honrar o token de cancelamento, concluir qualquer trabalho e sair RunAsync() o mais rápido possível quando o sistema solicita o cancelamento.It is important to honor the cancellation token, finish any work, and exit RunAsync() as quickly as possible when the system requests cancellation.

Neste exemplo de serviço sem estado, a contagem é armazenada em uma variável local.In this stateless service example, the count is stored in a local variable. Mas como esse é um serviço sem estado, o valor armazenado só existe para o ciclo de vida atual de sua instância de serviço.But because this is a stateless service, the value that's stored exists only for the current lifecycle of its service instance. Quando o serviço é movido ou reiniciado, o valor é perdido.When the service moves or restarts, the value is lost.

Criar um serviço com estadoCreate a stateful service

Service Fabric introduz um novo tipo de serviço com estado.Service Fabric introduces a new kind of service that is stateful. Um serviço com estado pode manter o estado de forma confiável no próprio serviço, localizado em conjunto com o código que o está usando.A stateful service can maintain state reliably within the service itself, co-located with the code that's using it. O estado se torna altamente disponível por Service Fabric sem a necessidade de persistir o estado para um repositório externo.State is made highly available by Service Fabric without the need to persist state to an external store.

Para converter um valor de contador de sem estado para altamente disponível e persistente, mesmo quando o serviço é movido ou reiniciado, você precisa de um serviço com estado.To convert a counter value from stateless to highly available and persistent, even when the service moves or restarts, you need a stateful service.

No mesmo aplicativo HelloWorld , você pode adicionar um novo serviço clicando com o botão direito do mouse nas referências de serviços no projeto de aplicativo e selecionando Adicionar > novo serviço de Service Fabric.In the same HelloWorld application, you can add a new service by right-clicking on the Services references in the application project and selecting Add -> New Service Fabric Service.

Adicionar um serviço ao seu aplicativo Service Fabric

Selecione .NET Core 2,0-> serviço com estado e nomeie-o HelloWorldStateful.Select .NET Core 2.0 -> Stateful Service and name it HelloWorldStateful. Clique em OK.Click OK.

Use a caixa de diálogo novo projeto para criar um novo serviço com estado Service Fabric

Seu aplicativo agora deve ter dois serviços: o serviço sem estado HelloWorldStateless e o serviço com estado HelloWorldStateful.Your application should now have two services: the stateless service HelloWorldStateless and the stateful service HelloWorldStateful.

Um serviço com estado tem os mesmos pontos de entrada que um serviço sem estado.A stateful service has the same entry points as a stateless service. A principal diferença é a disponibilidade de um provedor de estado que pode armazenar o estado de forma confiável.The main difference is the availability of a state provider that can store state reliably. Service Fabric vem com uma implementação de provedor de estado chamada coleções confiáveis, que permite criar estruturas de dados replicadas por meio do Gerenciador de estado confiável.Service Fabric comes with a state provider implementation called Reliable Collections, which lets you create replicated data structures through the Reliable State Manager. Um serviço confiável com estado usa esse provedor de estado por padrão.A stateful Reliable Service uses this state provider by default.

Abra HelloWorldStateful.cs no HelloWorldStateful, que contém o seguinte método RunAsync:Open HelloWorldStateful.cs in HelloWorldStateful, which contains the following RunAsync method:

protected override async Task RunAsync(CancellationToken cancellationToken)
{
    // TODO: Replace the following sample code with your own logic
    //       or remove this RunAsync override if it's not needed in your service.

    var myDictionary = await this.StateManager.GetOrAddAsync<IReliableDictionary<string, long>>("myDictionary");

    while (true)
    {
        cancellationToken.ThrowIfCancellationRequested();

        using (var tx = this.StateManager.CreateTransaction())
        {
            var result = await myDictionary.TryGetValueAsync(tx, "Counter");

            ServiceEventSource.Current.ServiceMessage(this.Context, "Current Counter Value: {0}",
                result.HasValue ? result.Value.ToString() : "Value does not exist.");

            await myDictionary.AddOrUpdateAsync(tx, "Counter", 0, (key, value) => ++value);

            // If an exception is thrown before calling CommitAsync, the transaction aborts, all changes are
            // discarded, and nothing is saved to the secondary replicas.
            await tx.CommitAsync();
        }

        await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
    }

RunAsyncRunAsync

RunAsync()funciona da mesma forma em serviços com e sem estado.RunAsync() operates similarly in stateful and stateless services. No entanto, em um serviço com estado, a plataforma executa trabalho adicional em seu nome antes RunAsync()de ser executada.However, in a stateful service, the platform performs additional work on your behalf before it executes RunAsync(). Esse trabalho pode incluir garantir que o Gerenciador de estado confiável e as coleções confiáveis estejam prontos para uso.This work can include ensuring that the Reliable State Manager and Reliable Collections are ready to use.

Coleções confiáveis e o Gerenciador de estado confiávelReliable Collections and the Reliable State Manager

var myDictionary = await this.StateManager.GetOrAddAsync<IReliableDictionary<string, long>>("myDictionary");

IReliableDictionary é uma implementação de dicionário que você pode usar para armazenar o estado de forma confiável no serviço.IReliableDictionary is a dictionary implementation that you can use to reliably store state in the service. Com Service Fabric e coleções confiáveis, você pode armazenar dados diretamente em seu serviço sem a necessidade de um repositório persistente externo.With Service Fabric and Reliable Collections, you can store data directly in your service without the need for an external persistent store. As coleções confiáveis tornam seus dados altamente disponíveis.Reliable Collections make your data highly available. Service Fabric realiza isso criando e gerenciando várias réplicas do seu serviço para você.Service Fabric accomplishes this by creating and managing multiple replicas of your service for you. Ele também fornece uma API que abstrai as complexidades de gerenciar essas réplicas e suas transições de estado.It also provides an API that abstracts away the complexities of managing those replicas and their state transitions.

As coleções confiáveis podem armazenar qualquer tipo .NET, incluindo seus tipos personalizados, com algumas limitações:Reliable Collections can store any .NET type, including your custom types, with a couple of caveats:

  • Service Fabric torna seu estado altamente disponível ao replicar o estado entre os nós e as coleções confiáveis armazenam seus dados no disco local em cada réplica.Service Fabric makes your state highly available by replicating state across nodes, and Reliable Collections store your data to local disk on each replica. Isso significa que tudo que é armazenado em coleções confiáveis deve ser serializável.This means that everything that is stored in Reliable Collections must be serializable. Por padrão, as coleções confiáveis usam DataContract para serialização, portanto, é importante certificar-se de que os tipos têm suporte do serializador de contrato de dados quando você usa o serializador padrão.By default, Reliable Collections use DataContract for serialization, so it's important to make sure that your types are supported by the Data Contract Serializer when you use the default serializer.

  • Os objetos são replicados para alta disponibilidade quando você confirma transações em coleções confiáveis.Objects are replicated for high availability when you commit transactions on Reliable Collections. Os objetos armazenados em coleções confiáveis são mantidos na memória local em seu serviço.Objects stored in Reliable Collections are kept in local memory in your service. Isso significa que você tem uma referência local para o objeto.This means that you have a local reference to the object.

    É importante que você não faça mutação de instâncias locais desses objetos sem executar uma operação de atualização na coleção confiável em uma transação.It is important that you do not mutate local instances of those objects without performing an update operation on the reliable collection in a transaction. Isso ocorre porque as alterações em instâncias locais de objetos não serão replicadas automaticamente.This is because changes to local instances of objects will not be replicated automatically. Você deve inserir novamente o objeto de volta no dicionário ou usar um dos métodos de atualização no dicionário.You must re-insert the object back into the dictionary or use one of the update methods on the dictionary.

O Gerenciador de estado confiável gerencia coleções confiáveis para você.The Reliable State Manager manages Reliable Collections for you. Você pode simplesmente pedir ao Gerenciador de estado confiável uma coleção confiável por nome a qualquer momento e em qualquer lugar em seu serviço.You can simply ask the Reliable State Manager for a reliable collection by name at any time and at any place in your service. O Gerenciador de estado confiável garante que você obtenha uma referência de volta.The Reliable State Manager ensures that you get a reference back. Não recomendamos que você salve referências a instâncias de coleções confiáveis em Propriedades ou variáveis de membro de classe.We don't recommended that you save references to reliable collection instances in class member variables or properties. Deve-se tomar cuidado especial para garantir que a referência seja definida para uma instância em todos os momentos no ciclo de vida do serviço.Special care must be taken to ensure that the reference is set to an instance at all times in the service lifecycle. O Gerenciador de estado confiável manipula esse trabalho para você e é otimizado para visitas repetidas.The Reliable State Manager handles this work for you, and it's optimized for repeat visits.

Operações transacionais e assíncronasTransactional and asynchronous operations

using (ITransaction tx = this.StateManager.CreateTransaction())
{
    var result = await myDictionary.TryGetValueAsync(tx, "Counter-1");

    await myDictionary.AddOrUpdateAsync(tx, "Counter-1", 0, (k, v) => ++v);

    await tx.CommitAsync();
}

As coleções confiáveis têm muitas das mesmas operações que suas System.Collections.Generic e System.Collections.Concurrent contraparte, exceto LINQ.Reliable Collections have many of the same operations that their System.Collections.Generic and System.Collections.Concurrent counterparts do, except LINQ. As operações em coleções confiáveis são assíncronas.Operations on Reliable Collections are asynchronous. Isso ocorre porque as operações de gravação com coleções confiáveis executam operações de e/s para replicar e manter os dados no disco.This is because write operations with Reliable Collections perform I/O operations to replicate and persist data to disk.

As operações de coletaconfiáveis são transacionais, para que você possa manter o estado consistente entre várias coleções confiáveis e operações.Reliable Collection operations are transactional, so that you can keep state consistent across multiple Reliable Collections and operations. Por exemplo, você pode remover uma fila de um item de trabalho de uma fila confiável, executar uma operação nele e salvar o resultado em um dicionário confiável, tudo em uma única transação.For example, you may dequeue a work item from a Reliable Queue, perform an operation on it, and save the result in a Reliable Dictionary, all within a single transaction. Isso é tratado como uma operação atômica e garante que toda a operação seja realizada com sucesso ou que toda a operação seja revertida.This is treated as an atomic operation, and it guarantees that either the entire operation will succeed or the entire operation will roll back. Se ocorrer um erro depois que você remover a fila do item, mas antes de salvar o resultado, toda a transação será revertida e o item permanecerá na fila para processamento.If an error occurs after you dequeue the item but before you save the result, the entire transaction is rolled back and the item remains in the queue for processing.

Executar a aplicaçãoRun the application

Agora retornamos ao aplicativo HelloWorld .We now return to the HelloWorld application. Agora você pode criar e implantar seus serviços.You can now build and deploy your services. Quando você pressionar F5, seu aplicativo será compilado e implantado em seu cluster local.When you press F5, your application will be built and deployed to your local cluster.

Depois que os serviços iniciarem a execução, você poderá exibir os eventos do ETW (rastreamento de eventos gerados para Windows) em uma janela eventos de diagnóstico .After the services start running, you can view the generated Event Tracing for Windows (ETW) events in a Diagnostic Events window. Observe que os eventos exibidos são do serviço sem estado e do serviço com estado no aplicativo.Note that the events displayed are from both the stateless service and the stateful service in the application. Você pode pausar o fluxo clicando no botão Pausar.You can pause the stream by clicking the Pause button. Em seguida, você pode examinar os detalhes de uma mensagem expandindo essa mensagem.You can then examine the details of a message by expanding that message.

Nota

Antes de executar o aplicativo, verifique se você tem um cluster de desenvolvimento local em execução.Before you run the application, make sure that you have a local development cluster running. Confira o Guia de introdução para obter informações sobre como configurar seu ambiente local.Check out the getting started guide for information on setting up your local environment.

Exibir eventos de diagnóstico no Visual Studio

Passos SeguintesNext steps

Depurar seu aplicativo Service Fabric no Visual StudioDebug your Service Fabric application in Visual Studio

Introdução: Service Fabric serviços de API Web com hospedagem interna OWINGet started: Service Fabric Web API services with OWIN self-hosting

Saiba mais sobre as coleções confiáveisLearn more about Reliable Collections

Implementar uma aplicaçãoDeploy an application

Atualização da aplicaçãoApplication upgrade

Referência do desenvolvedor para Reliable ServicesDeveloper reference for Reliable Services