Partager via

Configurer le serveur

Configurez un silo par programmation à l’aide de la UseOrleans(IHostBuilder, Action<HostBuilderContext,ISiloBuilder>) méthode d’extension et de plusieurs classes d’options supplémentaires. Les classes d’options dans Orleans suivent le modèle Options de .NET et peuvent être chargées à partir de fichiers, de variables d’environnement ou de tout autre fournisseur de configuration valide.

Il existe plusieurs aspects clés de la configuration du silo :

  • Fournisseur de clustering
  • (Facultatif) Orleans Informations de clustering
  • (Facultatif) Points de terminaison pour les communications de silo à silo et de client à silo

Cet exemple montre une configuration de silo définissant des informations de cluster, à l’aide du clustering Azure et à la configuration des parties d’application :

using IHost host = Host.CreateDefaultBuilder(args)
    .UseOrleans(builder =>
    {
        builder.UseAzureStorageClustering(
            options => options.ConfigureTableServiceClient(connectionString));
    })
    .UseConsoleLifetime()
    .Build();

Conseil / Astuce

Lors du développement pour Orleans, vous pouvez appeler UseLocalhostClustering(ISiloBuilder, Int32, Int32, IPEndPoint, String, String) pour configurer un cluster local. Dans les environnements de production, vous devez utiliser un fournisseur de clustering adapté à votre déploiement.

Fournisseur de clustering

siloBuilder.UseAzureStorageClustering(
    options => options.ConfigureTableServiceClient(connectionString))

En règle générale, vous déployez un service basé sur Orleans un cluster de nœuds, sur du matériel dédié ou dans le cloud. Pour le développement et les tests de base, vous pouvez déployer Orleans dans une configuration à nœud unique. Lorsqu’il est déployé sur un cluster de nœuds, Orleans implémente en interne des protocoles pour découvrir et gérer l’appartenance à des Orleans silos dans le cluster, notamment la détection des défaillances de nœud et la reconfiguration automatique.

Pour une gestion fiable de l’appartenance au cluster, Orleans utilisez La table Azure, SQL Server ou Apache ZooKeeper pour la synchronisation de nœuds.

Dans cet exemple, nous utilisons Azure Table comme fournisseur d'adhésion.

Orleans Information de regroupement

Pour configurer optionnellement le clustering, utilisez ClusterOptions comme paramètre de type pour la méthode Configure sur l'instance ISiloBuilder.

siloBuilder.Configure<ClusterOptions>(options =>
{
    options.ClusterId = "my-first-cluster";
    options.ServiceId = "SampleApp";
})

Ici, vous spécifiez deux options :

  • Définissez la ClusterId à "my-first-cluster" : Il s'agit d'un ID unique pour le cluster Orleans. Tous les clients et silos utilisant cet ID peuvent communiquer directement entre eux. Toutefois, vous pouvez choisir d’utiliser une autre ClusterId option pour différents déploiements.
  • Définissez la valeur ServiceId à "SampleApp" : il s'agit d'un ID unique pour votre application utilisé par certains fournisseurs, tels que les fournisseurs de persistance. Cet ID doit rester stable et ne pas changer entre les déploiements.

Par défaut, Orleans utilise "default" à la fois pour les deux ServiceId et ClusterId. Ces valeurs n’ont pas besoin de changer dans la plupart des cas. ServiceId est plus significatif et distingue différents services logiques, ce qui leur permet de partager des systèmes de stockage back-end sans interférence. ClusterId détermine les hôtes qui se connectent pour former un cluster.

Au sein de chaque cluster, tous les hôtes doivent utiliser le même ServiceId. Toutefois, plusieurs clusters peuvent partager un ServiceId. Cela permet des scénarios de déploiement bleu/vert où vous démarrez un nouveau déploiement (cluster) avant d’arrêter une autre. Il s’agit généralement des systèmes hébergés dans Azure App Service.

Le cas le plus courant est que ServiceId et ClusterId restent fixes pour la durée de vie de l'application, et que vous utilisez une stratégie de déploiement progressive. Il s’agit généralement des systèmes hébergés dans Kubernetes et Service Fabric.

Points de terminaison

Par défaut, Orleans écoute toutes les interfaces sur le port 11111 pour la communication silo-à-silo et le port 30000 pour la communication client-à-silo. Pour remplacer ce comportement, appelez ConfigureEndpoints(ISiloBuilder, Int32, Int32, AddressFamily, Boolean) et transmettez les numéros de port que vous souhaitez utiliser.

siloBuilder.ConfigureEndpoints(siloPort: 17_256, gatewayPort: 34_512)

Dans le code précédent :

  • Le port de silo est défini sur 17_256.
  • Le port de passerelle est défini sur 34_512.

