persistance des grains ADO.NET

2025-05-29

Le code principal de stockage relationnel s’appuie Orleans sur des fonctionnalités de ADO.NET génériques et est par conséquent indépendant du fournisseur de base de données. Configurez les chaînes de connexion comme expliqué dans le Orleans Guide de configuration.

Pour faire fonctionner le code Orleans avec un système de gestion de base de données relationnelle donné, il vous faut les éléments suivants :

Chargez la bibliothèque de ADO.NET appropriée dans le processus. Définissez cela comme d’habitude, par exemple via l’élément DbProviderFactories dans la configuration de l’application.
Configurez l’ADO.NET invariant via la Invariant propriété dans les options.
Vérifiez que la base de données existe et qu’elle est compatible avec le code. Pour ce faire, exécutez un script de création de base de données spécifique au fournisseur. Pour plus d’informations, consultez ADO.NET Configuration.

Le fournisseur de stockage des grains ADO.NET vous permet de stocker l’état des grains dans les bases de données relationnelles. Actuellement, les bases de données suivantes sont prises en charge :

Serveur SQL
MySQL/MariaDB
PostgreSQL
Oracle

Tout d’abord, installez le package de base :

Install-Package Microsoft.Orleans.Persistence.AdoNet

Lisez l’article de configuration ADO.NET pour plus d’informations sur la configuration de votre base de données, y compris les scripts d’ADO.NET invariants et d’installation correspondants.

L’exemple suivant montre comment configurer un fournisseur de stockage ADO.NET via ISiloHostBuilder:

var siloHostBuilder = new HostBuilder()
    .UseOrleans(c =>
    {
        c.AddAdoNetGrainStorage("OrleansStorage", options =>
        {
            options.Invariant = "<Invariant>";
            options.ConnectionString = "<ConnectionString>";
            options.UseJsonFormat = true;
        });
    });

Essentiellement, vous devez uniquement définir la chaîne de connexion spécifique au fournisseur de base de données et un Invariant (voir ADO.NET Configuration) identifiant le fournisseur. Vous pouvez également choisir le format d’enregistrement des données : binaire (par défaut), JSON ou XML. Bien que binaire soit l’option la plus compacte, elle est opaque et vous ne pourrez pas lire ou utiliser les données directement. JSON est l’option recommandée.

Vous pouvez définir les propriétés suivantes via AdoNetGrainStorageOptions:

/// <summary>
/// Options for AdoNetGrainStorage
/// </summary>
public class AdoNetGrainStorageOptions
{
    /// <summary>
    /// Define the property of the connection string
    /// for AdoNet storage.
    /// </summary>
    [Redact]
    public string ConnectionString { get; set; }

    /// <summary>
    /// Set the stage of the silo lifecycle where storage should
    /// be initialized.  Storage must be initialized prior to use.
    /// </summary>
    public int InitStage { get; set; } = DEFAULT_INIT_STAGE;
    /// <summary>
    /// Default init stage in silo lifecycle.
    /// </summary>
    public const int DEFAULT_INIT_STAGE =
        ServiceLifecycleStage.ApplicationServices;

    /// <summary>
    /// The default ADO.NET invariant will be used for
    /// storage if none is given.
    /// </summary>
    public const string DEFAULT_ADONET_INVARIANT =
        AdoNetInvariants.InvariantNameSqlServer;

    /// <summary>
    /// Define the invariant name for storage.
    /// </summary>
    public string Invariant { get; set; } =
        DEFAULT_ADONET_INVARIANT;

    /// <summary>
    /// Determine whether the storage string payload should be formatted in JSON.
    /// <remarks>If neither <see cref="UseJsonFormat"/> nor <see cref="UseXmlFormat"/> is set to true, then BinaryFormatSerializer will be configured to format the storage string payload.</remarks>
    /// </summary>
    public bool UseJsonFormat { get; set; }
    public bool UseFullAssemblyNames { get; set; }
    public bool IndentJson { get; set; }
    public TypeNameHandling? TypeNameHandling { get; set; }

    public Action<JsonSerializerSettings> ConfigureJsonSerializerSettings { get; set; }

