Partilhar via

.NET Aspire Orleans integração

  • Artigo

Orleans tem suporte integrado para .NET.NET Aspire. .NET .NET Aspiremodelo de aplicação permite descrever os serviços, bancos de dados e outros recursos e infraestruturas na sua aplicação e como se relacionam. Orleans fornece uma maneira simples de criar aplicativos distribuídos que são elasticamente escaláveis e tolerantes a falhas. Você pode usar .NET Aspire para configurar e orquestrar Orleans e suas dependências, por exemplo, fornecendo à Orleans associação de cluster e armazenamento.

Orleans é representado como um recurso em .NET Aspire. Ao contrário de outras integrações, a integração Orleans não cria um contêiner e não requer um pacote de integração client separado. Em vez disso, você conclui a configuração Orleans no projeto de host do aplicativo .NET Aspire.

Observação

Esta integração requer Orleans versão 8.1.0 ou posterior.

Integração de hospedagem

A integração de hospedagem Orleans modela um serviço Orleans como o tipo OrleansService. Para aceder este tipo e APIs, adicione o pacote NuGet 📦Aspire.Hospedagem.Orleans no projeto de aplicação host .

dotnet add package Aspire.Hosting.Orleans

Para obter mais informações, consulte dotnet add package ou Gerir dependências de pacotes em aplicações .NET.

Adicionar um recurso Orleans

Em seu projeto de host de aplicativo, chame AddOrleans para adicionar e retornar um Orleans construtor de recursos de serviço. O nome fornecido ao recurso Orleans é para fins de diagnóstico. Para a maioria dos aplicativos, um valor de "default" é suficiente.

var orleans = builder.AddOrleans("default")

Use o armazenamento Azure para agrupar tabelas e armazenar grãos

Em um aplicativo Orleans, o bloco de construção fundamental é um grão. Os grãos podem ter estados duráveis. Você deve armazenar o estado durável para um grão em algum lugar. Em um aplicativo .NET.NET Aspire, Azure Blob Storage é um local possível.

Orleans hosts se registram em um banco de dados e usam esse banco de dados para encontrar uns aos outros e formar um cluster. Eles armazenam quais servidores são membros de quais silos em uma tabela de banco de dados. Você pode usar bancos de dados relacionais ou NoSQL para armazenar essas informações. Em um aplicativo .NET.NET Aspire, uma escolha popular para armazenar esta tabela é Azure Table Storage.

Para configurar Orleans com clustering e armazenamento de grãos em Azure, instale o 📦Aspire.Hospedagem.Azure.Armazenamento pacote NuGet no projeto de hospedagem da aplicação:

dotnet add package Aspire.Hosting.Azure.Storage

No teu projeto de host de aplicação, depois de chamar AddOrleans, configura o recurso Orleans com clustering e armazenamento de grãos usando, respetivamente, os métodos WithClustering e 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);

O código anterior informa Orleans que qualquer serviço que faça referência a ele também deve fazer referência ao recurso clusteringTable.

Adicionar um projeto Orleansserver no host do aplicativo

Agora pode adicionar um novo projeto, inscrito em orquestração .NET Aspire, à sua solução como um Orleansserver. Participará do aglomerado Orleans como um silo com grãos constituintes. Faça referência ao recurso Orleans do seu projeto server usando WithReference(orleans). Quando você faz referência ao recurso Orleans do seu serviço, esses recursos também são referenciados:

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

Adicionar um projeto Orleansclient no host do aplicativo

Orleans clientes se comunicam com grãos hospedados em servidores Orleans. Em um aplicativo .NET Aspire, por exemplo, você pode ter um site front-end que chama grãos em um cluster Orleans. Consulte o recurso Orleans do seu Orleansclient usando 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);

Criar o projeto Orleansserver

Agora que o projeto de host do aplicativo foi concluído, você pode implementar o projeto Orleansserver. Vamos começar adicionando os pacotes NuGet necessários:

Na pasta do projeto Orleansserver, execute estes comandos:

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

Em seguida, no arquivo Program.cs do seu projeto Orleansserver, adicione os clientes de armazenamento para blob e tabelas Azure e, em seguida, chame UseOrleans.

var builder = WebApplication.CreateBuilder(args);

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

O código a seguir é um exemplo completo de um projeto Orleansserver, incluindo um grão chamado 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;
    }
}

Criar um projeto Orleansclient

No projeto Orleansclient, adicione os mesmos pacotes 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

Em seguida, no arquivo Program.cs do seu projeto Orleansclient, adicione o client de armazenamento de tabela Azure e chame UseOrleansClient.

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

O código a seguir é um exemplo completo de um projeto Orleansclient. Ele refere-se ao grão CounterGrain definido no exemplo Orleansserver acima.

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

Habilitando OpenTelemetry

Por convenção, .NET.NET Aspire soluções incluem um projeto para definir a configuração e o comportamento padrão para o seu serviço. Esse projeto é chamado de serviço padrão projeto e os modelos o criam com um nome que termina em ServiceDefaults. Para configurar Orleans para OpenTelemetry no .NET Aspire, aplique a configuração ao seu projeto de padrões do serviço seguindo o guia de observabilidade Orleans.

Modifique o método ConfigureOpenTelemetry para adicionar os medidores de Orleans e de rastreamento instrumentos. O trecho de código a seguir mostra o arquivo de Extensions.cs modificado de um projeto padrão de serviço que inclui métricas e rastreamentos 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;
}

Fornecedores suportados

A integração OrleansAspire suporta um subconjunto limitado de provedores de Orleans atualmente:

  • Agrupamento:
    • Redis
    • Azure Tabelas de armazenamento
  • Persistência:
    • Redis
    • Azure Tabelas de armazenamento
    • Blobs de armazenamento de dados Azure
  • Lembretes:
    • Redis
    • Azure Tabelas de armazenamento
  • Diretório de grãos:
    • Redis
    • Azure Tabelas de armazenamento

Os provedores de streaming não são suportados a partir de Orleans versão 8.1.0.

Próximos passos

documentação da Microsoft OrleansExplore o aplicativo de exemplo de votação Orleans