Remplissez des ensembles de données à l'aide de TableAdapters dans les applications .NET Framework

Remarque

Les jeux de données et les classes associées sont des technologies .NET Framework héritées qui datent du début des années 2000. Elles permettent aux applications d’utiliser des données en mémoire pendant que les applications sont déconnectées de la base de données. Elles sont particulièrement utiles aux applications qui permettent aux utilisateurs de modifier des données, et de rendre ces changements persistants dans la base de données. Même si les jeux de données sont une technologie très efficace, nous vous recommandons d’utiliser Entity Framework Core pour les nouvelles applications .NET. Entity Framework offre un moyen plus naturel d’utiliser des données tabulaires en tant que modèles objet. De plus, il présente une interface de programmation plus simple.

Un composant TableAdapter remplit un jeu de données avec des données de la base de données, en fonction d’une ou plusieurs requêtes ou procédures stockées que vous spécifiez. Les TableAdapters peuvent également effectuer des ajouts, des mises à jour et des suppressions sur la base de données pour conserver les modifications que vous apportez au jeu de données. Vous pouvez également émettre des commandes globales qui ne sont pas liées à une table spécifique.

Notes

Les TableAdapters sont générés par les concepteurs Visual Studio. Si vous créez des jeux de données par programmation, utilisez DataAdapter, qui est une classe .NET.

Pour plus d’informations sur les opérations de TableAdapter, vous pouvez passer directement à l’une des rubriques suivantes :

Rubrique Description
Créer et configurer des TableAdapters Comment utiliser les concepteurs pour créer et configurer des TableAdapters
Créer des requêtes TableAdapter paramétrées Comment permettre aux utilisateurs de fournir des arguments aux procédures ou requêtes TableAdapter
Accéder directement à la base de données avec un TableAdapter Comment utiliser les méthodes Dbdirect de TableAdapters
Désactiver les contraintes pendant le remplissage d’un dataset Comment utiliser des contraintes de clé étrangère lors de la mise à jour des données
Guide pratique pour étendre les fonctionnalités d’un TableAdapter Comment ajouter du code personnalisé à TableAdapters
Lire les données XML dans un dataset Comment utiliser XML

Vue d’ensemble de TableAdapter

Les TableAdapters sont des composants générés par le concepteur qui se connectent à une base de données, exécutent des requêtes ou des procédures stockées et remplissent leur DataTable avec les données retournées. Les TableAdapters peuvent également renvoyer les données mises à jour de votre application à la base de données. Vous pouvez exécuter autant de requêtes que vous le souhaitez sur un TableAdapter tant qu’elles retournent des données conformes au schéma de la table à laquelle le TableAdapter est associé. Le diagramme suivant montre comment les TableAdapters interagissent avec les bases de données et d’autres objets en mémoire :

Data flow in a client application

Bien que les TableAdapters soient conçus avec le Concepteur de DataSet, les classes TableAdapter ne sont pas générées en tant que classes imbriquées de DataSet. Elles se trouvent dans des espaces de noms distincts spécifiques à chaque jeu de données. Par exemple, si vous avez un jeu de données nommé NorthwindDataSet, les TableAdapters qui sont associés à DataTable dans le NorthwindDataSet se trouvent dans l’espace de noms NorthwindDataSetTableAdapters. Pour accéder par programmation à un TableAdapter particulier, vous devez déclarer une nouvelle instance du TableAdapter. Par exemple :

NorthwindDataSet northwindDataSet = new NorthwindDataSet();

NorthwindDataSetTableAdapters.CustomersTableAdapter customersTableAdapter = 
    new NorthwindDataSetTableAdapters.CustomersTableAdapter();

customersTableAdapter.Fill(northwindDataSet.Customers);

Schéma de table de données associé

Lorsque vous créez un TableAdapter, vous utilisez la requête ou la procédure stockée initiale pour définir le schéma du TableAdapter associé à DataTable. Vous exécutez cette requête ou procédure stockée initiale en appelant la méthode Fill du TableAdapter (qui remplit le TableAdapter associé à DataTable). Toutes les modifications que vous apportez à la requête principale du TableAdapter sont répercutées dans le schéma de la table de données associée. Par exemple, la suppression d’une colonne de la requête principale supprime également la colonne de la table de données associée. Si des requêtes supplémentaires sur le TableAdapter utilisent des instructions SQL qui retournent des colonnes qui ne figurent pas dans la requête principale, le concepteur tente de synchroniser les modifications de colonne entre la requête principale et les requêtes supplémentaires.

Commandes de mise à jour du TableAdapter

La fonctionnalité de mise à jour d’un TableAdapter dépend de la quantité d’informations disponibles dans la requête principale de l’assistant du TableAdapter. Par exemple, les TableAdapters qui sont configurés pour extraire des valeurs de plusieurs tables (à l’aide d’un JOIN), des valeurs scalaires, des vues ou des résultats de fonctions d’agrégation ne sont pas initialement créés avec la possibilité de renvoyer des mises à jour à la base de données sous-jacente. Toutefois, vous pouvez configurer les commandes INSERT, UPDATEet DELETE manuellement dans la fenêtre Propriétés.