Un Orleans silo a deux types typiques de configuration de point de terminaison :

  • Points de terminaison de silo à silo : utilisés pour la communication entre les silos du même cluster.
  • Points de terminaison de client à silo (ou passerelle) : utilisé pour la communication entre les clients et les silos dans le même cluster.

Cette méthode doit suffire dans la plupart des cas, mais vous pouvez la personnaliser davantage si nécessaire. Voici un exemple d’utilisation d’une adresse IP externe avec transfert de port :

siloBuilder.Configure<EndpointOptions>(options =>
{
    // Port to use for silo-to-silo
    options.SiloPort = 11_111;
    // Port to use for the gateway
    options.GatewayPort = 30_000;
    // IP Address to advertise in the cluster
    options.AdvertisedIPAddress = IPAddress.Parse("172.16.0.42");
    // The socket used for client-to-silo will bind to this endpoint
    options.GatewayListeningEndpoint = new IPEndPoint(IPAddress.Any, 40_000);
    // The socket used by the gateway will bind to this endpoint
    options.SiloListeningEndpoint = new IPEndPoint(IPAddress.Any, 50_000);
})

En interne, le silo écoute 0.0.0.0:40000 et 0.0.0.0:50000, mais la valeur publiée dans le fournisseur d’appartenances est 172.16.0.42:11111 et 172.16.0.42:30000.

Configurez un silo par programmation via SiloHostBuilder et plusieurs classes d’options supplémentaires. Les classes d’options dans Orleans suivent le modèle Options de .NET et peuvent être chargées à partir de fichiers, de variables d’environnement ou de tout autre fournisseur de configuration valide.

Il existe plusieurs aspects clés de la configuration du silo :

  • Orleans Information de regroupement
  • Fournisseur de clustering
  • Points de terminaison pour les communications de silo à silo et de client à silo
  • Composants d’application

Cet exemple montre une configuration de silo définissant des informations de cluster, à l’aide du clustering Azure et à la configuration des parties d’application :

var silo = Host.CreateDefaultBuilder(args)
    .UseOrleans(builder =>
    {
        builder
            .UseAzureStorageClustering(
                options => options.ConnectionString = connectionString)
            .Configure<ClusterOptions>(options =>
            {
                options.ClusterId = "my-first-cluster";
                options.ServiceId = "AspNetSampleApp";
            })
            .ConfigureEndpoints(siloPort: 11111, gatewayPort: 30000)
            .ConfigureApplicationParts(
                parts => parts.AddApplicationPart(typeof(ValueGrain).Assembly).WithReferences())
    })
    .UseConsoleLifetime()
    .Build();

Nous allons décomposer les étapes utilisées dans cet exemple :

Fournisseur de clustering

siloBuilder.UseAzureStorageClustering(
    options => options.ConnectionString = connectionString)

En règle générale, vous déployez un service basé sur Orleans un cluster de nœuds, sur du matériel dédié ou dans le cloud. Pour le développement et les tests de base, vous pouvez déployer Orleans dans une configuration à nœud unique. Lorsqu’il est déployé sur un cluster de nœuds, Orleans implémente en interne des protocoles pour découvrir et gérer l’appartenance à des Orleans silos dans le cluster, notamment la détection des défaillances de nœud et la reconfiguration automatique.

Pour une gestion fiable de l’appartenance au cluster, Orleans utilisez La table Azure, SQL Server ou Apache ZooKeeper pour la synchronisation de nœuds.

Dans cet exemple, nous utilisons Azure Table comme fournisseur d'adhésion.

Orleans Information de regroupement

.Configure<ClusterOptions>(options =>
{
    options.ClusterId = "my-first-cluster";
    options.ServiceId = "AspNetSampleApp";
})

Ici, nous faisons deux choses :

  • Définissez la ClusterId à "my-first-cluster" : Il s'agit d'un ID unique pour le cluster Orleans. Tous les clients et silos utilisant cet ID peuvent communiquer directement entre eux. Toutefois, vous pouvez choisir d’utiliser une autre ClusterId option pour différents déploiements.
  • Définissez la valeur ServiceId à "AspNetSampleApp" : il s'agit d'un ID unique pour votre application utilisé par certains fournisseurs, tels que les fournisseurs de persistance. Cet ID doit rester stable et ne pas changer entre les déploiements.

Par défaut, Orleans utilise "default" à la fois pour les deux ServiceId et ClusterId. Ces valeurs n’ont pas besoin de changer dans la plupart des cas. ServiceId est plus significatif et distingue différents services logiques, ce qui leur permet de partager des systèmes de stockage back-end sans interférence. ClusterId détermine les hôtes qui se connectent pour former un cluster.

