integração .NET AspireOrleans
Orleans tem suporte interno para .NET.NET Aspire. .NET .NET Aspiremodelo de aplicativo permite descrever os serviços, bancos de dados e outros recursos e infraestrutura em seu aplicativo e como eles se relacionam entre si. Orleans fornece uma maneira simples de criar aplicativos distribuídos que são elasticamente escalonáveis e tolerantes a falhas. Você pode usar .NET Aspire para configurar e orquestrar Orleans e suas dependências, como fornecendo associação e armazenamento de cluster para Orleans.
Orleans é representado como um recurso no .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 de cliente separado. Em vez disso, você conclui a configuração de Orleans no projeto de hospedagem do aplicativo .NET Aspire.
Nota
Essa 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 acessar esse tipo e APIs, adicione o pacote NuGet 📦Aspire.Hosting.Orleans no projeto do host do aplicativo .
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.
Adicionar um recurso Orleans
No projeto de host do aplicativo, chame AddOrleans para adicionar e retornar um construtor de recursos de serviço 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")
Usar armazenamento Azure para agrupamento de tabelas e armazenamento de 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 dos 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 opção popular para armazenar essa tabela é Azure Table Storage.
Para configurar Orleans com clustering e armazenamento de grãos em Azure, instale o pacote NuGet 📦Aspire.Hosting.Azure.Storage no projeto de host do aplicativo:
dotnet add package Aspire.Hosting.Azure.Storage
No projeto do host do aplicativo, depois de chamar AddOrleans, configure o recurso Orleans com agrupamento e armazenamento de dados, utilizando 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 deve referenciar o recurso clusteringTable.
Adicionar um projeto de servidor Orleans no host do aplicativo
Agora você pode adicionar um novo projeto, inscrito na orquestração .NET Aspire, à sua solução como servidor Orleans. Ele participará do cluster Orleans como um silo com grãos constituintes. Faça referência ao recurso Orleans do seu projeto de servidor usando WithReference(orleans). Quando você faz referência ao recurso Orleans do 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 cliente Orleans no host do aplicativo
Clientes Orleans se comunicam com grains 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. Faça referência ao recurso Orleans do cliente Orleans 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 do servidor Orleans
Agora que o projeto de host do aplicativo está concluído, você pode implementar o projeto do servidor Orleans. Vamos começar adicionando os pacotes NuGet necessários:
Na pasta do projeto do servidor Orleans, 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 projeto do servidor Orleans, adicione os clientes de blob e tabelas de Armazenamento Azure e 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 de servidor Orleans, 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 cliente Orleans
No projeto do cliente Orleans, 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 cliente Orleans, adicione o cliente de armazenamento de tabelas Azure e, em seguida, chame UseOrleansClient.
builder.AddKeyedAzureTableClient("clustering");
builder.UseOrleansClient();
O código a seguir é um exemplo completo de um projeto cliente Orleans. Ele chama o grão CounterGrain definido no exemplo acima do servidor Orleans.
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 projeto de padrões de serviço 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 padrão de serviço seguindo o guia de Orleans observabilidade.
Modifique o método ConfigureOpenTelemetry para adicionar os medidores Orleans, e os instrumentos de rastreamento . 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.
