Udostępnij za pośrednictwem

Użyj Orleans z .NET Aspire

  • Artykuł

Orleans posiada wbudowaną obsługę dla .NET Aspire. model aplikacji .NET.NET Aspireumożliwia opisywanie usług, baz danych i innych zasobów/infrastruktury w aplikacji oraz ich powiązania. Orleans zapewnia prosty sposób tworzenia aplikacji rozproszonych, które są elastycznie skalowalne i odporne na uszkodzenia. .NET Aspire służy do konfigurowania i orkiestracji Orleans oraz jego zależności, na przykład poprzez zapewnianie Orleans członkostwa w klastrze bazy danych oraz przestrzeni magazynowej.

Orleans jest reprezentowana jako zasób w .NET Aspire. Zasób Orleans obejmuje konfigurację, której Twoja usługa potrzebuje do działania, takich jak dostawcy członkostwa w klastrze i dostawcy magazynu.

Warunki wstępne

Aby pracować z .NET.NET Aspire, musisz mieć zainstalowane lokalnie następujące elementy:

Aby uzyskać więcej informacji, zobacz .NET.NET Aspire setup and toolingi .NET.NET Aspire SDK.

Oprócz wymagań wstępnych dotyczących .NET.NET Aspirepotrzebne są następujące elementy:

  • Orleans w wersji 8.1.0 lub nowszej

Aby uzyskać więcej informacji, zobacz .NET.NET Aspire konfigurację i narzędzia.

Zacznij

Aby rozpocząć, należy dodać pakiet hostingowy Orleans do projektu hosta aplikacji, instalując pakiet NuGet 📦Aspire.Hosting.Orleans.

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.

Zasób Orleans jest dodawany do konstruktora aplikacji rozproszonych .NET Aspire przy użyciu metody AddOrleans(string name), która zwraca konstruktor zasobów 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")

Konstruktor zasobów Orleans oferuje metody konfigurowania zasobu Orleans.

Aby skonfigurować Orleans przy użyciu klasteryzacji i przechowywania danych, zainstaluj pakiet NuGet 📦Aspire.Hostowanie.Azure.Storage w projekcie hosta aplikacji.

dotnet add package Aspire.Hosting.Azure.Storage

W poniższym przykładzie zasób Orleans jest skonfigurowany z klastrowaniem i magazynem ziarna przy użyciu odpowiednio 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 również musi odwoływać się do zasobu clusteringTable.

Aby wziąć udział w klastrze Orleans, należy odwołać się do zasobu Orleans z projektu usługi, używając WithReference(orleans), aby uczestniczyć jako Orleansserver, lub używając WithReference(orleans.AsClient()), aby uczestniczyć jako client. W przypadku odwoływania się do zasobu Orleans ze swojej usługi, te zasoby są również przywoływane:

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

Podsumowując, oto przykład projektu hosta aplikacji .NET.NET Aspire, który obejmuje:

  • Zasób Orleans z klastrowaniem i przechowywaniem.
  • Projekt Orleansserver, OrleansServer.
  • 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();

Aby korzystać z zasobu .NET AspireOrleans z projektu Orleansserver, wykonaj kilka kroków:

  1. Dodaj odpowiednie integracje .NET.NET Aspire. W tym przykładzie używasz Aspire.Azure.Data.Tables i Aspire.Azure.Storage.Blobs.
  2. Dodaj pakiety dostawców Orleans dla integracji .NET Aspire. W tym przykładzie używasz Microsoft.Orleans.Persistence.AzureStorage i Microsoft.Orleans.Clustering.AzureStorage.
  3. Dodaj Orleans do konstruktora aplikacji hosta.

W pliku Program.cs projektu Orleansserver należy skonfigurować integracje .NET Aspire używane i dodać Orleans do konstruktora hostów. Podane nazwy muszą być zgodne z nazwami używanymi w projekcie hosta aplikacji .NET.NET Aspire: "clustering" dla dostawcy klastrowania i "grain-state" dla dostawcy magazynu stanu ziarna.

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

Podobnie w projekcie OrleansClient dodaj zasoby .NET Aspire, których projekt potrzebuje, aby dołączyć do klastra Orleans jako client, i skonfiguruj konstruktora hosta, aby dodać 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();

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. Ten projekt jest nazywany domyślnym projektem usługi , a szablony tworzą go z nazwą kończącą się na ServiceDefaults. Aby skonfigurować Orleans dla OpenTelemetry w projekcie .NET Aspire, należy zastosować konfigurację do projektu ustawień domyślnych dla usługi zgodnie z przewodnikiem możliwości obserwacjiOrleans. Krótko mówiąc, należy zmodyfikować metodę ConfigureOpenTelemetry, aby dodać mierniki Orleans oraz instrumenty śledzenia . 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

Eksploruj przykładową aplikację do głosowania Orleans