Delen via


integratie van .NET AspireOrleans

Orleans heeft ingebouwde ondersteuning voor .NET.NET Aspire. .NET .NET Aspire's toepassingsmodel stelt u in staat om de services, databases en andere resources en 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. U kunt .NET Aspire gebruiken om Orleans en de bijbehorende afhankelijkheden te configureren en te organiseren, zoals door Orleans met clusterlidmaatschap en -opslag op te geven.

Orleans wordt weergegeven als een resource in .NET Aspire. In tegenstelling tot andere integraties maakt de Orleans-integratie geen container en is er geen afzonderlijk clientintegratiepakket vereist. In plaats daarvan voltooit u de Orleans configuratie in het .NET Aspire app-hostproject.

Notitie

Voor deze integratie is Orleans versie 8.1.0 of hoger vereist.

Hostingintegratie

De Orleans-hostingintegatie modelleert een Orleans-service als het OrleansService-type. Als u toegang wilt krijgen tot dit type en deze API's, voegt u het 📦Aspire.Hosting.Orleans NuGet-pakket toe in het app-hostproject.

dotnet add package Aspire.Hosting.Orleans

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

Een Orleans-resource toevoegen

Roep in uw app-hostproject AddOrleans aan om een Orleans serviceresourcebouwer toe te voegen en te retourneren. 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")

Gebruik Azure-opslag voor clusteringtabellen en graanopslag

In een Orleans-app is de fundamentele bouwsteen een graan. Korrels kunnen duurzame toestanden hebben. U moet de duurzame status ergens opslaan voor een graan. In een .NET.NET Aspire toepassing is Azure Blob Storage één mogelijke locatie.

Orleans hosts zich registreren in een database en die database gebruiken om elkaar te vinden en een cluster te vormen. Ze slaan op welke servers lid zijn van welke silo's in een databasetabel. U kunt relationele of NoSQL-databases gebruiken om deze informatie op te slaan. In een .NET.NET Aspire toepassing is een populaire keuze om deze tabel op te slaan Azure Table Storage.

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

dotnet add package Aspire.Hosting.Azure.Storage

Configureer in uw app-hostproject, nadat u AddOrleanshebt aangeroepen, respectievelijk de Orleans-resource met clustering en graanopslag met behulp van de WithClustering- en WithGrainStorage methoden:

// 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 naar de clusteringTable resource moet verwijzen.

Een Orleans serverproject toevoegen aan de app-host

U kunt nu een nieuw project, ingeschreven bij .NET Aspire indeling, toevoegen aan uw oplossing als een Orleans-server. Het neemt deel aan het Orleans cluster als een silo met samenstellende korrels. Verwijs naar de Orleans resource van uw serverproject met behulp van WithReference(orleans). Wanneer u naar de Orleans-bron van uw service verwijst, worden die bronnen ook aangeroepen.

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

Een Orleans-clientproject toevoegen in de app-host

Orleans clients communiceren met grains die gehost worden op Orleans servers. In een .NET Aspire-app hebt u bijvoorbeeld een front-end-website die korrels aanroept in een Orleans-cluster. Verwijs naar de Orleans resource van uw Orleans-client met behulp van 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);

Het Orleans-serverproject maken

Nu het app-hostproject is voltooid, kunt u het Orleans serverproject implementeren. Laten we beginnen met het toevoegen van de benodigde NuGet-pakketten:

Voer in de map voor het Orleans serverproject de volgende opdrachten uit:

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

Voeg vervolgens in het Program.cs bestand van uw Orleans serverproject de Azure Storage-blob- en tabellenclients toe en roep UseOrleansaan.

var builder = WebApplication.CreateBuilder(args);

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

De volgende code is een volledig voorbeeld van een Orleans serverproject, met inbegrip van een graan met de naam 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;
    }
}

Een Orleans-clientproject maken

Voeg in het Orleans-clientproject dezelfde NuGet-pakketten toe:

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

Voeg vervolgens in het Program.cs bestand van uw Orleans clientproject de Azure table storage-client toe en roep UseOrleansClientaan.

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

De volgende code is een volledig voorbeeld van een Orleans-clientproject. Hiermee wordt het CounterGrain graan aanroepen dat is gedefinieerd in het bovenstaande Orleans servervoorbeeld:

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 heet het Service Defaults project en de sjablonen maken het met een naam die eindigt op ServiceDefaults. Als u Orleans wilt configureren voor OpenTelemetry in .NET Aspire, past u de configuratie toe op het standaardproject van uw service volgens de handleiding Orleans waarneembaarheid.

Wijzig de methode ConfigureOpenTelemetry om de Orleansmeters toe te voegen en instrumenten te traceren. 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