Condividi tramite

Usare Orleans con .NET Aspire

  • Articolo

Orleans ha il supporto predefinito per .NET Aspire. Il modello applicativo di .NET.NET Aspireconsente di descrivere i servizi, i database e altre risorse/infrastruttura nella tua app e come si relazionano. Orleans offre un modo semplice per creare applicazioni distribuite che sono scalabili in modo elastico e a tolleranza di errore. .NET Aspire viene utilizzato per configurare e orchestrare Orleans e le relative dipendenze, ad esempio fornendo a Orleans l'appartenenza al cluster di database e lo spazio di archiviazione.

Orleans è rappresentato come risorsa in .NET Aspire. La risorsa Orleans include la configurazione necessaria per il tuo servizio, ad esempio provider di appartenenza al cluster e provider di archiviazione.

Prerequisiti

Per usare .NET.NET Aspire, è necessario che il codice seguente sia installato in locale:

Per altre informazioni, vedere .NET.NET Aspire configurazione e strumentie .NET.NET Aspire SDK.

Oltre ai prerequisiti per .NET.NET Aspire, è necessario:

  • Orleans versione 8.1.0 o versioni successive

Per altre informazioni, vedere .NET.NET Aspire configurazione e strumenti.

Inizia

Per iniziare, è necessario aggiungere il pacchetto di hosting Orleans al progetto host dell'app installando il pacchetto NuGet 📦Aspire.Hosting.Orleans.

dotnet add package Aspire.Hosting.Orleans

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle .NET applicazioni.

La risorsa Orleans viene aggiunta al generatore di applicazioni distribuite .NET Aspire usando il metodo AddOrleans(string name), che restituisce un generatore di risorse Orleans. Il nome fornito alla risorsa Orleans è a scopo diagnostico. Per la maggior parte delle applicazioni, è sufficiente un valore di "default".

var orleans = builder.AddOrleans("default")

Il generatore di risorse Orleans offre metodi per configurare la risorsa Orleans.

Per configurare Orleans con clustering e storage a grana, installare il pacchetto NuGet 📦Aspire.hosting.Azure.storage nel progetto host dell'applicazione:

dotnet add package Aspire.Hosting.Azure.Storage

Nell'esempio seguente la risorsa Orleans viene configurata con il clustering e l'archiviazione granulare usando rispettivamente i metodi WithClustering e WithGrainStorage:

// Add the resources which you will use for Orleans clustering and
// grain state storage.
var storage = builder.AddAzureStorage("storage").RunAsEmulator();
var clusteringTable = storage.AddTables("clustering");
var grainStorage = storage.AddBlobs("grain-state");

// Add the Orleans resource to the Aspire DistributedApplication
// builder, then configure it with Azure Table Storage for clustering
// and Azure Blob Storage for grain storage.
var orleans = builder.AddOrleans("default")
                     .WithClustering(clusteringTable)
                     .WithGrainStorage("Default", grainStorage);

Il codice precedente indica a Orleans che qualsiasi servizio che fa riferimento ad esso deve fare riferimento anche alla risorsa clusteringTable.

Per partecipare a un cluster di Orleans, fare riferimento alla risorsa Orleans del progetto di servizio, usando WithReference(orleans) per partecipare come Orleansserver, o WithReference(orleans.AsClient()) per partecipare come client. Quando si fa riferimento alla risorsa Orleans dal servizio, viene fatto riferimento anche alle risorse seguenti:

// Add our server project and reference your 'orleans' resource from it.
// it can join the Orleans cluster as a service.
// This implicitly add references to the required resources.
// In this case, that is the 'clusteringTable' resource declared earlier.
builder.AddProject<Projects.OrleansServer>("silo")
       .WithReference(orleans)
       .WithReplicas(3);

Unendo tutto, ecco un esempio di un progetto di hosting dell'app .NET.NET Aspire che include:

  • Risorsa Orleans con clustering e archiviazione.
  • Un progetto di Orleansserver, OrleansServer.
  • Il progetto Orleansclient, OrleansClient.
var builder = DistributedApplication.CreateBuilder(args);

// Add the resources which you will use for Orleans clustering and
// grain state storage.
var storage = builder.AddAzureStorage("storage").RunAsEmulator();
var clusteringTable = storage.AddTables("clustering");
var grainStorage = storage.AddBlobs("grain-state");

// Add the Orleans resource to the Aspire DistributedApplication
// builder, then configure it with Azure Table Storage for clustering
// and Azure Blob Storage for grain storage.
var orleans = builder.AddOrleans("default")
                     .WithClustering(clusteringTable)
                     .WithGrainStorage("Default", grainStorage);

// Add our server project and reference your 'orleans' resource from it.
// it can join the Orleans cluster as a service.
// This implicitly add references to the required resources.
// In this case, that is the 'clusteringTable' resource declared earlier.
builder.AddProject<Projects.OrleansServer>("silo")
       .WithReference(orleans)
       .WithReplicas(3);

