Freigeben über

Verwenden Sie Orleans mit .NET Aspire

  • Artikel

Orleans verfügt über integrierte Unterstützung für .NET Aspire. Mit dem Anwendungsmodell von .NET.NET Aspirekönnen Sie die Dienste, Datenbanken und andere Ressourcen/Infrastruktur in Ihrer App sowie deren Beziehungen zueinander beschreiben. Orleans bietet eine einfache Möglichkeit, verteilte Anwendungen zu erstellen, die elastisch skalierbar und fehlertolerant sind. .NET Aspire wird verwendet, um Orleans und seine Abhängigkeiten zu konfigurieren und zu orchestrieren, z. B. durch die Bereitstellung von Datenbankcluster-Mitgliedschaft und Speicher für Orleans.

Orleans wird als Ressource in .NET Aspiredargestellt. Die Orleans Ressource umfasst die Konfiguration, die Ihr Dienst benötigt, um zu funktionieren, wie Clustermitgliedschaftsanbieter und Speicheranbieter.

Voraussetzungen

Um mit .NET.NET Aspirezu arbeiten, benötigen Sie folgendes lokal installiert:

Weitere Informationen finden Sie unter .NET.NET Aspire Setup und Toolingsowie .NET.NET Aspire SDK.

Zusätzlich zu den Voraussetzungen für .NET.NET Aspirebenötigen Sie Folgendes:

  • Orleans Version 8.1.0 oder höher

Weitere Informationen finden Sie unter .NET.NET Aspire Einrichtung und Werkzeuge.

Loslegen

Um zu beginnen, müssen Sie das Orleans Hosting-Paket zu Ihrem App-Hostprojekt hinzufügen, indem Sie das 📦Aspire.Hosting.Orleans NuGet-Paket installieren.

dotnet add package Aspire.Hosting.Orleans

Weitere Informationen finden Sie unter dotnet add package oder Paketabhängigkeiten in .NET-Anwendungen verwalten.

Die Orleans Ressource wird dem .NET Aspire verteilten Anwendungs-Generator mithilfe der AddOrleans(string name)-Methode hinzugefügt, die einen Orleans Ressourcen-Generator zurückgibt. Der Name, der der Orleans Ressource vergeben wird, dient zu Diagnosezwecken. Für die meisten Anwendungen genügt ein Wert von "default".

var orleans = builder.AddOrleans("default")

Der Orleans Ressourcen-Konfigurator bietet Methoden zum Konfigurieren Ihrer Orleans Ressource.

Um Orleans mit Cluster- und Kornspeicherung zu konfigurieren, installieren Sie das 📦Aspire.Hosting.Azure.Storage--NuGet-Paket im App-Hostprojekt:

dotnet add package Aspire.Hosting.Azure.Storage

Im folgenden Beispiel wird die Ressource Orleans mit Clustering und Getreidespeichermethoden durch die Methoden WithClustering bzw. WithGrainStorage konfiguriert.

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

Der vorangehende Code weist Orleans darauf hin, dass jeder Dienst, der darauf verweist, auch auf die Ressource clusteringTable verweisen muss.

Um an einem Orleans Cluster teilzunehmen, verweisen Sie auf die Orleans Ressource aus Ihrem Dienstprojekt, indem Sie entweder WithReference(orleans) verwenden, um als Orleansserverteilzunehmen, oder WithReference(orleans.AsClient()), um als clientteilzunehmen. Wenn Sie auf die Orleans-Ressource von Ihrem Dienst verweisen, werden diese Ressourcen ebenfalls referenziert.

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

Wenn man alles zusammenfügt, hier ist ein Beispiel für ein .NET.NET Aspire App-Hostprojekt, das Folgendes umfasst:

  • Eine Orleans Ressource mit Clustering und Speicher.
  • Ein Orleansserver Projekt, OrleansServer.
  • Ein Orleansclient Projekt, 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();

Es gibt einige Schritte, um die .NET AspireOrleans Ressource aus einem Orleansserver Projekt zu nutzen:

  1. Fügen Sie die relevanten .NET.NET Aspire Integrationen hinzu. In diesem Beispiel verwenden Sie Aspire.Azure.Data.Tables und Aspire.Azure.Storage.Blobs.
  2. Fügen Sie die Orleans Provider-Pakete für jene .NET Aspire Integrationen hinzu. In diesem Beispiel verwenden Sie Microsoft.Orleans.Persistence.AzureStorage und Microsoft.Orleans.Clustering.AzureStorage.
  3. Fügen Sie Orleans zum Hostanwendungs-Generator hinzu.

In der Program.cs-Datei Ihres Orleansserver Projekts müssen Sie die von Ihnen verwendeten .NET Aspire-Integrationen konfigurieren und dem Host-Builder Orleans hinzufügen. Die angegebenen Namen müssen mit den Namen übereinstimmen, die im .NET.NET Aspire App-Hostprojekt verwendet werden: "clustering" für den Clustering-Provider und "grain-state" für den Grain State Speicherprovider.

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

Im OrleansClient--Projekt gehen Sie ähnlich vor, indem Sie die .NET Aspire Ressourcen hinzufügen, die Ihr Projekt benötigt, um als Orleansdem client Cluster beizutreten, und den Host-Builder so konfigurieren, dass ein Orleansclienthinzugefügt wird.

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

Aktivieren von OpenTelemetry

Standardmäßig enthalten .NET.NET Aspire Lösungen ein Projekt zum Definieren der Standardkonfiguration und des Standardverhaltens für Ihren Dienst. Dieses Projekt wird als Dienststandard-Projekt bezeichnet, und Vorlagen erstellen es mit einem Namen, der auf ServiceDefaultsendet. Um Orleans für OpenTelemetry in .NET Aspirezu konfigurieren, müssen Sie die Konfiguration auf Ihr Standarddienstprojekt anwenden, basierend auf dem Orleans Observability Handbuch. Kurz gesagt, müssen Sie die ConfigureOpenTelemetry Methode ändern, um die OrleansZähler und Nachverfolgung Instrumente hinzuzufügen. Der folgende Codeausschnitt zeigt die geänderte Extensions.cs Datei aus einem Dienststandardprojekt, das Metriken und Ablaufverfolgungen aus Orleansenthält.

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

Unterstützte Anbieter

Die OrleansAspire-Integration unterstützt heute eine begrenzte Teilmenge von Orleans-Anbietern.

  • Clusterbildung:
    • Redis
    • Azure Speichertabellen
  • Ausdauer:
    • Redis
    • Azure Speichertabellen
    • Azure Speicherblobs
  • Erinnerungen:
    • Redis
    • Azure Speichertabellen
  • Getreideverzeichnis:
    • Redis
    • Azure Speichertabellen

Streaminganbieter werden ab Orleans Version 8.1.0 nicht unterstützt.

Nächste Schritte

Erkunden Sie die Orleans Beispiel-App zur Abstimmung