requêtes TableAdapter

TableAdapter with multiple queries

Les TableAdapters peuvent contenir plusieurs requêtes pour remplir les tables de données associées. Vous pouvez définir toutes les requêtes pour un TableAdapter dont votre application a besoin, tant que chaque requête retourne des données conformes au même schéma que la table de données associée. Cette fonctionnalité permet à un TableAdapter de charger différents résultats en fonction de critères différents.

Par exemple, si votre application contient une table avec des noms de clients, vous pouvez créer une requête qui remplit la table avec le nom de chaque client commençant par une certaine lettre, et une autre qui remplit la table avec tous les clients résidant dans le même État. Pour remplir une table Customers avec des clients dans un État donné, vous pouvez créer une requête FillByState qui prend un paramètre pour la valeur d’État comme suit : SELECT * FROM Customers WHERE State = @State. Vous exécutez la requête en appelant la méthode FillByState et en transmettant la valeur du paramètre comme suit : CustomerTableAdapter.FillByState("WA").

En plus d’ajouter des requêtes qui retournent des données du même schéma que la table de données du TableAdapter, vous pouvez ajouter des requêtes qui retournent des valeurs scalaires (uniques). Par exemple, une requête qui retourne un nombre de clients (SELECT Count(*) From Customers) est valide pour un CustomersTableAdapter, même si les données retournées ne sont pas conformes au schéma de la table.

Propriété ClearBeforeFill

Par défaut, chaque fois que vous exécutez une requête pour remplir la table de données d’un TableAdapter, les données existantes sont effacées et seuls les résultats de la requête sont chargés dans la table. Définissez la propriété ClearBeforeFill du TableAdapter sur false si vous souhaitez ajouter ou fusionner les données retournées à partir d’une requête vers les données existantes d’une table de données. Indépendamment du fait que vous effaciez ou non les données, vous devez renvoyer explicitement les mises à jour à la base de données, si vous souhaitez les conserver. N’oubliez donc pas d’enregistrer les modifications apportées aux données de la table avant d’exécuter une autre requête qui remplit la table. Pour plus d’informations, consultez Mettre à jour des données à l’aide d’un TableAdapter.

Héritage du TableAdapter

Les TableAdapters étendent les fonctionnalités des adaptateurs de données standard en encapsulant une classe DataAdapter configurée. Par défaut, le TableAdapter hérite de la classe Component et ne peut pas être casté dans la classe DataAdapter. La conversion d’un TableAdapter vers la classe DataAdapter génère une erreur InvalidCastException. Pour modifier la classe de base d’un TableAdapter, vous pouvez spécifier une classe qui dérive de Component dans la propriété Classe de base du TableAdapter dans le Concepteur de DataSet.

Méthodes et propriétés du TableAdapter

La classe du TableAdapter n’est pas de type .NET. Cela signifie que vous ne pouvez pas la rechercher dans la documentation ou dans l’Explorateur d’objets. Elle est créée au moment de la conception lorsque vous utilisez l’un des assistants mentionnés précédemment. Le nom attribué à un TableAdapter lorsque vous le créez est basé sur le nom de la table avec laquelle vous travaillez. Par exemple, lorsque vous créez un TableAdapter basé sur une table dans une base de données nommée Orders, le TableAdapter est nommé OrdersTableAdapter. Le nom de la classe du TableAdapter peut être modifié à l’aide de la propriété Nom dans le Concepteur de DataSet.

Voici les méthodes et propriétés couramment utilisées des TableAdapters :

Membre Description
TableAdapter.Fill Remplit la table de données associée au TableAdapter avec les résultats de la commande SELECT du TableAdapter.
TableAdapter.Update Renvoie les modifications à la base de données et retourne un nombre entier qui représente le nombre de lignes affectées par la mise à jour. Pour plus d’informations, consultez Mettre à jour des données à l’aide d’un TableAdapter.
TableAdapter.GetData Retourne une nouvelle DataTable qui est remplie de données.
TableAdapter.Insert Crée une ligne dans la table de données. Pour plus d’informations, consultez Insérer de nouveaux enregistrements dans une base de données.
TableAdapter.ClearBeforeFill Détermine si une table de données est vidée avant d’appeler l’une des méthodes Fill.

Méthode de mise à jour du TableAdapter

Les TableAdapters utilisent des commandes de données pour lire et écrire à partir de la base de données. Utilisez la requête initiale (principale)Fill du TableAdapter comme base pour créer le schéma de la table de données associée, ainsi que les commandes InsertCommand, UpdateCommand et DeleteCommand associées à la méthode TableAdapter.Update. L’appel de la méthode Update d’un TableAdapter exécute les instructions qui ont été créées lors de la configuration initiale du TableAdapter, et non l’une des requêtes supplémentaires que vous avez ajoutées avec l’assistant de configuration des requêtes du TableAdapter.

