Поделиться через

Используйте Orleans с .NET Aspire

  • Статья

Orleans имеет встроенную поддержку .NET Aspire. модель приложения .NET.NET Aspireпозволяет описать службы, базы данных и другие ресурсы и инфраструктуру в приложении и их связь. Orleans предоставляет простой способ создания распределенных приложений, которые являются эластично масштабируемыми и отказоустойчивыми. .NET Aspire используется для настройки и оркестрации Orleans и его зависимостей, например, путем предоставления Orleans членства в кластере базы данных и хранилища.

Orleans представлен как ресурс в .NET Aspire. Ресурс Orleans включает конфигурацию, которая необходима для работы вашей службы, например, поставщики членства в кластере и поставщики хранилища.

Необходимые условия

Для работы с .NET.NET Aspireвам потребуется установить следующее локально:

См. дополнительные сведения в разделе .NET.NET Aspireпрограммы установки и инструментов и разделе .NET.NET Aspire пакета SDK.

Помимо необходимых требований для .NET.NET Aspire, вам потребуется:

  • Orleans версии 8.1.0 или более поздней

Дополнительные сведения см. в .NET.NET Aspire настройках и инструментах.

Начало работы

Чтобы приступить к работе, необходимо добавить хостинговый пакет Orleans в проект хоста приложения, установив пакет NuGet 📦Aspire. Хостинг.Orleans.

dotnet add package Aspire.Hosting.Orleans

Дополнительные сведения см. в статье о том, как добавить пакет с помощью команды dotnet add package или в статье Управление зависимостями пакетов в приложениях .NET.

Ресурс Orleans добавляется в построитель распределенных приложений .NET Aspire с помощью метода AddOrleans(string name), который возвращает построитель ресурсов Orleans. Имя, предоставленное ресурсу Orleans, предназначено для диагностики. Для большинства приложений достаточно значения "default".

var orleans = builder.AddOrleans("default")

Построитель ресурсов Orleans предлагает методы настройки Orleans ресурса.

Чтобы настроить Orleans с кластерами и хранением зерна, установите пакет NuGet 📦Aspire.Hosting.Azure.Storage в проект узла приложения:

dotnet add package Aspire.Hosting.Azure.Storage

В следующем примере ресурс Orleans настраивается с кластеризацией и хранилищем зерна с помощью методов WithClustering и 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);

Предыдущий код сообщает Orleans, что любая служба, ссылающаяся на нее, также должна ссылаться на ресурс clusteringTable.

Чтобы участвовать в кластере Orleans, обратитесь к ресурсу Orleans из вашего служебного проекта, используя WithReference(orleans) для участия в качестве Orleansserverили WithReference(orleans.AsClient()) для участия в качестве client. При обращении к ресурсу Orleans из вашей службы, также используются следующие ресурсы:

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

Собрав это все воедино, вот пример проекта хоста приложения .NET.NET Aspire, который включает в себя:

  • Ресурс Orleans с кластеризацией и хранилищем.
  • Проект OrleansserverOrleansServer.
  • Проект OrleansclientOrleansClient.
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();

Чтобы использовать ресурс .NET AspireOrleans из проекта Orleansserver, выполните несколько действий.

  1. Добавьте соответствующие .NET.NET Aspire интеграции. В этом примере используется Aspire.Azure.Data.Tables и Aspire.Azure.Storage.Blobs.
  2. Добавьте пакеты поставщиков Orleans для этих интеграций .NET Aspire. В этом примере используется Microsoft.Orleans.Persistence.AzureStorage и Microsoft.Orleans.Clustering.AzureStorage.
  3. Добавьте Orleans в конструктор приложений-хостов.

В файле Program.cs проекта Orleansserver необходимо настроить интеграции .NET Aspire, которые вы используете, и добавить Orleans в конструктор хоста. Указанные имена должны соответствовать именам, используемым в проекте узла приложения .NET.NET Aspire: "кластеризация" для поставщика кластеризации и "состояние зерна" для поставщика хранилища состояний зерна:

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

Аналогично в проекте OrleansClient, добавляя ресурсы .NET Aspire, которые необходимы для присоединения вашего проекта к кластеру Orleans как client, и настраивая объект HostBuilder для добавления 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();

Включение OpenTelemetry

По соглашению .NET.NET Aspire решения включают проект для определения конфигурации и поведения по умолчанию для вашей службы. Этот проект называется проектом по умолчанию для службы, а шаблоны создают его под именем с окончанием ServiceDefaults. Чтобы настроить для в , необходимо применить конфигурацию к проекту службы по умолчанию, следуя руководству наблюдаемости. Короче говоря, необходимо изменить метод ConfigureOpenTelemetry, чтобы добавить Orleansметров и средства трассировки. В следующем фрагменте кода показан измененный файл Extensions.cs из проекта с настройками по умолчанию службы, который включает метрики и трейсинги из 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;
}

Поддерживаемые поставщики

Интеграция OrleansAspire поддерживает ограниченное подмножество поставщиков Orleans сегодня:

  • Кластеризация:
    • Redis
    • Таблицы хранения Azure
  • Упорство:
    • Redis
    • Таблицы хранения Azure
    • BLOB-объекты хранилища Azure
  • Напоминания:
    • Redis
    • Таблицы хранения Azure
  • Каталог зерна
    • Redis
    • Таблицы хранения Azure

Поставщики потоковой передачи не поддерживаются по состоянию на Orleans версии 8.1.0.

Дальнейшие действия

Изучите Orleans пример приложения для голосования