integracja Orleans i .NET Aspire

.NET Aspire zapewnia uproszczone podejście do tworzenia aplikacji natywnych dla chmury z wbudowaną obsługą Orleans. Począwszy od Orleans 8.0, można użyć Aspire do organizowania klastra Orleans, zarządzania zasobami zapasowymi (takimi jak Redis lub Azure Storage) i automatycznego konfigurowania odnajdywania, obserwacji i kontroli kondycji usług.

Przegląd

Orleans Integracja z .NET Aspire korzysta z pakietu Aspire.Hosting.Orleans w projekcie AppHost. Ten pakiet udostępnia metody rozszerzeń:

  • Definiowanie Orleans jako zasób rozproszony
  • Konfigurowanie dostawców klastrowania (Redis, Azure Storage, ADO.NET)
  • Konfigurowanie dostawców magazynu ziarna
  • Konfigurowanie dostawców przypomnień
  • Konfigurowanie dostawców katalogów ziarna
  • Model silosu i relacje z klientami

Wymagania wstępne

Przed rozpoczęciem korzystania z Orleans i Aspire upewnij się, że masz:

Wymagane pakiety

Twoje rozwiązanie wymaga następujących referencji do pakietów.

Projekt AppHost

<ItemGroup>
  <PackageReference Include="Aspire.Hosting.AppHost" Version="13.1.3" />
  <PackageReference Include="Aspire.Hosting.Orleans" Version="13.1.3" />
  <PackageReference Include="Aspire.Hosting.Redis" Version="13.1.3" />
</ItemGroup>

Orleans Projekt silosu

<ItemGroup>
  <PackageReference Include="Microsoft.Orleans.Server" Version="10.1.0" />
  <PackageReference Include="Microsoft.Orleans.Clustering.Redis" Version="10.1.0" />
  <PackageReference Include="Aspire.StackExchange.Redis" Version="13.2.4" />
</ItemGroup>

Orleans projekt klienta (jeśli jest oddzielny od silosu)

<ItemGroup>
  <PackageReference Include="Microsoft.Orleans.Client" Version="10.1.0" />
  <PackageReference Include="Microsoft.Orleans.Clustering.Redis" Version="10.1.0" />
  <PackageReference Include="Aspire.StackExchange.Redis" Version="13.2.4" />
</ItemGroup>

Konfigurowanie hosta AppHost

Projekt AppHost organizuje Orleans klaster i jego zależności.

Klaster podstawowy Orleans z klastrowaniem Redis

public static void BasicOrleansCluster(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    // Add Redis for Orleans clustering
    var redis = builder.AddRedis("orleans-redis");

    // Define the Orleans resource with Redis clustering
    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis);

    // Add the Orleans silo project
    builder.AddProject<Projects.Silo>("silo")
        .WithReference(orleans)
        .WaitFor(redis)
        .WithReplicas(3);

    builder.Build().Run();
}

Orleans z przechowywaniem ziarna i przypomnieniami

public static void OrleansWithStorageAndReminders(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    var redis = builder.AddRedis("orleans-redis");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis)
        .WithGrainStorage("Default", redis)
        .WithGrainStorage("PubSubStore", redis)
        .WithReminders(redis);

    builder.AddProject<Projects.Silo>("silo")
        .WithReference(orleans)
        .WaitFor(redis)
        .WithReplicas(3);

    builder.Build().Run();
}

Oddzielne projekty silosu i klienta

Orleans Gdy klient jest uruchamiany w osobnym procesie (takim jak frontend internetowy), użyj metody .AsClient():

public static void SeparateSiloAndClient(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    var redis = builder.AddRedis("orleans-redis");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis)
        .WithGrainStorage("Default", redis);

    // Backend Orleans silo cluster
    var silo = builder.AddProject<Projects.Silo>("backend")
        .WithReference(orleans)
        .WaitFor(redis)
        .WithReplicas(5);

    // Frontend web project as Orleans client
    builder.AddProject<Projects.Client>("frontend")
        .WithReference(orleans.AsClient())  // Client-only reference
        .WaitFor(silo);

    builder.Build().Run();
}

Konfigurowanie projektu silosu Orleans

Orleans W projekcie silosu skonfiguruj Orleans, aby używać zasobów udostępnionych przez Aspire:

public static void BasicSiloConfiguration(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    // Add Aspire service defaults (OpenTelemetry, health checks, etc.)
    builder.AddServiceDefaults();

    // Add the Aspire Redis client for Orleans
    builder.AddKeyedRedisClient("orleans-redis");

    // Configure Orleans - Aspire injects all configuration automatically
    builder.UseOrleans();

    builder.Build().Run();
}

Wskazówka

