Compartilhar via

Usar Orleans com .NET Aspire

  • Artigo

Orleans tem suporte interno para .NET Aspire. .NET .NET Aspiremodelo de aplicativo permite descrever os serviços, bancos de dados e outros recursos/infraestrutura em seu aplicativo e como eles se relacionam. Orleans fornece uma maneira simples de criar aplicativos distribuídos que são elasticamente escalonáveis e tolerantes a falhas. .NET Aspire é usado para configurar e gerenciar Orleans e suas dependências, por exemplo, fornecendo a Orleans a associação ao cluster de banco de dados e o armazenamento.

Orleans é representado como um recurso no .NET Aspire. O recurso Orleans inclui configuração que seu serviço precisa para operar, como os provedores de associação de cluster e os 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 instalação e ferramentas e .NET.NET Aspiredo 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 instalação e ferramentas.

Começar

Para começar, você precisa adicionar o pacote de hospedagem Orleans ao projeto de host do aplicativo instalando o pacote NuGet 📦Aspire.Hosting.Orleans.

dotnet add package Aspire.Hosting.Orleans

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

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

Para configurar Orleans com clustering e armazenamento de grãos, instale 📦Aspire.Hosting.Azure.Storage pacote NuGet no projeto host do aplicativo.

dotnet add package Aspire.Hosting.Azure.Storage

No exemplo a seguir, o recurso Orleans é configurado com clustering e armazenamento de grãos usando os métodos WithClustering e 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);

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

Para participar de um cluster Orleans, faça referência ao recurso Orleans do seu projeto de serviço, usando WithReference(orleans) para participar como um Orleansserverou WithReference(orleans.AsClient()) para participar como um client. Quando você faz referência ao recurso Orleans do 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 de Orleans com agrupamento 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 de Orleansserver, há algumas etapas:

  1. Adicione as relevantes integrações de .NET.NET Aspire. Neste exemplo, você está usando Aspire.Azure.Data.Tables e Aspire.Azure.Storage.Blobs.
  2. Adicione os pacotes do provedor 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 seu projeto de Orleansserver, você deve configurar as integrações .NET Aspire que está usando 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 "estado de granulação" para o provedor de armazenamento de estado de grãos:

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 Orleans como um cliente configurando o construtor de hosts 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 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 para no , é necessário aplicar a configuração ao projeto de padrões de serviço seguindo o guia de observabilidade do . Em suma, você precisa modificar o método ConfigureOpenTelemetry para adicionar os medidores Orleanse os instrumentos de rastreamento e . O snippet 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;
}

Provedores com suporte

A integração OrleansAspire dá suporte a um subconjunto limitado de provedores de Orleans hoje:

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

Não há suporte para provedores de streaming a partir do Orleans versão 8.1.0.

Próximas etapas

Explore o aplicativo de exemplo de votação Orleans