Au sein de chaque cluster, tous les hôtes doivent utiliser le même ServiceId. Toutefois, plusieurs clusters peuvent partager un ServiceId. Cela permet des scénarios de déploiement bleu/vert où vous démarrez un nouveau déploiement (cluster) avant d’arrêter une autre. Il s’agit généralement des systèmes hébergés dans Azure App Service.

Le cas le plus courant est que ServiceId et ClusterId restent fixes pour la durée de vie de l'application, et que vous utilisez une stratégie de déploiement progressive. Il s’agit généralement des systèmes hébergés dans Kubernetes et Service Fabric.

Points de terminaison

siloBuilder.ConfigureEndpoints(siloPort: 11111, gatewayPort: 30000)

Un Orleans silo a deux types typiques de configuration de point de terminaison :

  • Points de terminaison de silo à silo : utilisés pour la communication entre les silos du même cluster.
  • Points de terminaison de client à silo (ou passerelle) : utilisé pour la communication entre les clients et les silos dans le même cluster.

Dans l’exemple, nous utilisons la méthode d’assistance .ConfigureEndpoints(siloPort: 11111, gatewayPort: 30000), qui définit le port pour la communication de silo à silo à 11111 et le port de passerelle à 30000. Cette méthode détecte sur quelle interface écouter.

Cette méthode doit suffire dans la plupart des cas, mais vous pouvez la personnaliser davantage si nécessaire. Voici un exemple d’utilisation d’une adresse IP externe avec transfert de port :

siloBuilder.Configure<EndpointOptions>(options =>
{
    // Port to use for silo-to-silo
    options.SiloPort = 11111;
    // Port to use for the gateway
    options.GatewayPort = 30000;
    // IP Address to advertise in the cluster
    options.AdvertisedIPAddress = IPAddress.Parse("172.16.0.42");
    // The socket used for client-to-silo will bind to this endpoint
    options.GatewayListeningEndpoint = new IPEndPoint(IPAddress.Any, 40000);
    // The socket used by the gateway will bind to this endpoint
    options.SiloListeningEndpoint = new IPEndPoint(IPAddress.Any, 50000);
})

En interne, le silo écoute 0.0.0.0:40000 et 0.0.0.0:50000, mais la valeur publiée dans le fournisseur d’appartenances est 172.16.0.42:11111 et 172.16.0.42:30000.

Composants d’application

siloBuilder.ConfigureApplicationParts(
    parts => parts.AddApplicationPart(
        typeof(ValueGrain).Assembly)
        .WithReferences())

Bien que cette étape ne soit pas techniquement requise (si elle n’est pas configurée, Orleans analyse tous les assemblys dans le dossier actif), nous vous encourageons à le configurer. Cette étape permet de Orleans charger des assemblys et des types utilisateur. Ces assemblages sont appelés parties de l'application. Orleans découvre tous les grains, interfaces de grain et sérialiseurs à l’aide des Composants d’Application.

Configurez les parties de l'application à l'aide de IApplicationPartManager, accessibles via la méthode d'extension ConfigureApplicationParts sur IClientBuilder et ISiloHostBuilder. La ConfigureApplicationParts méthode accepte un délégué. Action<IApplicationPartManager>

Les méthodes d'extension suivantes sur IApplicationPartManager apportent un soutien aux utilisations courantes :

Compléter les assemblages ajoutés par les méthodes ci-dessus à l’aide des méthodes d’extension suivantes sur leur type de retour : IApplicationPartManagerWithAssemblies

  • ApplicationPartManagerExtensions.WithReferences: ajoute tous les assemblys référencés des composants ajoutés. Cela charge immédiatement tous les assemblies référencés transitivement. Les erreurs de chargement d’assembly sont ignorées.
  • ApplicationPartManagerCodeGenExtensions.WithCodeGeneration: génère le code de prise en charge des composants ajoutés et l’ajoute au gestionnaire de composants. Notez que cela nécessite l’installation du Microsoft.Orleans.OrleansCodeGenerator package et est généralement appelée génération de code runtime.

La découverte de types nécessite que les composants ApplicationPart fournis incluent des attributs spécifiques. L’ajout du package de génération de code au moment de la build (Microsoft.Orleans.CodeGenerator.MSBuild ou Microsoft.Orleans.OrleansCodeGenerator.Build) à chaque projet contenant des grains, des interfaces grain ou des sérialiseurs est l’approche recommandée pour garantir que ces attributs sont présents. La génération de code pendant la compilation ne prend en charge que C#. Pour F#, Visual Basic et d’autres langages .NET, vous pouvez générer du code pendant le temps de configuration via la WithCodeGeneration méthode décrite ci-dessus. Pour plus d’informations sur la génération de code, consultez la section correspondante.