Compartir a través de

Uso de Orleans con .NET Aspire

  • Artículo

Orleans tiene compatibilidad integrada con .NET Aspire. .NET .NET Aspiremodelo de aplicación le permite describir los servicios, las bases de datos y otros recursos o infraestructuras de la aplicación y cómo se relacionan. Orleans proporciona una manera sencilla de crear aplicaciones distribuidas que son escalables elásticamente y tolerantes a errores. .NET Aspire se usa para configurar y orquestar Orleans y sus dependencias, como proporcionar a Orleans la pertenencia y almacenamiento del clúster de base de datos.

Orleans se representa como un recurso en .NET Aspire. El recurso Orleans incluye la configuración que el servicio necesita para funcionar, como proveedores de pertenencia a clústeres y proveedores de almacenamiento.

Prerrequisitos

Para trabajar con .NET.NET Aspire, necesita lo siguiente instalado localmente:

Para obtener más información, consulte configuración y herramientas de .NET.NET Aspirey sdk de .NET.NET Aspire.

Además de los requisitos previos para .NET.NET Aspire, necesitas:

  • Orleans versión 8.1.0 o posterior

Para obtener más información, consulte .NET.NET Aspire configuración y herramientas.

Comenzar

Para empezar, debe agregar el paquete de hospedaje de Orleans al proyecto host de la aplicación, mediante la instalación del paquete NuGet 📦Aspire.Hosting.Orleans.

dotnet add package Aspire.Hosting.Orleans

Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en aplicaciones .NET.

El recurso Orleans se agrega al generador de aplicaciones distribuidas .NET Aspire mediante el método AddOrleans(string name), que devuelve un generador de recursos Orleans. El nombre proporcionado al recurso Orleans es para fines de diagnóstico. Para la mayoría de las aplicaciones, basta un valor de "default".

var orleans = builder.AddOrleans("default")

El generador de recursos Orleans ofrece métodos para configurar el recurso de Orleans.

** Para configurar Orleans con clústeres y almacenamiento de grano, instale el paquete NuGet 📦Aspire.Hosting.Azure.Storage en el proyecto host de la aplicación.

dotnet add package Aspire.Hosting.Azure.Storage

En el siguiente ejemplo, el recurso Orleans se configura mediante clústeres y almacenamiento granular utilizando los métodos WithClustering y WithGrainStorage, respectivamente.

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

El código anterior indica Orleans que cualquier servicio que haga referencia a él también debe hacer referencia al recurso clusteringTable.

Para participar en un clúster de Orleans, refiérase al recurso Orleans de su proyecto de servicio, utilizando WithReference(orleans) para participar como un Orleansserver, o WithReference(orleans.AsClient()) para participar como un client. Al hacer referencia al recurso Orleans desde el servicio, también se hace referencia a esos recursos:

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

Al reunir todo esto, este es un ejemplo de un proyecto host de aplicación .NET.NET Aspire que incluye:

  • Un recurso Orleans con agrupación en clústeres y almacenamiento.
  • Un proyecto de Orleansserver, OrleansServer.
  • Un proyecto de Orleansclient, 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();

Para consumir el recurso de .NET AspireOrleans desde un proyecto de Orleansserver, hay algunos pasos:

  1. Agregue las integraciones de .NET.NET Aspire pertinentes. En este ejemplo, estás utilizando Aspire.Azure.Data.Tables y Aspire.Azure.Storage.Blobs.
  2. Agregue los paquetes de proveedor de Orleans para esas integraciones de .NET Aspire. En este ejemplo, estás utilizando Microsoft.Orleans.Persistence.AzureStorage y Microsoft.Orleans.Clustering.AzureStorage.
  3. Agregue Orleans al generador de aplicaciones host.

En el archivo Program.cs del proyecto de Orleansserver, debe configurar las integraciones de .NET Aspire que usa y agregar Orleans al generador de hosts. Los nombres proporcionados deben coincidir con los nombres utilizados en el proyecto de host de la aplicación de .NET.NET Aspire: "clustering" para el proveedor de clustering y "grain-state" para el proveedor de almacenamiento de estado de grano.

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

De forma similar, en el proyecto de OrleansClient, agregue los recursos de .NET Aspire que su proyecto necesita para unirse al clúster de Orleans como un client, configurando el generador de hosts para agregar un 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();

Habilitación de OpenTelemetry

Por convención, las soluciones de .NET.NET Aspire incluyen un proyecto para definir la configuración y el comportamiento predeterminados para el servicio. Este proyecto se llama proyecto predeterminado del servicio y las plantillas lo crean con un nombre que termina en ServiceDefaults. Para configurar para en , debe aplicar la configuración al proyecto predeterminado del servicio siguiendo la guía de de observabilidad de . En resumen, debe modificar el método ConfigureOpenTelemetry para agregar los instrumentos de seguimiento de los medidores Orleans y . En el siguiente fragmento de código se muestra el archivo modificado Extensions.cs de un proyecto predeterminado de servicio que incluye métricas y seguimientos de 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;
}

Proveedores admitidos

La integración de OrleansAspire admite actualmente un subconjunto limitado de proveedores de Orleans:

  • Agrupamiento:
    • Redis
    • Mesas de almacenamiento Azure
  • Persistencia:
    • Redis
    • Mesas de almacenamiento Azure
    • Blobs de Almacenamiento Azure
  • Recordatorios:
    • Redis
    • Mesas de almacenamiento Azure
  • Directorio de granos:
    • Redis
    • Mesas de almacenamiento Azure

A partir de la versión 8.1.0 de Orleans, no se admiten los proveedores de streaming.

Pasos siguientes

Explorar la aplicación de ejemplo de votación Orleans