Introduzione a Reliable ServicesGet started with Reliable Services

Un'applicazione di Azure Service Fabric contiene uno o più servizi che consentono l'esecuzione del codice.An Azure Service Fabric application contains one or more services that run your code. Questa guida illustra come creare applicazioni di Service Fabric con e senza stato con i servizi Reliable Services.This guide shows you how to create both stateless and stateful Service Fabric applications with Reliable Services. Questo video di Microsoft Virtual Academy illustra anche come creare un servizio Reliable Services senza stato:

This Microsoft Virtual Academy video also shows you how to create a stateless Reliable service:


Concetti di baseBasic concepts

Per iniziare a usare Reliable Services, è sufficiente comprendere solo alcuni concetti di base:To get started with Reliable Services, you only need to understand a few basic concepts:

  • Tipo di servizio: si tratta dell'implementazione del servizio.Service type: This is your service implementation. Viene definito dalla classe scritta che estende StatelessService e qualsiasi altro codice o dipendenze usate, insieme al nome e al numero della versione.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.
  • Istanza di servizio denominata: per eseguire il servizio, si creano le istanze denominate del tipo di servizio, analogamente al modo in cui si creano le istanze di un oggetto di un tipo di 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. Il formato del nome di un'istanza del servizio è un URI che usa lo schema "fabric:/", ad esempio "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 del servizio: le istanze del servizio denominate che si creano devono essere eseguite in un processo host.Service host: The named service instances you create need to run inside a host process. L'host del servizio è semplicemente un processo in cui eseguire le istanze del servizio.The service host is just a process where instances of your service can run.
  • Registrazione del servizio: la registrazione raccoglie tutti gli elementi.Service registration: Registration brings everything together. Il tipo di servizio deve essere registrato con il runtime di Service Fabric in un host del servizio per consentire a Service Fabric di creare istanze per l'esecuzione.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.

Creare un servizio senza statoCreate a stateless service

Il servizio senza stato è il tipo di servizio di norma presente nelle applicazioni cloud.A stateless service is a type of service that is currently the norm in cloud applications. Viene considerato senza stato perché il servizio stesso non contiene dati che devono essere archiviati in modo affidabile o resi a disponibilità elevata.It is considered stateless because the service itself does not contain data that needs to be stored reliably or made highly available. Se un'istanza di un servizio senza stato si arresta, il relativo stato interno viene perso.If an instance of a stateless service shuts down, all of its internal state is lost. In questi tipi di servizio lo stato deve essere reso persistente mediante un archivio esterno, ad esempio tabelle di Azure o un database SQL, in modo da assicurare elevata disponibilità e affidabilità.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.

Avviare Visual Studio 2015 o Visual Studio 2017 come amministratore e creare un nuovo progetto di applicazione di Service Fabric denominato HelloWorld:Launch Visual Studio 2015 or Visual Studio 2017 as an administrator, and create a new Service Fabric application project named HelloWorld:

Uso della finestra di dialogo New Project per creare una nuova applicazione di Service Fabric

Creare quindi un progetto di servizio senza stato denominato HelloWorldStateless:Then create a stateless service project named HelloWorldStateless:

Nella seconda finestra di dialogo creare un progetto di servizio senza stato

La soluzione ora contiene due progetti:Your solution now contains two projects:

  • HelloWorld.HelloWorld. Si tratta del progetto applicazione contenente i servizi.This is the application project that contains your services. Il progetto contiene anche il manifesto dell'applicazione che descrive l'applicazione stessa, oltre ad alcuni script di PowerShell che consentono di distribuirla.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. Si tratta del progetto di servizio.This is the service project. Il progetto contiene l'implementazione del servizio senza stato.It contains the stateless service implementation.

Implementare il servizioImplement the service

Aprire il file HelloWorldStateless.cs nel progetto del servizio.Open the HelloWorldStateless.cs file in the service project. In Service Fabric un servizio può eseguire qualsiasi tipo di logica di business.In Service Fabric, a service can run any business logic. L'API del servizio fornisce due punti di ingresso per il codice:The service API provides two entry points for your code:

  • Un metodo del punto di ingresso aperto denominato RunAsync, che consente di iniziare a eseguire qualsiasi carico di lavoro, inclusi carichi di lavoro di calcolo con esecuzione prolungata.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)
{
    ...
}
  • Un punto di ingresso di comunicazione a cui è possibile collegare lo stack di comunicazione desiderato, come ASP.NET Core.A communication entry point where you can plug in your communication stack of choice, such as ASP.NET Core. In questo punto è possibile iniziare a ricevere richieste da utenti e da altri servizi.This is where you can start receiving requests from users and other services.
protected override IEnumerable<ServiceInstanceListener> CreateServiceInstanceListeners()
{
    ...
}

