Partilhar via

Use Orleans com .NET Aspire

  • Artigo

Orleans tem suporte integrado para .NET Aspire. O modelo de aplicação de .NET.NET Aspirepermite descrever os serviços, bancos de dados e outros recursos/infraestrutura na sua aplicação e como eles se relacionam. Orleans fornece uma maneira direta de criar aplicativos distribuídos que são elasticamente escaláveis e tolerantes a falhas. .NET Aspire é usado para configurar e orquestrar Orleans e as suas dependências, como, por exemplo, fornecendo ao Orleans a associação ao cluster de banco de dados e armazenamento.

Orleans é representado como um recurso em .NET Aspire. O recurso Orleans inclui a configuração que o seu serviço precisa para operar, como provedores de adesão ao cluster e provedores de armazenamento.

Pré-requisitos

Para trabalhar com .NET.NET Aspire, você precisa do seguinte instalado localmente:

Para obter mais informações, consulte .NET.NET Aspirede configuração e ferramentas e .NET.NET Aspire SDK.

Além dos pré-requisitos para .NET.NET Aspire, você precisa:

  • Orleans versão 8.1.0 ou posterior

Para obter mais informações, consulte .NET.NET Aspire configuração e ferramentas.

Começar

Para começar, tens de adicionar o pacote de alojamento Orleans ao teu projeto de hospedagem da aplicação, instalando o pacote NuGet 📦Aspire.Hosting.Orleans.

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.

O recurso Orleans é adicionado ao .NET Aspire construtor de aplicativos distribuídos usando o método AddOrleans(string name), que retorna um Orleans construtor de recursos. 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")

O construtor de recursos Orleans oferece métodos para configurar seu recurso Orleans.

Para configurar o Orleans com clustering e armazenamento de `grains`, instale o pacote NuGet 📦Aspire.Hosting.Azure.Storage no projeto de host da aplicação:

dotnet add package Aspire.Hosting.Azure.Storage

No exemplo a seguir, o recurso Orleans é configurado com agrupamento e armazenamento de grãos, utilizando os métodos WithClustering e WithGrainStorage, respetivamente:

// 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 precisa fazer referência ao recurso clusteringTable.

Para participar num cluster de Orleans, faça referência ao recurso Orleans do seu projeto de serviço, usando WithReference(orleans) para participar como Orleansserver, ou então WithReference(orleans.AsClient()) para participar como client. Quando você faz referência ao recurso Orleans do seu serviço, esses recursos também são referenciados:

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

Juntando tudo isso, aqui está um exemplo de um projeto de host de aplicativo .NET.NET Aspire que inclui:

  • Um recurso Orleans com clusterização e armazenamento.
  • Um projeto Orleansserver, OrleansServer.
  • Um projeto 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 o recurso .NET AspireOrleans de um projeto Orleansserver, há algumas etapas:

  1. Adicione as integrações relevantes de .NETe.NET Aspire. Neste exemplo, você está usando Aspire.Azure.Data.Tables e Aspire.Azure.Storage.Blobs.
  2. Adicione os pacotes de provedores Orleans para essas integrações .NET Aspire. Neste exemplo, você está usando Microsoft.Orleans.Persistence.AzureStorage e Microsoft.Orleans.Clustering.AzureStorage.
  3. Adicione Orleans ao construtor de aplicativos host.

No arquivo Program.cs do teu projeto Orleansserver, deves configurar as integrações de .NET Aspire que estás a usar e adicionar Orleans ao construtor de host. Os nomes fornecidos devem corresponder aos nomes usados no projeto de host do aplicativo .NET.NET Aspire: "clustering" para o provedor de clustering e "grain-state" para o provedor de armazenamento de estado de grão:

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

Você faz o mesmo no projeto OrleansClient, adicionando os recursos .NET Aspire que seu projeto precisa para ingressar no cluster de Orleans como um cliente configurando o construtor de host para adicionar um 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();

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. Este projeto é chamado de projeto Serviço Padrão, e os modelos criam-no com um nome que termina em ServiceDefaults. Para configurar Orleans para OpenTelemetry no .NET Aspire, deve aplicar a configuração aos padrões do seu projeto de serviço, seguindo o guia de observabilidade Orleans. Em resumo, precisa modificar o método ConfigureOpenTelemetry para adicionar os instrumentos de medição Orleansmetros e os instrumentos de rastreamento . 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

Explore o aplicativo de exemplo de votação Orleans