Udostępnij za pośrednictwem

integracja .NET AspireOrleans

  • Artykuł

Orleans ma wbudowaną obsługę .NET.NET Aspire. model aplikacji .NET.NET Aspireumożliwia opisywanie usług, baz danych i innych zasobów oraz infrastruktury w aplikacji oraz ich powiązania ze sobą. Orleans zapewnia prosty sposób tworzenia aplikacji rozproszonych, które są elastycznie skalowalne i odporne na błędy. Można użyć .NET Aspire do konfigurowania i orkiestracji Orleans oraz jego zależności, takich jak zapewnienie Orleans członkostwa w klastrze i przestrzeni magazynowej.

Orleans jest reprezentowana jako zasób w .NET Aspire. W przeciwieństwie do innych integracji integracja Orleans nie tworzy kontenera i nie wymaga oddzielnego pakietu integracji klienta. Zamiast tego należy ukończyć konfigurację Orleans w projekcie hosta aplikacji .NET Aspire.

Notatka

Ta integracja wymaga Orleans w wersji 8.1.0 lub nowszej.

Integracja hostingu

Model integracji usługi Orleans przedstawia Orleans jako typ OrleansService. Aby uzyskać dostęp do tego typu i interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.Orleans w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.Orleans

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w .NET aplikacjach.

Dodawanie zasobu Orleans

W projekcie hosta aplikacji wywołaj AddOrleans, aby dodać i zwrócić konstruktor zasobów usługi Orleans. Nazwa podana dla zasobu Orleans służy do celów diagnostycznych. W przypadku większości aplikacji wystarczy wartość "default".

var orleans = builder.AddOrleans("default")

Używanie magazynu Azure do klastrowania tabel i magazynu ziarna

W aplikacji Orleans podstawowym blokiem konstrukcyjnym jest ziarno. Ziarna mogą mieć trwałe stany. Należy przechowywać trwały stan ziarna gdzieś. W aplikacji .NET.NET AspireAzure Blob Storage jest jedną z możliwych lokalizacji.

Orleans hosty rejestrują się w bazie danych i używają tej bazy danych do znajdowania się nawzajem i tworzenia klastra. Przechowują, które serwery są członkami silosów w tabeli bazy danych. Do przechowywania tych informacji można użyć relacyjnych lub baz danych NoSQL. W aplikacji .NET.NET Aspire popularnym wyborem do przechowywania tej tabeli jest Azure Table Storage.

Aby skonfigurować Orleans do klastrowania i magazynowania ziarna w Azure, zainstaluj pakiet NuGet 📦Aspire.Hosting.Azure.Storage w projekcie hosta aplikacji.

dotnet add package Aspire.Hosting.Azure.Storage

W projekcie hosta aplikacji po wywołaniu AddOrleansskonfiguruj zasób Orleans z użyciem klastrowania i magazynu ziarna, korzystając odpowiednio z metod WithClustering i 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);

Powyższy kod informuje Orleans, że każda usługa odwołująca się do niej musi również odwoływać się do zasobu clusteringTable.

Dodawanie projektu serwera Orleans na hoście aplikacji

Teraz możesz dodać do swojego rozwiązania nowy projekt włączony do orkiestracji .NET Aspire jako serwer Orleans. Weźmie udział w klastrze Orleans jako silos z ziarnami składowymi. Odwołuj się do zasobu Orleans z projektu serwera przy użyciu WithReference(orleans). W przypadku odwoływania się do zasobu Orleans ze swojej usługi, te zasoby są również przywoływane:

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

Dodaj projekt klienta Orleans do hosta aplikacji

Orleans klienci komunikują się z ziarnami hostowanymi na serwerach Orleans. Na przykład w aplikacji .NET Aspire możesz mieć stronę internetową front-endu, która wywołuje ziarna w klastrze Orleans. Odwołuj się do zasobu Orleans z klienta Orleans przy użyciu 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);

Tworzenie projektu serwera Orleans

Po zakończeniu projektu hosta aplikacji możesz zaimplementować projekt serwera Orleans. Zacznijmy od dodania niezbędnych pakietów NuGet:

W folderze projektu serwera Orleans uruchom następujące polecenia:

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

Następnie w pliku Program.cs projektu serwera Orleans dodaj klientów blobów i tabel usługi Azure Storage, a następnie wywołaj UseOrleans.

var builder = WebApplication.CreateBuilder(args);

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

Poniższy kod jest kompletnym przykładem projektu serwera Orleans, w tym ziarna o nazwie 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;
    }
}

Tworzenie projektu klienta Orleans

W projekcie klienta Orleans dodaj te same pakiety 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

Następnie w pliku Program.cs projektu klienta Orleans dodaj klienta usługi Azure Table Storage, a następnie wywołaj UseOrleansClient.

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

Poniższy kod jest kompletnym przykładem projektu klienta Orleans. Wywołuje on ziarno CounterGrain zdefiniowane w powyższym przykładzie serwera Orleans:

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

Włączanie OpenTelemetry

Zgodnie z konwencją rozwiązania .NET.NET Aspire obejmują projekt służący do definiowania domyślnej konfiguracji i zachowania usługi. Projekt nosi nazwę projektu domyślnych ustawień usługi , a szablony tworzą go z nazwą kończącą się na ServiceDefaults. Aby skonfigurować Orleans dla OpenTelemetry w .NET Aspire, zastosuj konfigurację do domyślnego projektu usługi zgodnie z przewodnikiem po możliwościach obserwowalności Orleans.

Zmodyfikuj metodę ConfigureOpenTelemetry, aby dodać mierniki Orleans oraz instrumenty śledzące . Poniższy fragment kodu przedstawia zmodyfikowany plik Extensions.cs z projektu domyślnego usługi, który zawiera metryki i ślady 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;
}

Obsługiwani dostawcy

Integracja OrleansAspire obsługuje obecnie ograniczony podzestaw dostawców Orleans:

  • Klastrowanie:
    • Redis
    • Tabele składowania Azure
  • Wytrwałość:
    • Redis
    • Tabele składowania Azure
    • Bloby magazynowe Azure
  • Przypomnienia:
    • Redis
    • Tabele składowania Azure
  • Katalog ziarna:
    • Redis
    • Tabele składowania Azure

Usługi streamingowe nie są obsługiwane w wersji Orleans 8.1.0.

Następne kroki

dokumentacja Microsoft OrleansEksploruj przykładową aplikację do głosowania Orleans