Questa esercitazione si concentra sul metodo del punto di ingresso RunAsync() .In this tutorial, we will focus on the RunAsync() entry point method. In questo punto è possibile iniziare immediatamente a eseguire il codice.This is where you can immediately start running your code. Il modello di progetto include un esempio di implementazione di RunAsync() che gestisce un conteggio incrementale.The project template includes a sample implementation of RunAsync() that increments a rolling count.

Nota

Per informazioni dettagliate sull'uso di uno stack di comunicazione, vedere Introduzione ai servizi API Web di Microsoft Azure Service Fabric con self-hosting 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, "Working-{0}", ++iterations);

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

La piattaforma chiama questo metodo quando si inserisce un'istanza di un servizio pronta per l'esecuzione.The platform calls this method when an instance of a service is placed and ready to execute. Per un servizio senza stato, la piattaforma chiama il metodo quando l'istanza del servizio viene aperta.For a stateless service, that simply means when the service instance is opened. Viene fornito un token di annullamento che determina quando è necessario chiudere l'istanza del servizio.A cancellation token is provided to coordinate when your service instance needs to be closed. In Service Fabric questo ciclo di apertura e chiusura di un'istanza del servizio può verificarsi più volte per tutta la durata del servizio nel suo complesso.In Service Fabric, this open/close cycle of a service instance can occur many times over the lifetime of the service as a whole. Questa situazione può verificarsi per vari motivi, tra cui:This can happen for various reasons, including:

  • Il sistema sposta le istanze del servizio per il bilanciamento delle risorse.The system moves your service instances for resource balancing.
  • Si verificano errori nel codice.Faults occur in your code.
  • Viene aggiornato il sistema o l'applicazione.The application or system is upgraded.
  • Si verifica un'interruzione nell'hardware sottostante.The underlying hardware experiences an outage.

Questa orchestrazione viene gestita dal sistema per assicurare l'elevata disponibilità e il corretto bilanciamento del servizio.This orchestration is managed by the system to keep your service highly available and properly balanced.

RunAsync() non deve bloccarsi in modo sincrono.RunAsync() should not block synchronously. L'implementazione di RunAsync deve restituire un'attività o restare in attesa in caso di operazioni a esecuzione prolungata oppure bloccate, per consentire al runtime di continuare.Your implementation of RunAsync should return a Task or await on any long-running or blocking operations to allow the runtime to continue. Si noti che nel ciclo while(true) dell'esempio precedente viene usato await Task.Delay() per la restituzione di un'attività.Note in the while(true) loop in the previous example, a Task-returning await Task.Delay() is used. Se il carico di lavoro si deve bloccare in modo sincrono, è opportuno pianificare una nuova Task con Task.Run() nell'implementazione RunAsync.If your workload must block synchronously, you should schedule a new Task with Task.Run() in your RunAsync implementation.

L'annullamento del carico di lavoro è un'operazione cooperativa coordinata dal token di annullamento fornito.Cancellation of your workload is a cooperative effort orchestrated by the provided cancellation token. Il sistema attende la fine dell'attività (per esito positivo, annullamento o errore) prima di continuare.The system will wait for your task to end (by successful completion, cancellation, or fault) before it moves on. È importante rispettare il token di annullamento, completare le operazioni e chiudere RunAsync() il più rapidamente possibile quando viene richiesto l'annullamento dal sistema.It is important to honor the cancellation token, finish any work, and exit RunAsync() as quickly as possible when the system requests cancellation.

In questo esempio di servizio senza stato il conteggio è archiviato in una variabile locale.In this stateless service example, the count is stored in a local variable. Tuttavia, poiché si tratta di un servizio senza stato, il valore archiviato esiste soltanto per il ciclo di vita corrente dell'istanza del servizio.But because this is a stateless service, the value that's stored exists only for the current lifecycle of its service instance. Quando si posta o si riavvia il servizio, il valore viene perso.When the service moves or restarts, the value is lost.

Creare un servizio con statoCreate a stateful service

Service Fabric introduce un nuovo tipo di servizio con stato.Service Fabric introduces a new kind of service that is stateful. Un servizio con stato può mantenere lo stato affidabile all'interno del servizio stesso, con percorso condiviso con il codice che lo usa.A stateful service can maintain state reliably within the service itself, co-located with the code that's using it. L'elevata disponibilità dello stato è assicurata da Service Fabric, senza dover rendere persistente lo stato mediante un archivio esterno.State is made highly available by Service Fabric without the need to persist state to an external store.

Per convertire un valore del contatore da senza stato a elevata disponibilità e persistenza anche quando il servizio viene spostato o riavviato, è necessario un servizio con stato.To convert a counter value from stateless to highly available and persistent, even when the service moves or restarts, you need a stateful service.