Lorsque vous utilisez un TableAdapter, il effectue efficacement les mêmes opérations avec les commandes que vous effectuez généralement. Par exemple, lorsque vous appelez la méthode Fill de l’adaptateur, l’adaptateur exécute la commande data dans sa propriété SelectCommand et utilise un lecteur de données (par exemple, SqlDataReader) pour charger le jeu de résultats dans la table de données. De même, lorsque vous appelez la méthode Update de l’adaptateur, celui-ci exécute la commande appropriée (dans les propriétés UpdateCommand, InsertCommand et DeleteCommand) pour chaque enregistrement modifié dans la table de données.

Notes

Si la requête principale contient suffisamment d’informations, les commandes InsertCommand, UpdateCommand et DeleteCommand sont créées par défaut lorsque le TableAdapter est généré. Si la requête principale de TableAdapter est composée de plusieurs instructions SELECT de table, il est possible que le concepteur ne soit pas en mesure de générer InsertCommand, UpdateCommand et DeleteCommand. Si ces commandes ne sont pas générées, vous pouvez recevoir une erreur lors de l’exécution de la méthode TableAdapter.Update.

TableAdapter GenerateDbDirectMethods

Outre InsertCommand, UpdateCommand et DeleteCommand, les TableAdapters sont créés avec des méthodes qui peuvent être exécutées directement sur la base de données. Vous pouvez appeler ces méthodes (TableAdapter.Insert, TableAdapter.Update et TableAdapter.Delete) pour manipuler des données directement dans la base de données. Cela signifie que vous pouvez appeler ces méthodes individuelles à partir de votre code au lieu d’appeler TableAdapter.Update pour gérer les insertions, mises à jour et suppressions qui sont en attente pour la table de données associée.

Si vous ne souhaitez pas créer ces méthodes directes, définissez la propriété GenerateDbDirectMethods de TableAdapter sur false (dans la fenêtre Propriétés). Les requêtes supplémentaires ajoutées à TableAdapter sont des requêtes autonomes. Elles ne génèrent pas ces méthodes.

Prise en charge de TableAdapter pour les types Nullable

TableAdapters prend en charge les types Nullable(Of T) et T?. Pour plus d’informations sur les types Nullable dans Visual Basic, consultez Types valeur Nullable. Pour plus d’informations sur les types Nullable dans C#, consultez Utiliser les types Nullable.

Référence TableAdapterManager

Par défaut, une classe TableAdapterManager est générée lorsque vous créez un jeu de données qui contient des tables associées. Pour empêcher la génération de la classe, définissez la valeur de la propriété Hierarchical Update du jeu de données sur false. Quand vous faites glisser sur l’aire de conception d’une page Windows Form ou WPF une table qui a une relation, Visual Studio déclare une variable membre de la classe. Si vous n’utilisez pas de liaison de données, vous devez déclarer manuellement la variable.

La classe TableAdapterManager n’est pas de type .NET. Par conséquent, vous ne pouvez pas la rechercher dans la documentation. Elle est créée au moment de la conception dans le cadre du processus de création du jeu de données.

Voici les méthodes et propriétés fréquemment utilisées de la classe TableAdapterManager :

Membre Description
Méthode UpdateAll Enregistre toutes les données de toutes les tables de données.
Propriété BackUpDataSetBeforeUpdate Détermine s’il faut créer une copie de sauvegarde du jeu de données avant d’exécuter la méthode TableAdapterManager.UpdateAll.Boolean.
Propriété tableNameTableAdapter Représente un TableAdapter. Le TableAdapterManager généré contient une propriété pour chaque TableAdapter qu’il gère. Par exemple, un jeu de données avec des tables Clients et Commandes est généré avec un TableAdapterManager qui contient les propriétés CustomersTableAdapter et OrdersTableAdapter.
Propriété UpdateOrder Contrôle l’ordre des commandes individuelles d’insertion, de mise à jour et de suppression. Définissez-la sur une des valeurs de l’énumération TableAdapterManager.UpdateOrderOption.

Par défaut, UpdateOrder est défini sur InsertUpdateDelete. Cela signifie que les insertions, puis les mises à jour, puis les suppressions sont effectuées pour toutes les tables du jeu de données.

Sécurité

Lorsque vous utilisez des commandes de données avec une propriété CommandType définie sur Text, vérifiez soigneusement les informations envoyées à partir d’un client avant de les transmettre à votre base de données. Des utilisateurs malveillants peuvent tenter d’envoyer (injecter) des instructions SQL modifiées ou supplémentaires afin d’accéder à la base de données ou de l’endommager. Avant de transférer l’entrée utilisateur vers une base de données, vérifiez toujours que les informations sont valides. Une bonne pratique consiste à toujours utiliser des requêtes paramétrables ou des procédures stockées lorsque cela est possible.