Integrazione Orleans e .NET Aspire

.NET Aspire offre un approccio semplificato alla creazione di applicazioni native del cloud con supporto predefinito per Orleans. A partire da Orleans 8.0, è possibile usare Aspire per orchestrare il cluster Orleans, gestire le risorse di backup (ad esempio Redis o Archiviazione di Azure) e configurare automaticamente l'individuazione del servizio, l'osservabilità e i controlli di integrità.

Informazioni generali

Orleans l'integrazione con .NET Aspire usa il pacchetto Aspire.Hosting.Orleans nel progetto AppHost. Questo pacchetto fornisce metodi di estensione per:

• Definire Orleans come risorsa distribuita
• Configurare i provider di clustering (Redis, Archiviazione di Azure, ADO.NET)
• Configurare provider di archiviazione del grano
• Configurare i provider di promemoria
• Configurare provider di directory granulari
• Relazioni tra i silos e i client di un modello

Prerequisiti

Prima di usare Orleans con Aspire, assicurarsi di avere:

• .NET 8.0 SDK o versione successiva
• carico di lavoro .NET Aspire
• IDE con supporto Aspire (Visual Studio 2022 17.9+, VS Code con C# Dev Kit o JetBrains Rider)

Pacchetti obbligatori

Per la soluzione sono necessari i riferimenti ai pacchetti seguenti:

Progetto 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 progetto silo

<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 progetto cliente (se separato dal silo)

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

Configurare l'AppHost

Il progetto AppHost orchestra il Orleans cluster e le relative dipendenze.

Cluster di base Orleans con il clustering di 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 con stoccaggio di cereali e promemoria

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

Separare i progetti silo e client

Quando il Orleans client viene eseguito in un processo separato (ad esempio un frontend web), usare il .AsClient() metodo:

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

Configurare il Orleans progetto silo

Nel progetto silo, configurare Orleans per usare le risorse Aspire fornite:

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

Configurare con una stringa di connessione esplicita

Se è necessario un controllo esplicito sulla stringa di connessione, è possibile leggerlo dalla configurazione:

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

Configurare il progetto del Orleans client

Per progetti client separati, configurare il Orleans client in modo analogo:

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

Informazioni di riferimento su metodi di estensione AppHost

Il Aspire.Hosting.Orleans pacchetto fornisce questi metodi di estensione:

Metodi di base

Clustering

Archiviazione granulare

Promemoria

Trasmissione in diretta

Elenco cereali

Modello di impostazioni predefinite del servizio

Aspire usa un modello di progetto ServiceDefaults per condividere la configurazione comune in tutti i progetti. Per Orleans, solitamente si include:

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

Archiviazione di Azure con Aspire

È possibile usare le risorse di Archiviazione di Azure per Orleans il clustering e la persistenza:

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

Sviluppo e configurazione di produzione

Aspire semplifica il passaggio tra configurazioni di sviluppo e produzione:

Sviluppo locale (uso di emulatori)

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

    // ...
}

Produzione (uso di servizi gestiti)

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

    // ...
}

Controlli di salute

Aspire configura automaticamente gli endpoint di controllo integrità. È possibile aggiungere Orleanscontrolli di integrità specifici:

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

Procedure consigliate

1. Usare ServiceDefaults: condividere la configurazione comune (OpenTelemetry, controlli di integrità) in tutti i progetti usando un progetto ServiceDefaults.

2. Attendere le dipendenze: usare .WaitFor() sempre per assicurarsi che le risorse di backup (Redis, database) siano pronte prima dell'avvio Orleans dei silo.

3. Configurare le repliche: usare .WithReplicas() per eseguire più istanze di silo per la tolleranza di errore e la scalabilità.

4. Progetti client separati: per i front-end Web, usare .AsClient() per configurare la Orleans modalità solo client.

5. Usare gli emulatori per lo sviluppo: Aspire può eseguire Redis, Archiviazione di Azure (Azurite) e altre dipendenze in locale usando i contenitori.

6. Abilitare la traccia distribuita: configurare OpenTelemetry con Orleans i nomi di origine per tracciare le chiamate granulari nel cluster.

Vedere anche

• panoramica di .NET Aspire
• .NET Aspire configurazione e strumenti
• Orleans guida alla configurazione
• Orleans Fornitori Redis
• Orleans Provider di archiviazione di Azure

L'integrazione di .NET Aspire è stata introdotta in Orleans 8.0. Per Orleans 7.0, puoi comunque effettuare il deploy in ambienti orchestrati da Aspire, ma il pacchetto dedicato Aspire.Hosting.Orleans e i relativi metodi di estensione non sono disponibili.

Prendere in considerazione l'aggiornamento alla Orleans versione 8.0 o successiva per sfruttare le Aspire funzionalità di integrazione.

L'integrazione di .NET Aspire è disponibile in Orleans 8.0 e versioni successive. Orleans 3.x non supporta .NET Aspire.