Nella stessa applicazione HelloWorld aggiungere un nuovo servizio facendo clic con il pulsante destro del mouse sui riferimenti ai servizi nel progetto applicazione e selezionare Aggiungi -> Nuovo servizio 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.

Aggiungere un servizio all'applicazione di Service Fabric

Selezionare Stateful Service e assegnare il nome HelloWorldStateful.Select Stateful Service and name it HelloWorldStateful. Fare clic su OK.Click OK.

Uso della finestra di dialogo New Project per creare un nuovo servizio di Service Fabric con stato

A questo punto l'applicazione ha due servizi: il servizio senza stato HelloWorldStateless e il servizio con stato HelloWorldStateful.Your application should now have two services: the stateless service HelloWorldStateless and the stateful service HelloWorldStateful.

Un servizio con stato ha gli stessi punti di ingresso di un servizio senza stato.A stateful service has the same entry points as a stateless service. La differenza principale è data dalla disponibilità di un provider di stato che può archiviare lo stato in modo affidabile.The main difference is the availability of a state provider that can store state reliably. Service Fabric include un'implementazione del provider di stato denominata Reliable Collections, che permette di creare strutture di dati replicate tramite Reliable State Manager.Service Fabric comes with a state provider implementation called Reliable Collections, which lets you create replicated data structures through the Reliable State Manager. Un servizio Reliable Services con stato usa questo provider di stato per impostazione predefinita.A stateful Reliable Service uses this state provider by default.

Aprire HelloWorldStateful.cs in HelloWorldStatefulche contiene il metodo RunAsync seguente: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, "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() funziona in modo simile sia nei servizi con stato che nei servizi senza stato.RunAsync() operates similarly in stateful and stateless services. In un servizio con stato la piattaforma esegue tuttavia operazioni aggiuntive per conto dell'utente prima di eseguire RunAsync().However, in a stateful service, the platform performs additional work on your behalf before it executes RunAsync(). Tali operazioni possono includere la verifica che Reliable State Manager e Reliable Collections siano pronti per l'uso.This work can include ensuring that the Reliable State Manager and Reliable Collections are ready to use.

Reliable Collections e Reliable State ManagerReliable Collections and the Reliable State Manager

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

IReliableDictionary è un'implementazione di dizionario che permette di archiviare in modo affidabile lo stato nel servizio.IReliableDictionary is a dictionary implementation that you can use to reliably store state in the service. Grazie a Service Fabric e alle raccolte Reliable Collections è possibile archiviare i dati direttamente nel servizio, senza la necessità di un archivio esterno persistente.With Service Fabric and Reliable Collections, you can store data directly in your service without the need for an external persistent store. Le raccolte Reliable Collections garantiscono la disponibilità elevata dei dati.Reliable Collections make your data highly available. A tale scopo, Service Fabric crea e gestisce automaticamente più repliche del servizio.Service Fabric accomplishes this by creating and managing multiple replicas of your service for you. Offre anche un'API che consente di evitare le complessità di gestione di tali repliche e delle relative transizioni di stato.It also provides an API that abstracts away the complexities of managing those replicas and their state transitions.

Le raccolte Reliable Collections possono archiviare qualsiasi tipo .NET, inclusi quelli personalizzati, con alcuni avvertimenti:Reliable Collections can store any .NET type, including your custom types, with a couple of caveats:

  • Service Fabric garantisce la disponibilità elevata dello stato replicando lo stato nei nodi, mentre Reliable Collections archivia i dati nel disco locale a ogni replica.Service Fabric makes your state highly available by replicating state across nodes, and Reliable Collections store your data to local disk on each replica. Questo significa che tutti gli elementi archiviati in Reliable Collections devono essere serializzabili.This means that everything that is stored in Reliable Collections must be serializable. Per impostazione predefinita, le raccolte Reliable Collections usano DataContract per la serializzazione. Quando si usa il serializzatore predefinito, è quindi importante assicurarsi che i tipi siano supportati dal serializzatore dei contratti dati.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.
  • Quando si esegue il commit di transazioni nelle raccolte Reliable Collections, gli oggetti vengono replicati per assicurare disponibilità elevata.Objects are replicated for high availability when you commit transactions on Reliable Collections. Gli oggetti archiviati nelle raccolte Reliable Collections vengono conservati nella memoria locale del servizio.Objects stored in Reliable Collections are kept in local memory in your service. Ciò significa che è presente un riferimento locale all'oggetto.This means that you have a local reference to the object.

    È importante non apportare modifiche alle istanze locali degli oggetti senza prima eseguire un'operazione di aggiornamento sulla raccolta Reliable Collections in una transazione.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. Le modifiche apportate alle istanze locali di oggetti, infatti, non vengono replicate automaticamente.This is because changes to local instances of objects will not be replicated automatically. È necessario inserire nuovamente l'oggetto nel dizionario oppure usare uno dei metodi di aggiornamento nel dizionario.You must re-insert the object back into the dictionary or use one of the update methods on the dictionary.