    /// <summary>
    /// Determine whether storage string payload should be formatted in Xml.
    /// <remarks>If neither <see cref="UseJsonFormat"/> nor <see cref="UseXmlFormat"/> is set to true, then BinaryFormatSerializer will be configured to format storage string payload.</remarks>
    /// </summary>
    public bool UseXmlFormat { get; set; }
}

Le fournisseur de persistance ADO.NET peut versionner des données et définir des sérialiseurs et désérialiseurs arbitraires avec des règles d’application personnalisées et la diffusion en continu, mais actuellement, il n’existe aucune méthode pour exposer cette fonctionnalité directement au code d’application.

ADO.NET logique de persistance

Les principes pour le stockage de persistance soutenu par ADO.NET sont :

Conservez les données critiques pour l’entreprise et accessibles pendant que les données, le format des données et le code évoluent.
Tirez parti des fonctionnalités spécifiques au fournisseur et au stockage.

Dans la pratique, cela signifie adhérer aux objectifs d'implémentation d'ADO.NET et inclure une logique d’implémentation ajoutée dans les fournisseurs de stockage spécifiques à ADO.NET qui permettent à la forme des données dans le stockage d’évoluer.

En plus des fonctionnalités habituelles du fournisseur de stockage, le fournisseur de ADO.NET dispose d’une fonctionnalité intégrée pour :

Modifiez les données de stockage d’un format à un autre (par exemple, de JSON à binaire) lors de la conversion d'état.
Formez le type à enregistrer ou lire à partir du stockage de manière arbitraire. Cela permet à la version d’état d’évoluer.
Extraire des données de la base de données.

Vous pouvez appliquer à la fois 1. et 2. en fonction de paramètres de décision arbitraires, tels que l’ID de grain, le type de grain ou les données de charge utile.

Cela vous permet de choisir un format de sérialisation, par exemple, L’encodage binaire simple (SBE) et d’implémenter IStorageDeserializer et IStorageSerializer. Les sérialiseurs intégrés ont été créés à l’aide de cette méthode :

Après avoir implémenté les sérialiseurs, ajoutez-les à la propriété StorageSerializationPicker dans AdoNetGrainStorage. StorageSerializationPicker est l’implémentation par défaut de IStorageSerializationPicker. Vous pouvez voir un exemple de modification du format de stockage des données ou de l’utilisation de sérialiseurs dans RelationalStorageTests.

Actuellement, il n’existe aucune méthode pour exposer le sélecteur de sérialisation à l’application Orleans, car il n’existe aucun moyen d’accéder directement à l’instance AdoNetGrainStorage créée par le cadre.

Objectifs de conception

1. Autoriser l’utilisation de n’importe quel serveur principal avec un fournisseur de ADO.NET

Cela doit couvrir l’ensemble le plus large possible de back-ends disponibles pour .NET, qui est un facteur dans les installations locales. Certains fournisseurs sont répertoriés dans ADO.NET vue d’ensemble, mais tous ne sont pas répertoriés, tels que Teradata.

2. Maintenir le potentiel de réglage des requêtes et de la structure de base de données, même pendant l’exécution d’un déploiement

Dans de nombreux cas, les serveurs et bases de données hôtes tiers sont sous contrat. Il n’est pas rare de trouver des environnements d’hébergement virtualisés où les performances varient en raison de facteurs imprévus tels que les voisins bruyants ou le matériel défectueux. La modification et le redéploiement des Orleans fichiers binaires (en raison de raisons contractuelles) ou même des fichiers binaires d’application peuvent ne pas être possibles. Toutefois, l’ajustement des paramètres de déploiement de base de données est généralement possible. La modification des composants standard, tels que Orleans les fichiers binaires, nécessite une procédure d’optimisation plus longue pour une situation donnée.

3. Autoriser l’utilisation de capacités spécifiques au fournisseur et spécifiques à la version

Les fournisseurs implémentent différentes extensions et fonctionnalités dans leurs produits. Il est judicieux d’utiliser ces fonctionnalités lorsqu’elles sont disponibles. Les exemples incluent upSERT ou PipelineDB natif dans PostgreSQL, et PolyBase ou des tables compilées en mode natif et des procédures stockées dans SQL Server.

