Delen via

Orleans gebruiken met .NET Aspire

  • Artikel

Orleans heeft ingebouwde ondersteuning voor .NET Aspire. Het toepassingsmodel van .NET.NET Aspirelaat u toe de services, databases en andere resources/infrastructuur in uw app te beschrijven en hoe deze zich tot elkaar verhouden. Orleans biedt een eenvoudige manier om gedistribueerde toepassingen te bouwen die elastisch schaalbaar en fouttolerant zijn. .NET Aspire wordt gebruikt voor het configureren en organiseren van Orleans en de bijbehorende afhankelijkheden, zoals het verstrekken van Orleans met databaseclusterlidmaatschap en -opslag.

Orleans wordt weergegeven als een resource in .NET Aspire. De Orleans-resource bevat configuratie die uw service moet uitvoeren, zoals providers van clusterlidmaatschappen en opslagproviders.

Voorwaarden

Als u met .NET.NET Aspirewilt werken, hebt u het volgende lokaal geïnstalleerd:

Zie .NET.NET Aspire setup en hulpprogramma'sen .NET.NET Aspire SDK-voor meer informatie.

Naast de vereisten voor .NET.NET Aspirehebt u het volgende nodig:

  • Orleans versie 8.1.0 of hoger

Voor meer informatie, zie .NET.NET Aspire instellen en hulpprogramma's.

Aan de slag gaan

Om aan de slag te gaan, moet u het Orleans hostingpakket toevoegen aan uw app-hostproject door het 📦Aspire.Hosting.Orleans NuGet package te installeren.

dotnet add package Aspire.Hosting.Orleans

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

De Orleans-resource wordt toegevoegd aan de .NET Aspire gedistribueerde opbouwfunctie voor toepassingen met behulp van de AddOrleans(string name) methode, die een Orleans opbouwfunctie voor resources retourneert. De naam die aan de Orleans resource is opgegeven, is bedoeld voor diagnostische doeleinden. Voor de meeste toepassingen volstaat een waarde van "default".

var orleans = builder.AddOrleans("default")

De Orleans resourcebouwer biedt methoden voor het configureren van uw Orleans resource.

Als u Orleans wilt configureren met clustering en graanopslag, installeert u de 📦Aspire.Hosting.Azure.storage NuGet-pakket in het app-hostproject:

dotnet add package Aspire.Hosting.Azure.Storage

In het volgende voorbeeld wordt de Orleans-resource geconfigureerd met clustering en graanopslag met behulp van respectievelijk de methoden WithClustering en 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);

De voorgaande code vertelt Orleans dat elke service waarnaar wordt verwezen, ook moet verwijzen naar de clusteringTable resource.

Als u wilt deelnemen aan een Orleans-cluster, raadpleegt u de Orleans-bron van uw serviceproject, hetzij met behulp van WithReference(orleans) om als Orleansserverdeel te nemen, of met WithReference(orleans.AsClient()) om als clientdeel te nemen. Wanneer u naar de Orleans-bron van uw service verwijst, worden die bronnen ook aangeroepen.

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

Hier volgt een voorbeeld van een .NET.NET Aspire app-hostproject, waaronder:

  • Een Orleans resource met clustering en opslag.
  • Een Orleansserver project, OrleansServer.
  • Een Orleansclient project, 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();

Als u de .NET AspireOrleans resource van een Orleansserver-project wilt gebruiken, zijn er enkele stappen:

  1. Voeg de relevante .NET.NET Aspire-integraties toe. In dit voorbeeld gebruikt u Aspire.Azure.Data.Tables en Aspire.Azure.Storage.Blobs.
  2. Voeg de Orleans providerpakketten toe voor de .NET Aspire-integraties. In dit voorbeeld gebruikt u Microsoft.Orleans.Persistence.AzureStorage en Microsoft.Orleans.Clustering.AzureStorage.
  3. Voeg Orleans toe aan de opbouwfunctie voor hosttoepassingen.

In het Program.cs-bestand van uw Orleansserver-project moet u de .NET Aspire-integraties configureren die u gebruikt en Orleans toevoegen aan de hostbouwer. De opgegeven namen moeten overeenkomen met de namen die worden gebruikt in het .NET.NET Aspire app-hostproject: 'clustering' voor de clusterprovider en 'grain-state' voor de provider van de grainstatusopslag:

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

U doet hetzelfde in het project OrleansClient, waarbij u de .NET Aspire resources toevoegt die uw project nodig heeft om toe te treden tot het Orleans-cluster als een client, en configureert u de hostbouwer om een Orleansclienttoe te voegen.

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

OpenTelemetry inschakelen

Standaard bevatten .NET.NET Aspire oplossingen een project voor het definiëren van standaardconfiguratie en -gedrag voor uw service. Dit project wordt de -servicestandaard project genoemd en sjablonen maken het met een naam die eindigt op ServiceDefaults. Als u Orleans wilt configureren voor OpenTelemetry in .NET Aspire, moet u de configuratie toepassen op het standaardproject van uw service volgens de handleiding Orleans waarneembaarheid. Kortom, u moet de methode ConfigureOpenTelemetry wijzigen om de meters Orleans toe te voegen en traceerinstrumenten. In het volgende codefragment ziet u het gewijzigde Extensions.cs-bestand van een servicestandaardproject met metrische gegevens en traceringen uit 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;
}

Ondersteunde providers

De OrleansAspire-integratie ondersteunt momenteel een beperkte subset van Orleans providers:

  • Clustering:
    • Redis
    • Azure Opslagtabellen
  • Volharding:
    • Redis
    • Azure Opslagtabellen
    • Azure Storageblobs
  • Herinneringen:
    • Redis
    • Azure Opslagtabellen
  • Graanoverzicht
    • Redis
    • Azure Opslagtabellen

Streamingproviders worden niet ondersteund vanaf Orleans versie 8.1.0.

Volgende stappen

De Orleans voorbeeld-app voor stemmen verkennen