Reliable State Manager gestisce automaticamente le raccolte Reliable Collections.The Reliable State Manager manages Reliable Collections for you. In qualunque momento e in qualsiasi posizione del servizio è possibile chiedere a Reliable State Manager una raccolta Reliable Collections indicandone il nome.You can simply ask the Reliable State Manager for a reliable collection by name at any time and at any place in your service. Reliable State Manager restituirà un riferimento.The Reliable State Manager ensures that you get a reference back. Non si consiglia di salvare riferimenti alle istanze di raccolte Reliable Collections in proprietà o variabili membri di classe.We don't recommended that you save references to reliable collection instances in class member variables or properties. Prestare particolare attenzione per assicurarsi che il riferimento sia sempre impostato su un'istanza durante il ciclo di vita del servizio.Special care must be taken to ensure that the reference is set to an instance at all times in the service lifecycle. Reliable State Manager gestisce queste operazioni automaticamente ed è ottimizzato per le visite ripetute.The Reliable State Manager handles this work for you, and it's optimized for repeat visits.

Operazioni transazionali e asincroneTransactional 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();
}

Le raccolte Reliable Collections includono molte delle operazioni corrispondenti di System.Collections.Generic e System.Collections.Concurrent, tranne LINQ.Reliable Collections have many of the same operations that their System.Collections.Generic and System.Collections.Concurrent counterparts do, except LINQ. Le operazioni sulle raccolte Reliable Collections sono asincrone.Operations on Reliable Collections are asynchronous. Questo avviene perché le operazioni di scrittura sulle raccolte Reliable Collections eseguono operazioni di I/O per replicare e rendere persistenti i dati su disco.This is because write operations with Reliable Collections perform I/O operations to replicate and persist data to disk.

Le operazioni sulle raccolte Reliable Collections sono transazionalie consentono di mantenere lo stato coerente tra più raccolte Reliable Collections e operazioni.Reliable Collection operations are transactional, so that you can keep state consistent across multiple Reliable Collections and operations. Ad esempio, è possibile rimuovere un elemento di lavoro da un oggetto ReliableQueue, eseguire un'operazione su tale elemento e salvare il risultato in un oggetto ReliableDictionary, il tutto all'interno di una singola transazione.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. Questa viene considerata come un'operazione atomica e garantisce la riuscita o il rollback dell'intera operazione.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 si verifica un errore dopo aver rimosso l'elemento dalla coda ma prima di aver salvato il risultato, viene eseguito il rollback dell'intera transazione e l'elemento rimane nella coda per l'elaborazione.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.

Eseguire l'applicazioneRun the application

Tornare all'applicazione HelloWorld .We now return to the HelloWorld application. È ora possibile compilare e distribuire i servizi.You can now build and deploy your services. Quando si preme F5, l'applicazione viene compilata e distribuita nel cluster locale.When you press F5, your application will be built and deployed to your local cluster.

Dopo l'avvio dell'esecuzione dei servizi, è possibile visualizzare gli eventi generati di Event Tracing for Windows (ETW) in una finestra Eventi di diagnostica .After the services start running, you can view the generated Event Tracing for Windows (ETW) events in a Diagnostic Events window. Si noti che gli eventi visualizzati nell'applicazione provengono sia dal servizio senza stato sia dal servizio con stato.Note that the events displayed are from both the stateless service and the stateful service in the application. È possibile sospendere il flusso facendo clic sul pulsante Pausa .You can pause the stream by clicking the Pause button. Espandendo un messaggio è possibile esaminarne i dettagli.You can then examine the details of a message by expanding that message.

Nota

Prima di eseguire l'applicazione, assicurarsi di avere un cluster di sviluppo locale in esecuzione.Before you run the application, make sure that you have a local development cluster running. Per informazioni sulla configurazione dell'ambiente locale, vedere la guida introduttiva .Check out the getting started guide for information on setting up your local environment.

Visualizzare gli eventi di diagnostica in Visual Studio

Passaggi successiviNext steps

Debug dell'applicazione di Service Fabric in Visual StudioDebug your Service Fabric application in Visual Studio

Introduzione ai servizi API Web di Service Fabric con self-hosting OWINGet started: Service Fabric Web API services with OWIN self-hosting

Reliable CollectionsLearn more about Reliable Collections

Distribuire un'applicazioneDeploy an application

Aggiornamento dell'applicazioneApplication upgrade

Guida di riferimento per gli sviluppatori per Reliable ServicesDeveloper reference for Reliable Services