Sdílet prostřednictvím

Použijte Orleans s .NET Aspire

  • Článek

Orleans má integrovanou podporu pro .NET Aspire. .NET .NET Aspireaplikační model umožňuje popsat služby, databáze a další prostředky a infrastrukturu v aplikaci a jejich vztah. Orleans poskytuje jednoduchý způsob vytváření distribuovaných aplikací, které jsou elasticky škálovatelné a odolné proti chybám. .NET Aspire slouží ke konfiguraci a orchestraci Orleans a jejích závislostí, jako je například poskytování Orleans členství v databázovém clusteru a úložiště.

Orleans je reprezentován jako prostředek v .NET Aspire. Prostředek Orleans zahrnuje konfiguraci, kterou vaše služba potřebuje provozovat, jako jsou poskytovatelé členství v clusteru a poskytovatelé úložiště.

Požadavky

Pokud chcete pracovat s .NET.NET Aspire, potřebujete místně nainstalovat následující:

Další informace najdete v tématu .NET.NET Aspire nastavení a nástrojea .NET.NET Aspire SDK.

Kromě požadavků na .NET.NET Aspirepotřebujete:

  • Orleans verze 8.1.0 nebo novější

Další informace viz .NET.NET Aspire nastavení a nástroje.

Začněte

Abyste mohli začít, musíte přidat hostingový balíček Orleans do hostitelského projektu aplikace tím, že nainstalujete NuGet balíček 📦Aspire.Hosting.Orleans.

dotnet add package Aspire.Hosting.Orleans

Další informace najdete v části dotnet add package nebo v části Správa závislostí balíčků v aplikacích .NET.

Prostředek Orleans je přidán do nástroje pro sestavování distribuovaných aplikací .NET Aspire pomocí metody AddOrleans(string name), která vrátí sestavovač prostředků Orleans. Název poskytnutý prostředku Orleans slouží k diagnostickým účelům. Pro většinu aplikací stačí hodnota "default".

var orleans = builder.AddOrleans("default")

Tvůrce prostředků Orleans nabízí metody konfigurace Orleans prostředku.

Pokud chcete nakonfigurovat Orleans s klastrováním a úložištěm zrn, nainstalujte balíček NuGet 📦Aspire.Hosting.Azure.Storage v projektu hostitele aplikace.

dotnet add package Aspire.Hosting.Azure.Storage

V následujícím příkladu je prostředek Orleans nakonfigurován s klastrovaním a úložištěm zrna pomocí metod WithClustering a 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);

Předchozí kód informuje Orleans, že každá služba, na kterou odkazuje, musí také odkazovat na clusteringTable prostředek.

Chcete-li se zapojit do clusteru Orleans, odkazujte na zdroj Orleans ze svého projektu služby, buď pomocí WithReference(orleans) k účasti jako Orleansserver, nebo WithReference(orleans.AsClient()) k účasti jako client. Když odkazujete na prostředek Orleans ze své služby, tyto prostředky jsou také odkazovány:

// 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);

Tady je příklad hostitelského projektu aplikace .NET.NET Aspire, který zahrnuje:

  • Prostředek Orleans s seskupováním a úložištěm.
  • Projekt OrleansserverOrleansServer.
  • Projekt OrleansclientOrleansClient.
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();

Pokud chcete využívat .NET AspireOrleans zdroj z projektu Orleansserver, existuje několik kroků:

  1. Přidejte relevantní integrace .NET.NET Aspire. V tomto příkladu používáte Aspire.Azure.Data.Tables a Aspire.Azure.Storage.Blobs.
  2. Přidejte balíčky zprostředkovatele Orleans pro tyto integrace .NET Aspire. V tomto příkladu používáte Microsoft.Orleans.Persistence.AzureStorage a Microsoft.Orleans.Clustering.AzureStorage.
  3. Přidejte Orleans do vytvářeče hostitelské aplikace.

V souboru Program.cs projektu Orleansserver musíte nakonfigurovat .NET Aspire integrace, které používáte, a přidat Orleans do tvůrce hostu. Zadané názvy se musí shodovat s názvy použitými v projektu hostitele aplikace .NET.NET Aspire: "clustering" pro zprostředkovatele clusteringu a "grain-state" pro poskytovatele úložiště se stavem zrnitosti:

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;
    }
}

Podobně postupujte v projektu OrleansClient, přidáním .NET Aspire prostředků, které váš projekt potřebuje pro připojení se ke clusteru Orleans jako client, a nakonfigurujte tvůrce hostitele tak, aby přidal 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();

Povolení OpenTelemetry

Podle konvence zahrnují .NET.NET Aspire řešení projekt pro definování výchozí konfigurace a chování vaší služby. Tento projekt se nazývá projekt výchozí služby a šablony ho vytvoří s názvem končícím na ServiceDefaults. Pokud chcete nakonfigurovat Orleans pro OpenTelemetry v .NET Aspire, je potřeba použít konfiguraci na výchozí projekt vaší služby podle průvodce pozorovatelnosti Orleans. Stručně řečeno, musíte upravit metodu ConfigureOpenTelemetry tak, aby přidávala měřiče Orleans a nástroje pro trasování . Následující fragment kódu ukazuje upravený soubor Extensions.cs z výchozího projektu služby, který obsahuje metriky a trasování z 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;
}

Podporovaní poskytovatelé

Integrace OrleansAspire dnes podporuje omezenou podmnožinu poskytovatelů Orleans:

  • Shlukování:
    • Redis
    • tabulky úložiště Azure
  • Perzistence:
    • Redis
    • tabulky úložiště Azure
    • Azure Blobů úložiště
  • Upomínky:
    • Redis
    • tabulky úložiště Azure
  • Adresář zrna
    • Redis
    • tabulky úložiště Azure

Poskytovatelé streamování nejsou podporováni ve verzi Orleans 8.1.0.

Další kroky

Prozkoumejte ukázkovou aplikaci Orleans hlasování