integrazione di .NET AspireOrleans
Orleans include un supporto predefinito per .NET.NET Aspire. Il modello applicativo di .NET.NET Aspireconsente di descrivere i servizi, i database, le altre risorse e l'infrastruttura nell'app, e il modo in cui sono correlati tra loro. Orleans offre un modo semplice per creare applicazioni distribuite scalabili in modo elastico e a tolleranza di errore. È possibile usare .NET Aspire per configurare e orchestrare Orleans e le relative dipendenze, ad esempio fornendo Orleans con l'appartenenza al cluster e l'archiviazione.
Orleans è rappresentato come risorsa in .NET Aspire. A differenza di altre integrazioni, l'integrazione Orleans non crea un contenitore e non richiede un pacchetto di integrazione client separato. Completa invece la configurazione Orleans nel progetto host dell'app .NET Aspire.
Nota
Questa integrazione richiede Orleans versione 8.1.0 o successiva.
Integrazione dell'hosting
L'integrazione di hosting Orleans modella un servizio Orleans come tipo OrleansService. Per accedere a questo tipo e API, aggiungere il pacchetto NuGet 📦Aspire.Hosting.Orleans nel progetto host dell'app .
dotnet add package Aspire.Hosting.Orleans
Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle .NET applicazioni.
Aggiungere una risorsa Orleans
Nel progetto host dell'app, invocare AddOrleans per aggiungere e restituire un generatore di risorse del servizio 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")
Usare lo storage Azure per il clustering delle tabelle e l'archiviazione granularizzata.
In un'app Orleans, l'elemento costruttivo fondamentale è un grano. I grani possono avere stati durevoli. È necessario archiviare lo stato durevole per un grano da qualche parte. In un'applicazione .NET.NET Aspire, Azure Blob Storage è una possibile posizione.
Orleans gli host si registrano in un database e usano tale database per individuarsi e formare un cluster. Archiviano quali server sono membri dei quali silo in una tabella di database. È possibile usare database relazionali o NoSQL per archiviare queste informazioni. In un'applicazione .NET.NET Aspire, una scelta comune per archiviare questa tabella è Azure Table Storage.
Per configurare Orleans con clustering e stoccaggio di cereali in Azure, installare il pacchetto NuGet 📦Aspire.Hosting.Azure.Storage nel progetto host dell'app:
dotnet add package Aspire.Hosting.Azure.Storage
Nel progetto host dell'app, dopo aver chiamato AddOrleans, configurare la risorsa Orleans con clustering e 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 vi fa riferimento deve fare riferimento anche alla risorsa clusteringTable.
Aggiungere un progetto server Orleans nell'host dell'app
È ora possibile aggiungere un nuovo progetto, registrato nell'orchestrazione .NET Aspire, alla tua soluzione come server Orleans. Parteciperà al cluster Orleans come silo con grani costitutivi. Fare riferimento alla risorsa Orleans dal progetto server usando WithReference(orleans). Quando si fa riferimento alla risorsa Orleans dal servizio, viene fatto riferimento anche alle risorse seguenti:
// Add your server project and reference your 'orleans' resource from it.
// It can join the Orleans cluster as a silo.
// This implicitly adds references to the required resources.
// In this case, that is the 'clusteringTable' resource declared earlier.
builder.AddProject<Projects.OrleansServer>("silo")
.WithReference(orleans)
.WithReplicas(3);
Aggiungere un progetto client Orleans nell'host dell'app
I client Orleans comunicano con i grain ospitati su server Orleans. In un'app .NET Aspire, ad esempio, potrebbe essere presente un sito Web front-end che chiama grani in un cluster Orleans. Fare riferimento alla risorsa Orleans dal tuo client Orleans usando WithReference(orleans.AsClient()).
// 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);
Creare il progetto server Orleans
Dopo aver completato il progetto host dell'app, è possibile implementare il progetto server Orleans. Per iniziare, aggiungere i pacchetti NuGet necessari:
Nella cartella per il progetto server Orleans eseguire questi comandi:
dotnet add package Aspire.Azure.Data.Tables
dotnet add package Aspire.Azure.Storage.Blobs
dotnet add package Microsoft.Orleans.Server
dotnet add package Microsoft.Orleans.Persistence.AzureStorage
dotnet add package Microsoft.Orleans.Clustering.AzureStorage
Quindi, nel file Program.cs del progetto server Orleans, aggiungete i client BLOB di archiviazione e le tabelle Azure e quindi chiamate UseOrleans.
var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
builder.AddKeyedAzureTableClient("clustering");
builder.AddKeyedAzureBlobClient("grain-state");
builder.UseOrleans();
Il codice seguente è un esempio completo di un progetto server Orleans, incluso un granulare denominato CounterGrain:
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;
}
}
Creare un progetto cliente Orleans
Nel progetto client Orleans aggiungere gli stessi pacchetti NuGet:
dotnet add package Aspire.Azure.Data.Tables
dotnet add package Aspire.Azure.Storage.Blobs
dotnet add package Microsoft.Orleans.Client
dotnet add package Microsoft.Orleans.Persistence.AzureStorage
dotnet add package Microsoft.Orleans.Clustering.AzureStorage
Quindi, nel file Program.cs del progetto client Orleans, aggiungere il client Azure per l'archiviazione delle tabelle e quindi chiamare UseOrleansClient.
builder.AddKeyedAzureTableClient("clustering");
builder.UseOrleansClient();
Il codice seguente è un esempio completo di un progetto client Orleans. Chiama il granello CounterGrain nella definizione dell'esempio del server Orleans precedentemente citato.
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. Il progetto si chiama progetto dei predefiniti di servizio e i modelli lo creano con un nome che termina con ServiceDefaults. Per configurare Orleans per OpenTelemetry in .NET Aspire, applicare la configurazione al progetto delle impostazioni predefinite del servizio seguendo la guida di osservabilità Orleans.
Modificare il metodo di ConfigureOpenTelemetry per aggiungere i Orleansmetri 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.