4. Activer l’optimisation des ressources matérielles

Lors de la conception d’une application, vous pouvez souvent anticiper les données qui nécessitent une insertion plus rapide et les données plus adaptées au stockage à froid moins cher (par exemple, le fractionnement des données entre SSD et HDD). Les considérations supplémentaires incluent l’emplacement physique des données (certains stockages peuvent être plus coûteux, tels que LE RAID SSD ou LE RAID HDD ou plus sécurisé) ou d’autres facteurs de décision. En rapport avec le point 3, certaines bases de données offrent des schémas de partitionnement spéciaux, tels que des tables et des index partitionnés SQL Server.

Ces principes s’appliquent tout au long du cycle de vie de l’application. Compte tenu du fait que l’un des Orleansprincipes fondamentaux est la haute disponibilité, il doit être possible d’ajuster le système de stockage sans interrompre le Orleans déploiement. Il doit également être possible d’ajuster les requêtes en fonction des données et d’autres paramètres d’application. Le billet de blog de Brian Harry fournit un exemple de changements dynamiques :

Lorsqu'une table est petite, le plan de requête a presque peu d'importance. Quand il est moyen, un plan de requête acceptable suffit, mais quand il est énorme (des millions sur des millions ou des milliards de lignes), même une légère variation dans le plan de requête peut entraîner des conséquences graves. Pour cette raison, nous laissons fortement entendre nos requêtes sensibles.

5. Ne faites aucune hypothèse sur les outils, les bibliothèques ou les processus de déploiement

De nombreuses organisations connaissent des outils de base de données spécifiques, tels que Dacpac ou Redgate. Le déploiement d’une base de données peut nécessiter une autorisation ou une personne spécifique, comme une personne dans un rôle DBA. En règle générale, cela signifie également avoir le schéma de la base de données cible et un croquis approximatif des requêtes générées par l'application pour évaluer la charge. Les processus, éventuellement influencés par les normes du secteur, peuvent imposer un déploiement basé sur des scripts. Le fait d’avoir des requêtes et des structures de base de données dans des scripts externes permet de le faire.

6. Utilisez la fonctionnalité d’interface minimale nécessaire pour charger ADO.NET bibliothèques et fonctionnalités

Cette approche est rapide et expose moins de surface à des différences potentielles dans les implémentations de bibliothèque ADO.NET.

7. Rendre la conception partitionnable

Le cas échéant (par exemple, dans un fournisseur de stockage relationnel), rendez la conception facilement partitionnable. Par exemple, cela signifie éviter les données dépendantes de la base de données comme IDENTITY colonnes. Les informations qui distinguent les données de ligne doivent s’appuyer uniquement sur les données des paramètres réels.

8. Faciliter le test de la conception

La création d’un nouveau back-end doit idéalement être aussi simple que la traduction d’un script de déploiement existant dans le dialecte SQL du back-end cible, en ajoutant une nouvelle chaîne de connexion aux tests (en supposant les paramètres par défaut), en vérifiant si la base de données est installée, puis en exécutant les tests sur celui-ci.

9. Compte tenu des points précédents, effectuez des scripts de portage pour les nouveaux back-ends et modifiez les scripts back-end existants aussi transparents que possible.

Réalisation des objectifs

L’infrastructure Orleans ne connaît pas le matériel spécifique au déploiement (qui peut changer pendant le déploiement actif), les modifications de données pendant le cycle de vie du déploiement ou certaines fonctionnalités spécifiques au fournisseur utilisables uniquement dans des situations spécifiques. Pour cette raison, l’interface entre la base de données et Orleans doit respecter l’ensemble minimal d’abstractions et de règles pour atteindre ces objectifs, garantir la robustesse contre les mauvaises utilisations et faciliter les tests. Consultez la gestion des clusters et l’implémentation concrète du protocole d’appartenance. En outre, l’implémentation de SQL Server contient un réglage spécifique à l’édition SQL Server. Le contrat d’interface entre la base de données et Orleans est défini comme suit :

