интеграция .NET AspireOrleans

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

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

Интеграция хостинга

Orleans интеграция моделирует службу Orleans как тип OrleansService. Чтобы получить доступ к этому типу и API, добавьте пакет 📦Aspire.Hosting.Orleans NuGet в проект узла приложения .

dotnet add package Aspire.Hosting.Orleans

<PackageReference Include="Aspire.Hosting.Orleans"
                  Version="*" />

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

Добавьте ресурс Orleans

В проекте узла приложения вызовите AddOrleans, чтобы добавить и вернуть построитель ресурсов службы Orleans. Имя, предоставленное ресурсу Orleans, предназначено для диагностики. Для большинства приложений достаточно значения "default".

var orleans = builder.AddOrleans("default")

Использование хранилища Azure для кластеризации таблиц и хранилища зерна

В приложении Orleans основной блок является . Зерна могут иметь устойчивые состояния. Вы должны хранить устойчивое состояние для зерна где-то. В приложении .NET.NET AspireAzure Blob Storage — это одно из возможных местоположений.

Orleans узлы регистрируются в базе данных и используют её для поиска друг друга и формирования кластера. Они хранят информацию о том, какие серверы являются членами каких силосов, в таблице базы данных. Для хранения этих сведений можно использовать реляционные базы данных или базы данных NoSQL. В приложении .NET.NET Aspire популярным вариантом хранения этой таблицы является Azure Table Storage.

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

dotnet add package Aspire.Hosting.Azure.Storage

<PackageReference Include="Aspire.Hosting.Azure.Storage"
                  Version="*" />

В проекте узла приложения после вызова AddOrleansнастройте ресурс 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 в хост приложения

Теперь вы можете добавить новый проект, участвующий в оркестрации .NET Aspire, в ваше решение как сервер Orleans. Он примет участие в кластере Orleans в качестве силоса из составных зерен. Сошлитесь на ресурс Orleans из вашего проекта сервера, используя WithReference(orleans). При обращении к ресурсу Orleans из вашей службы, также используются следующие ресурсы:

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

Добавить клиентский проект Orleans в узел приложения

Orleans клиенты взаимодействуют с зернами, размещенными на серверах Orleans. Например, в приложении .NET Aspire может быть внешний веб-сайт, который вызывает зерна в кластере Orleans. Обратитесь к ресурсу Orleans из клиента Orleans, используя 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);

Создание проекта сервера Orleans

После завершения проекта узла приложения можно реализовать серверный проект Orleans. Начнем с добавления необходимых пакетов NuGet:

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

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />
<PackageReference Include="Aspire.Azure.Storage.Blobs"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Persistence.AzureStorage"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Clustering.AzureStorage"
                  Version="*" />

Затем в Program.cs файле проекта сервера Orleans добавьте Azure blob-объект хранилища и клиенты таблиц, а затем вызовите UseOrleans.

var builder = WebApplication.CreateBuilder(args);

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

Следующий код является полным примером проекта сервера Orleans, включая зерно с именем 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;
    }
}

Создание клиентского проекта Orleans

В клиентском проекте Orleans добавьте те же пакеты 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

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />
<PackageReference Include="Aspire.Azure.Storage.Blobs"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Persistence.AzureStorage"
                  Version="*" />
<PackageReference Include="Microsoft.Orleans.Clustering.AzureStorage"
                  Version="*" />

Затем в файле Program.cs клиентского проекта Orleans добавьте клиент хранилища таблиц Azure и вызовите UseOrleansClient.

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

Следующий код является полным примером клиентского проекта Orleans. Это вызывает зерно CounterGrain, определенное в приведенном выше примере сервера 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();

Включение OpenTelemetry

По соглашению .NET.NET Aspire решения включают проект для определения конфигурации и поведения по умолчанию для вашей службы. Этот проект называется проектом Service Defaults, и шаблоны создают его с названием, заканчивающимся на ServiceDefaults. Чтобы настроить Orleans для OpenTelemetry в .NET Aspire, примените конфигурацию к проекту службы по умолчанию, следуя руководству Orleans обсервабельности.

Измените метод 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.

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