Compartir a través de

Orleans y la integración con .NET Aspire

.NET Aspire proporciona un enfoque simplificado para crear aplicaciones nativas de la nube con compatibilidad integrada con Orleans. Orleans A partir de la versión 8.0, puede usar Aspire para organizar el Orleans clúster, administrar recursos de respaldo (como Redis o Azure Storage) y configurar automáticamente la detección, observabilidad y comprobaciones de estado del servicio.

Información general

Orleans La integración con .NET Aspire utiliza el paquete en su proyecto AppHost Aspire.Hosting.Orleans. Este paquete proporciona métodos de extensión para:

  • Definir Orleans como un recurso distribuido
  • Configuración de proveedores de agrupación en clústeres (Redis, Azure Storage, ADO.NET)
  • Configurar proveedores de almacenamiento de granos
  • Configuración de proveedores de recordatorios
  • Configuración de proveedores de directorios granulares
  • Silo de modelo y relaciones con clientes

Prerrequisitos

Antes de usar Orleans con Aspire, asegúrese de que tiene:

Paquetes necesarios

La solución necesita las siguientes referencias de paquete:

Proyecto appHost

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

Orleans proyecto de silo

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

Orleans proyecto cliente (si es independiente del silo)

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

Configuración de AppHost

El proyecto AppHost organiza el Orleans clúster y sus dependencias.

Clúster básico Orleans con agrupación en clústeres de 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 almacenamiento de grano y recordatorios

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

Separar proyectos de silo y cliente

Cuando el Orleans cliente se ejecute en un proceso independiente (por ejemplo, una interfaz web), use el método .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();
}

Configuración del Orleans proyecto de silo

En el Orleans proyecto de silo, configure Orleans para usar los recursos proporcionados por 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();
}

Sugerencia

Cuando se usa .NET Aspire, el uso del UseOrleans sin parámetros suele ser todo lo que necesita. Aspire inserta Orleans la configuración (identificador de clúster, identificador de servicio, puntos de conexión y configuración del proveedor) a través de variables de entorno que Orleans se leen automáticamente. Solo necesita la sobrecarga de delegado UseOrleans(siloBuilder => {...}) cuando requiera una configuración manual adicional además de lo que proporciona Aspire.

Importante

Debe llamar al método adecuado AddKeyed* (como AddKeyedRedisClient, AddKeyedAzureTableCliento AddKeyedAzureBlobClient) para registrar el recurso de respaldo en el contenedor de inserción de dependencias. Orleans los proveedores buscan recursos por su nombre de servicio con clave: si omite este paso, Orleans no podrá resolver el recurso y producirá un error de resolución de dependencias en tiempo de ejecución. Esto se aplica a todos los recursos administrados por Aspire usados con Orleans.

Configuración con una cadena de conexión explícita

Si necesita un control explícito sobre la cadena de conexión, puede leerla desde la configuración:

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

Configuración del Orleans proyecto de cliente

Para proyectos de cliente independientes, configure el Orleans cliente de forma similar:

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

Referencia de métodos de extensión de AppHost

El Aspire.Hosting.Orleans paquete proporciona estos métodos de extensión:

Métodos principales

Método Description
builder.AddOrleans(name) Agrega un Orleans recurso a la aplicación distribuida con el nombre especificado.
.WithClusterId(id) Establece el Orleans ClusterId. Acepta una cadena o ParameterResource. Si no se especifica, se genera automáticamente un identificador único.
.WithServiceId(id) Establece el ServiceId Orleans. Acepta una cadena o ParameterResource. Si no se especifica, se genera automáticamente un identificador único.
.AsClient() Devuelve una referencia exclusiva de cliente al recurso Orleans (no incluye funcionalidades de silo).
project.WithReference(orleans) Agrega la Orleans referencia de recursos a un proyecto, lo que habilita la inserción de configuración.

Nota:

Al configurar un recurso de respaldo mediante .WithClustering(resource), .WithGrainStorage(name, resource)o métodos similares, el Orleans recurso incluye automáticamente una referencia a ese recurso de respaldo. No es necesario llamar a .WithReference() por separado para cada recurso de respaldo; solo se requiere .WithReference(orleans). Sin embargo, debe usar .WaitFor() en el recurso de respaldo para asegurarse de que está listo antes de que se inicie el silo.

Clustering

Método Description
.WithClustering(resource) Configura la agrupación en clústeres Orleans para usar el recurso especificado (Redis, Azure Storage, Cosmos DB, etc.).
.WithDevelopmentClustering() Configura clúster de un solo host en memoria interna solo para desarrollo local. No son adecuadas para producción.

Almacenamiento de granos

Método Description
.WithGrainStorage(name, resource) Configura un proveedor de almacenamiento de grano con nombre utilizando el recurso especificado.
.WithMemoryGrainStorage(name) Configura el almacenamiento de granos en memoria para el nombre especificado. Los datos se pierden al reiniciar el silo.

Recordatorios

Método Description
.WithReminders(resource) Configura el servicio de recordatorio Orleans mediante el recurso especificado.
.WithMemoryReminders() Configura recordatorios en memoria interna para el desarrollo. Los recordatorios se pierden al reiniciar el silo.

Transmisión en línea

Método Description
.WithStreaming(name, resource) Configura un proveedor de flujos con nombre mediante el recurso especificado (por ejemplo, Azure Queue Storage).
.WithMemoryStreaming(name) Configura el streaming en memoria para el desarrollo.
.WithBroadcastChannel(name) Configura un proveedor de canales de difusión con el nombre especificado.

Directorio de granos

Método Description
.WithGrainDirectory(name, resource) Configura un directorio de grano con nombre mediante el recurso especificado.

Patrón de valores predeterminados del servicio

Aspire usa un patrón de proyecto ServiceDefaults para compartir la configuración común en todos los proyectos. Para Orleans, esto normalmente incluye:

Configuración de 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 con Aspire

Puede usar recursos de Azure Storage para la agrupación en clústeres y la Orleans persistencia:

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

Configuración de desarrollo frente a producción

Aspire facilita el cambio entre configuraciones de desarrollo y producción:

Desarrollo local (mediante emuladores)

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

    // ...
}

Producción (mediante servicios administrados)

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

    // ...
}

Exámenes de salud

Aspire configura automáticamente los puntos de conexión de comprobación de estado. Puede agregar comprobaciones de salud específicas de Orleans:

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

procedimientos recomendados

  1. Use ServiceDefaults: comparta la configuración común (OpenTelemetry, las comprobaciones de estado) en todos los proyectos mediante un proyecto ServiceDefaults.

  2. Espere a las dependencias: use .WaitFor() siempre para asegurarse de que los recursos de respaldo (Redis, bases de datos) estén listos antes de Orleans que se inicien los silos.

  3. Configurar réplicas: use .WithReplicas() para ejecutar varias instancias de silo para tolerancia a fallos y escalabilidad.

  4. Proyectos de cliente independientes: para front-end web, use .AsClient() para configurar Orleans el modo de solo cliente.

  5. Uso de emuladores para el desarrollo: Aspire puede ejecutar Redis, Azure Storage (Azurite) y otras dependencias localmente mediante contenedores.

  6. Habilitar el seguimiento distribuido: configure OpenTelemetry con Orleans nombres de origen para realizar un seguimiento de las llamadas específicas en el clúster.

Consulte también

La integración de .NET Aspire se introdujo en Orleans la versión 8.0. En Orleans 7.0, todavía puede implementar en entornos orquestados por Aspire, pero el paquete dedicado Aspire.Hosting.Orleans y sus métodos de extensión no están disponibles.

Considere la posibilidad de actualizar a Orleans la versión 8.0 o posterior para aprovechar las características de integración de Aspire.

La integración de .NET Aspire está disponible en Orleans 8.0 y posteriores. Orleans 3.x no admite .NET Aspire.

  • Last updated on