// Reference the Orleans resource as a client from the 'frontend'
// project so that it can connect to the Orleans cluster.
builder.AddProject<Projects.OrleansClient>("frontend")
       .WithReference(orleans.AsClient())
       .WithExternalHttpEndpoints()
       .WithReplicas(3);

// Build and run the application.
using var app = builder.Build();
await app.RunAsync();

Per utilizzare la risorsa .NET AspireOrleans da un progetto di Orleansserver, è necessario eseguire alcuni passaggi:

  1. Aggiungere le integrazioni .NET.NET Aspire pertinenti. In questo esempio si usano Aspire.Azure.Data.Tables e Aspire.Azure.Storage.Blobs.
  2. Aggiungi i pacchetti del provider Orleans per quelle integrazioni .NET Aspire. In questo esempio si usano Microsoft.Orleans.Persistence.AzureStorage e Microsoft.Orleans.Clustering.AzureStorage.
  3. Aggiungere Orleans al generatore di applicazioni host.

Nel file Program.cs del progetto Orleansserver è necessario configurare le integrazioni .NET Aspire in uso e aggiungere Orleans al generatore host. I nomi specificati devono corrispondere ai nomi usati nel progetto host dell'app .NET.NET Aspire: "clustering" per il provider di clustering e "grain-state" per il provider di archiviazione dello stato del grano.

using Orleans.Runtime;
using OrleansContracts;

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.AddKeyedAzureTableClient("clustering");
builder.AddKeyedAzureBlobClient("grain-state");
builder.UseOrleans();

var app = builder.Build();

app.MapGet("/", () => "OK");

await app.RunAsync();

public sealed class CounterGrain(
    [PersistentState("count")] IPersistentState<int> count) : ICounterGrain
{
    public ValueTask<int> Get()
    {
        return ValueTask.FromResult(count.State);
    }

    public async ValueTask<int> Increment()
    {
        var result = ++count.State;
        await count.WriteStateAsync();
        return result;
    }
}

Analogamente, nel progetto OrleansClient, aggiungendo le risorse .NET Aspire necessarie affinché il tuo progetto si unisca al cluster Orleans come client, e configurando il generatore host per aggiungere un Orleansclient:

using OrleansContracts;

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.AddKeyedAzureTableClient("clustering");
builder.UseOrleansClient();

var app = builder.Build();

app.MapGet("/counter/{grainId}", async (IClusterClient client, string grainId) =>
{
    var grain = client.GetGrain<ICounterGrain>(grainId);
    return await grain.Get();
});

app.MapPost("/counter/{grainId}", async (IClusterClient client, string grainId) =>
{
    var grain = client.GetGrain<ICounterGrain>(grainId);
    return await grain.Increment();
});

app.UseFileServer();

await app.RunAsync();

Abilitazione di OpenTelemetry

Per convenzione, .NET.NET Aspire soluzioni includono un progetto per definire la configurazione e il comportamento predefiniti per il servizio. Questo progetto viene chiamato progetto predefinito del servizio e i modelli lo creano con un nome che termina con ServiceDefaults. Per configurare per in , è necessario applicare la configurazione al progetto di impostazioni predefinite del servizio seguendo la guida osservabilità . In breve, è necessario modificare il metodo ConfigureOpenTelemetry per aggiungere i contatori Orleans e gli strumenti di tracciatura . Il frammento di codice seguente mostra il file di Extensions.cs modificato da un progetto predefinito del servizio che include metriche e tracce da Orleans.

public static IHostApplicationBuilder ConfigureOpenTelemetry(this IHostApplicationBuilder builder)
{
    builder.Logging.AddOpenTelemetry(logging =>
    {
        logging.IncludeFormattedMessage = true;
        logging.IncludeScopes = true;
    });

    builder.Services.AddOpenTelemetry()
        .WithMetrics(metrics =>
        {
            metrics.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddRuntimeInstrumentation()
                .AddMeter("Microsoft.Orleans");
        })
        .WithTracing(tracing =>
        {
            tracing.AddSource("Microsoft.Orleans.Runtime");
            tracing.AddSource("Microsoft.Orleans.Application");

            tracing.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation();
        });

    builder.AddOpenTelemetryExporters();

    return builder;
}

Fornitori supportati

L'integrazione OrleansAspire supporta attualmente un subset limitato di provider di Orleans:

  • Raggruppamento:
    • Redis
    • tabelle di archiviazione Azure
  • Persistenza:
    • Redis
    • tabelle di archiviazione Azure
    • BLOB di archiviazione Azure
  • Promemoria:
    • Redis
    • tabelle di archiviazione Azure
  • Directory delle Granaglie
    • Redis
    • tabelle di archiviazione Azure

I provider di streaming non sono supportati a partire da Orleans versione 8.1.0.

Passaggi successivi

Esplora l'app per il voto di esempio Orleans