Esercitazione: Hello World

Questa panoramica fa riferimento all'applicazione di esempio Hello World.

I concetti principali di Orleans coinvolgono un silo, un client e uno o più grani. La creazione di un'app Orleans comporta la configurazione del silo, la configurazione del client e la scrittura dei grani.

Configurare il silo

I silos vengono configurati a livello di codice tramite SiloHostBuilder e diverse classi di opzioni supplementari. Un elenco di tutte le opzioni è disponibile qui.

static async Task<ISiloHost> StartSilo()
{
    var builder = new HostBuilder()
        UseOrleans(c =>
        {
            c.UseLocalhostClustering()
                .Configure<ClusterOptions>(options =>
                {
                    options.ClusterId = "dev";
                    options.ServiceId = "HelloWorldApp";
                })
                .Configure<EndpointOptions>(
                    options => options.AdvertisedIPAddress = IPAddress.Loopback)
                .ConfigureApplicationParts(
                    parts => parts.AddApplicationPart(typeof(HelloGrain).Assembly).WithReferences())
                .ConfigureLogging(logging => logging.AddConsole());
        });

    var host = builder.Build();
    await host.StartAsync();

    return host;
}

Opzione	Utilizzo
.UseLocalhostClustering()	Configura il client per la connessione a un silo in localhost.
ClusterOptions	ClusterId è il nome del cluster Orleans e deve essere lo stesso per silo e client in modo che possano comunicare tra loro. ServiceId è l'ID usato per l'applicazione e non deve cambiare tra le distribuzioni.
EndpointOptions	Indica al silo dove essere in ascolto. Per questo esempio, si userà un loopback.
ConfigureApplicationParts	Aggiunge la classe dei grani e l'assembly di interfaccia come parti dell'applicazione all'applicazione Orleans.

Dopo aver caricato le configurazioni, SiloHost viene compilato e quindi avviato in modo asincrono.

Configurazione del client

Analogamente al silo, il client viene configurato tramite ClientBuilder e una raccolta simile di classi di opzioni.

static async Task<IClusterClient> StartClientWithRetries()
{
    attempt = 0;
    var client = new ClientBuilder()
        .UseLocalhostClustering()
        .Configure<ClusterOptions>(options =>
        {
            options.ClusterId = "dev";
            options.ServiceId = "HelloWorldApp";
        })
        .ConfigureLogging(logging => logging.AddConsole())
        .Build();

    await client.Connect(RetryFilter);
    Console.WriteLine("Client successfully connect to silo host");
    return client;
}

Opzione	Utilizzo
.UseLocalhostClustering()	Come per SiloHost
ClusterOptions	Come per SiloHost

È possibile trovare una guida più approfondita alla configurazione del client nella sezione Configurazione client della Guida alla configurazione.

Scrittura di un grano

I grani sono le primitive chiave del modello di programmazione di Orleans. I grani sono i blocchi predefiniti di un'applicazione Orleans e sono unità atomiche di isolamento, distribuzione e persistenza. I grani sono oggetti che rappresentano le entità dell'applicazione. Proprio come nella programmazione orientata agli oggetti classica, un grano incapsula lo stato di un'entità e ne codifica il comportamento nella logica del codice. I grani possono contenere riferimenti reciproci e interagire richiamando i metodi degli altri esposti tramite interfacce.

Per ulteriori informazioni, consultare la sezione Concetti di base della documentazione Orleans.

Questo è il corpo principale del codice per il grano Hello World:

namespace HelloWorld.Grains;

public class HelloGrain : Orleans.Grain, IHello
{
    Task<string> IHello.SayHello(string greeting)
    {
        logger.LogInformation($"SayHello message received: greeting = '{greeting}'");
        return Task.FromResult($"You said: '{greeting}', I say: Hello!");
    }
}

Una classe grain implementa una o più interfacce grain. Per ulteriori informazioni, consultare la sezione Grani.

namespace HelloWorld.Interfaces;

public interface IHello : Orleans.IGrainWithIntegerKey
{
    Task<string> SayHello(string greeting);
}

Come interagiscono le parti

Questo modello di programmazione viene compilato come parte del concetto di base della programmazione orientata agli oggetti distribuita. SiloHost viene avviato per primo. Quindi, viene avviato il programma OrleansClient. Il metodo Main di OrleansClient chiama il metodo che avvia il client, StartClientWithRetries(). Il client viene passato al metodo DoClientWork().

static async Task DoClientWork(IClusterClient client)
{
    var friend = client.GetGrain<IHello>(0);
    var response = await friend.SayHello("Good morning, my friend!");
    Console.WriteLine($"\n\n{response}\n\n");
}

A questo punto, OrleansClient crea un riferimento al grano IHello e chiama il relativo metodo SayHello() tramite l'interfaccia IHello. Questa chiamata attiva il grano nel silo. OrleansClient invia un messaggio di saluto al grano attivato. Il grano restituisce il messaggio di saluto come risposta a OrleansClient, che OrleansClient visualizza nella console.

Esecuzione dell'app di esempio

Per eseguire l'app di esempio, fare riferimento al file Leggimi.