W przypadku korzystania z .NET Aspire zazwyczaj wystarczy UseOrleans bez parametrów. Aspire Orleans wprowadza konfigurację (identyfikator klastra, identyfikator usługi, punkty końcowe i ustawienia dostawcy) za pośrednictwem zmiennych środowiskowych, które Orleans są odczytywane automatycznie. Przeciążenie UseOrleans(siloBuilder => {...}) delegata jest potrzebne tylko wtedy, gdy wymagana jest dodatkowa ręczna konfiguracja oprócz tej, którą Aspire zapewnia.

Ważne

Należy wywołać odpowiednią metodę AddKeyed* (taką jak AddKeyedRedisClient, AddKeyedAzureTableClient lub AddKeyedAzureBlobClient), aby zarejestrować zasób wspierający w kontenerze wstrzykiwania zależności. Orleans dostawcy wyszukują zasoby według nazwy usługi określonej kluczem — jeśli pominiesz ten krok, Orleans nie będzie w stanie rozpoznać zasobu i wygeneruje błąd rozwiązywania zależności w czasie wykonywania. Dotyczy to wszystkich Aspirezasobów zarządzanych używanych z Orleansprogramem .

Konfigurowanie przy użyciu jawnych parametrów połączenia

Jeśli potrzebujesz bezpośredniej kontroli nad łańcuchem połączenia, możesz je odczytać z konfiguracji.

public static void ExplicitConnectionConfiguration(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    builder.AddServiceDefaults();
    builder.AddKeyedRedisClient("orleans-redis");

    builder.UseOrleans(siloBuilder =>
    {
        var redisConnectionString = builder.Configuration.GetConnectionString("orleans-redis");

        siloBuilder.UseRedisClustering(options =>
        {
            options.ConfigurationOptions =
                ConfigurationOptions.Parse(redisConnectionString!);
        });

        siloBuilder.AddRedisGrainStorageAsDefault(options =>
        {
            options.ConfigurationOptions =
                ConfigurationOptions.Parse(redisConnectionString!);
        });
    });

    builder.Build().Run();
}

Orleans Konfigurowanie projektu klienta

W przypadku oddzielnych projektów klienckich skonfiguruj klienta Orleans w podobny sposób:

public static void BasicClientConfiguration(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    builder.AddServiceDefaults();
    builder.AddKeyedRedisClient("orleans-redis");

    // Configure Orleans client - Aspire injects clustering configuration automatically
    builder.UseOrleansClient();

    builder.Build().Run();
}

Dokumentacja metod rozszerzenia AppHost

Pakiet Aspire.Hosting.Orleans udostępnia następujące metody rozszerzenia:

Podstawowe metody

Metoda Description
builder.AddOrleans(name) Orleans Dodaje zasób do aplikacji rozproszonej o określonej nazwie.
.WithClusterId(id) Ustawia identyfikator Orleans ClusterId. Akceptuje ciąg lub ParameterResource. Jeśli nie zostanie określony, unikatowy identyfikator zostanie wygenerowany automatycznie.
.WithServiceId(id) Ustawia identyfikator Orleans ServiceId. Akceptuje ciąg lub ParameterResource. Jeśli nie zostanie określony, unikatowy identyfikator zostanie wygenerowany automatycznie.
.AsClient() Zwraca referencję klienta do zasobu Orleans (nie uwzględniając funkcji silosu).
project.WithReference(orleans) Dodaje odniesienie do zasobu Orleans w projekcie, umożliwiając wstrzykiwanie konfiguracji.

Uwaga / Notatka

Podczas konfigurowania zasobu pomocniczego przy użyciu metod .WithClustering(resource), .WithGrainStorage(name, resource) lub podobnych metod, zasób Orleans automatycznie odnosi się do tego zasobu pomocniczego. Nie musisz wywoływać .WithReference() oddzielnie dla każdego zasobu zastępczego — wymagane jest tylko .WithReference(orleans). Jednak należy użyć .WaitFor() na zasobie wspomagającym, aby upewnić się, że jest gotowy, zanim silos się uruchomi.

Clustering

Metoda Description
.WithClustering(resource) Konfiguruje Orleans klastrowanie do używania określonego zasobu (Redis, Azure Storage, Cosmos DB itp.).
.WithDevelopmentClustering() Konfiguruje klastrowanie w pamięci z jednym hostem tylko na potrzeby programowania lokalnego. Nie nadaje się do produkcji.

Magazyn ziarna

Metoda Description
.WithGrainStorage(name, resource) Konfiguruje nazwanego dostawcę magazynu ziarna przy użyciu określonego zasobu.
.WithMemoryGrainStorage(name) Konfiguruje magazyn ziarna w pamięci dla określonej nazwy. Dane zostaną utracone po ponownym uruchomieniu silosu.

Przypomnienia

Metoda Description
.WithReminders(resource) Konfiguruje usługę Orleans przypomnienia przy użyciu określonego zasobu.
.WithMemoryReminders() Konfiguruje przypomnienia w pamięci na potrzeby programowania. Przypomnienia są tracone po ponownym uruchomieniu silosu.