L’idée générale est que les données sont lues et écrites par le biais Orleansde requêtes spécifiques. Orleans fonctionne sur les noms de colonnes et les types lors de la lecture, ainsi que sur les noms de paramètres et les types lors de l’écriture.
Les implémentations doivent conserver les noms et les types d’entrée et de sortie. Orleans utilise ces paramètres pour lire les résultats des requêtes par nom et par type. Le réglage spécifique au fournisseur et au déploiement est autorisé et les contributions sont encouragées tant que le contrat d’interface est maintenu.
Les implémentations entre les scripts spécifiques au fournisseur doivent conserver les noms de contraintes. Cela simplifie la résolution des problèmes par le biais d’un nommage uniforme entre les implémentations concrètes.
Version – ou ETag dans le code de l’application – représente une version unique pour Orleans. Le type de son implémentation réelle n’est pas important tant qu’il représente une version unique. Dans l'implémentation, le code Orleans attend un entier signé de 32 bits.
Pour être explicite et supprimer l’ambiguïté, Orleans attend que certaines requêtes retournent TRUE en tant que > valeur 0 ou FALSE comme = 0 valeur. Le nombre de lignes affectées ou retournées n’a pas d’importance. Si une erreur est générée ou qu’une exception est levée, la requête doit s’assurer que l’intégralité de la transaction est rétablie et peut retourner FALSE ou propager l’exception.
Actuellement, toutes sauf une requête sont des insertions ou des mises à jour à une seule ligne (remarque : vous pourriez remplacer les requêtes UPDATE par INSERT, à condition que les requêtes associées SELECT aient effectué la dernière écriture).

Les moteurs de base de données prennent en charge la programmation dans la base de données. Cela est similaire au chargement d’un script exécutable et à l’appel de celui-ci pour exécuter des opérations de base de données. En pseudocode, il peut être représenté comme suit :

const int Param1 = 1;
const DateTime Param2 = DateTime.UtcNow;
const string queryFromOrleansQueryTableWithSomeKey =
    "SELECT column1, column2 "+
    "FROM <some Orleans table> " +
    "WHERE column1 = @param1 " +
    "AND column2 = @param2;";
TExpected queryResult =
    SpecificQuery12InOrleans<TExpected>(query, Param1, Param2);

Ces principes sont également inclus dans les scripts de base de données.

Idées d’application de scripts personnalisés

Modifiez les scripts pour OrleansQuery la persistance des grains en utilisant IF ELSE, afin que certains états soient enregistrés avec la valeur par défaut INSERT, tandis que d'autres états de grain puissent utiliser des tables optimisées pour la mémoire. Modifiez en conséquence les requêtes SELECT.
Utilisez l'idée dans 1. pour tirer parti d'autres aspects spécifiques au déploiement ou au fournisseur, tels que le fractionnement des données entre SSD et HDD, placer certaines données dans des tables chiffrées, ou peut-être insérer des données statistiques via un transfert de SQL Server à Hadoop ou même des serveurs liés.

Vous pouvez tester les scripts modifiés en exécutant la Orleans suite de tests ou directement dans la base de données à l’aide, par exemple, d’un projet de test unitaire SQL Server.

Instructions pour l’ajout de nouveaux fournisseurs de ADO.NET

Ajoutez un nouveau script de configuration de base de données en fonction de la section Réalisation des objectifs ci-dessus.
Ajoutez le nom invariant ADO du fournisseur à AdoNetInvariants et les données spécifiques au fournisseur ADO.NET à DbConstantsStore. Celles-ci sont potentiellement utilisées dans certaines opérations de requête, par exemple, pour sélectionner le mode d’insertion de statistiques correct (par exemple, UNION ALL avec ou sans FROM DUAL).
Orleans comprend des tests complets pour tous les magasins du système : adhésion, rappels et statistiques. Ajoutez des tests pour le nouveau script de base de données en collant des classes de test existantes et en modifiant le nom invariant ADO. Dérivez également de RelationalStorageForTesting pour définir la fonctionnalité de test pour l’invariant ADO.