Streaming

Metoda Description
.WithStreaming(name, resource) Konfiguruje nazwanego dostawcę strumienia przy użyciu określonego zasobu (np. usługi Azure Queue Storage).
.WithMemoryStreaming(name) Konfiguruje przesyłanie strumieniowe w pamięci na potrzeby programowania.
.WithBroadcastChannel(name) Konfiguruje dostawcę kanału emisji o określonej nazwie.

Katalog ziarna

Metoda Description
.WithGrainDirectory(name, resource) Konfiguruje nazwany katalog ziarna przy użyciu określonego zasobu.

Wzorzec domyślnej sekwencji usług

Aspire Używa wzorca projektu ServiceDefaults do współużytkowania wspólnej konfiguracji we wszystkich projektach. W przypadku Orleans zazwyczaj obejmuje to następujące elementy:

Konfiguracja openTelemetry

public static IHostApplicationBuilder AddServiceDefaults(
    this IHostApplicationBuilder builder)
{
    builder.ConfigureOpenTelemetry();
    builder.AddDefaultHealthChecks();
    
    return builder;
}

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");  // Orleans metrics
        })
        .WithTracing(tracing =>
        {
            tracing.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddSource("Microsoft.Orleans.Runtime")
                .AddSource("Microsoft.Orleans.Application");
        });

    return builder;
}

Azure Storage z Aspire

Zasoby usługi Azure Storage można używać do Orleans klastrowania i trwałości:

public static void AzureStorageWithAspire(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    // Add Azure Storage for Orleans
    var storage = builder.AddAzureStorage("orleans-storage")
        .RunAsEmulator();  // Use Azurite emulator for local development

    var tables = storage.AddTables("orleans-tables");
    var blobs = storage.AddBlobs("orleans-blobs");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(tables)
        .WithGrainStorage("Default", blobs)
        .WithReminders(tables);

    builder.AddProject<Projects.Silo>("silo")
        .WithReference(orleans)
        .WaitFor(storage)
        .WithReplicas(3);

    builder.Build().Run();
}

Programowanie a konfiguracja produkcyjna

Aspire ułatwia przełączanie między konfiguracjami programistycznymi i produkcyjnymi:

Programowanie lokalne (przy użyciu emulatorów)

public static void LocalDevelopment(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    var redis = builder.AddRedis("orleans-redis");
    // Redis container runs automatically during development

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis);

    // ...
}

Produkcja (przy użyciu usług zarządzanych)

public static void ProductionConfig(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    // Use existing Azure Cache for Redis
    var redis = builder.AddConnectionString("orleans-redis");

    var orleans = builder.AddOrleans("cluster")
        .WithClustering(redis);

    // ...
}

Kontrole kondycji

Aspire automatycznie konfiguruje punkty końcowe sprawdzania kondycji. Możesz dodać kontrole stanu zdrowia specyficzne dla Orleans:

public static void ConfigureHealthChecks(IHostApplicationBuilder builder)
{
    builder.Services.AddHealthChecks()
        .AddCheck<GrainHealthCheck>("orleans-grains")
        .AddCheck<SiloHealthCheck>("orleans-silo");
}

Najlepsze rozwiązania

  1. Use ServiceDefaults: Udostępniaj wspólne konfiguracje (OpenTelemetry, health checks) we wszystkich projektach poprzez projekt ServiceDefaults.

  2. Poczekaj na zależności: zawsze używaj .WaitFor(), aby zapewnić, że zasoby wspierające (Redis, bazy danych) są gotowe przed Orleans rozpoczęciem pracy silosów.

  3. Skonfiguruj repliki: Użyj .WithReplicas(), aby uruchomić wiele wystąpień silosu w celu zapewnienia odporności na awarie i skalowalności.

  4. Oddzielne projekty klienckie: w przypadku frontonów internetowych użyj polecenia .AsClient() , aby skonfigurować Orleans tryb tylko dla klienta.

  5. Użyj emulatory do programowania: Aspire można uruchamiać usługę Redis, Azure Storage (Azurite) i inne zależności lokalnie przy użyciu kontenerów.

  6. Włącz śledzenie rozproszone: skonfiguruj metodę OpenTelemetry z nazwami źródłowymi Orleans w celu śledzenia wywołań ziarna w klastrze.

Zobacz także

Integracja .NET Aspire została wprowadzona w Orleans 8.0. W wersji Orleans 7.0 można nadal wdrażać w Aspireśrodowiskach orkiestrowanych, ale dedykowany Aspire.Hosting.Orleans pakiet i jego metody rozszerzenia nie są dostępne.

Rozważ uaktualnienie do Orleans wersji 8.0 lub nowszej Aspire , aby skorzystać z funkcji integracji.

.NET Aspire integracja jest dostępna w Orleans 8.0 i nowszych. Orleans 3.x nie obsługuje .NET Aspire.

  • Last updated on