Créer et configurer TableAdapters dans des 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.

Les TableAdapters fournissent une communication entre votre application et une base de données. Ils se connectent à la base de données, exécutent des requêtes ou des procédures stockées et retournent une nouvelle table de données ou remplissent une DataTable existante avec les données retournées. Les TableAdapters peuvent également renvoyer les données mises à jour de votre application à la base de données.

Les TableAdapters sont créés pour vous lorsque vous effectuez l’une des actions suivantes :

  • Faites glisser des objets de base de données de l’Explorateur de serveurs vers le Concepteur de DataSet.

  • Exécutez l’assistant de configuration de la source de données, puis sélectionnez le type de source de données Base de données ou Service web.

    Data Source Configuration Wizard in Visual Studio

Vous pouvez également créer un TableAdapter et le configurer avec une source de données en faisant glisser un TableAdapter de la boîte à outils vers une région vide dans la surface du Concepteur de DataSet.

Pour une présentation de TableAdapters, consultez Remplir des jeux de données à l’aide de TableAdapters.

Notes

Dans cet article, il est possible que votre ordinateur affiche des noms ou des emplacements différents pour certains éléments de l’interface utilisateur Visual Studio. Vous utilisez peut-être une autre édition de Visual Studio ou d’autres paramètres d’environnement. Pour plus d’informations, consultez Personnaliser l’IDE.

Utiliser l’assistant de configuration de TableAdapter

Exécutez l’assistant de configuration de TableAdapter pour créer ou modifier des TableAdapters et leurs DataTables associés. Vous pouvez configurer un TableAdapter existant en cliquant dessus avec le bouton droit dans le Concepteur de DataSet.

Screenshot showing the Table Adapter Configuration Wizard.

Si vous faites glisser un nouveau TableAdapter à partir de la boîte à outils lorsque le Concepteur de DataSet est actif, l’assistant démarre et vous invite à spécifier la source de données à laquelle TableAdapter doit se connecter. Dans la page suivante, l’assistant demande quel type de commandes il doit utiliser pour communiquer avec la base de données, qu’il s’agisse d’instructions SQL ou de procédures stockées. (Vous ne verrez pas cet écran si vous configurez un TableAdapter qui est déjà associé à une source de données.)

  • Vous avez la possibilité de créer une procédure stockée dans la base de données sous-jacente si vous disposez des autorisations appropriées pour la base de données. Si vous ne disposez pas de ces autorisations, cette option n’est pas disponible.

  • Vous pouvez également choisir d’exécuter des procédures stockées existantes pour les commandes SELECT, INSERT, UPDATE et DELETE de TableAdapter. Par exemple, la procédure stockée attribuée à la commande Update est exécutée quand la méthode TableAdapter.Update() est appelée.

Mappez les paramètres de la procédure stockée sélectionnée aux colonnes correspondantes de la table de données. Par exemple, si votre procédure stockée accepte un paramètre nommé @CompanyName qu’elle passe à la colonne CompanyName de la table, définissez la Colonne Source du paramètre @CompanyName sur CompanyName.

Notes

La procédure stockée attribuée à la commande SELECT est exécutée en appelant la méthode du TableAdapter que vous nommez à la prochaine étape de l’assistant. La méthode par défaut est Fill, de sorte que le code généralement utilisé pour exécuter la procédure SELECT est TableAdapter.Fill(tableName). Si vous modifiez le nom par défaut Fill, remplacez Fill par le nom attribué et remplacez « TableAdapter » par le nom réel du TableAdapter (par exemple, CustomersTableAdapter).

  • Sélectionner l’option Créer des méthodes pour envoyer des mises à jour directement à la base de données revient à définir la propriété GenerateDBDirectMethods sur True. L’option n’est pas disponible quand l’instruction SQL d’origine ne fournit pas assez d’informations ou que la requête ne peut pas être mise à jour. Cette situation peut se produire, par exemple, dans des requêtes JOIN et des requêtes retournant une valeur unique (scalaire).

Les options avancées de l’assistant vous permettent de :

  • Générer des instructions INSERT, UPDATE et DELETE en fonction de l’instruction SELECT définie dans la page Générer des instructions SQL
  • Utiliser l'accès concurrentiel optimiste
  • Spécifier s’il faut actualiser la table de données après l’exécution des instructions INSERT et UPDATE

Configurer la méthode de remplissage d’un TableAdapter

Vous pouvez modifier le schéma de la table de TableAdapter. Pour ce faire, vous modifiez la méthode Fill principale de TableAdapter. Les TableAdapters sont créés avec une méthode Fill principale qui définit le schéma de la table de données associée. La méthode Fill principale est basée sur la requête ou la procédure stockée que vous avez entré lors de la configuration initiale de TableAdapter. Il s’agit de la première (principale) méthode sous la table de données dans le Concepteur de DataSet.

TableAdapter with multiple queries

Toutes les modifications que vous apportez à la méthode Fill principale de 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 dans la méthode Fill principale supprime également la colonne de la table de données associée. En outre, la suppression de la colonne de la méthode Fill principale supprime la colonne de toutes les requêtes supplémentaires pour ce TableAdapter.

Vous pouvez utiliser l’assistant de configuration de requête TableAdapter pour créer et modifier des requêtes supplémentaires pour TableAdapter. Ces requêtes supplémentaires doivent être conformes au schéma de table, sauf si elles retournent une valeur scalaire. Chaque requête supplémentaire a un nom que vous spécifiez.

L’exemple suivant montre comment appeler une requête supplémentaire nommée FillByCity :

CustomersTableAdapter.FillByCity(NorthwindDataSet.Customers, "Seattle")

Pour démarrer l’assistant de configuration de requêtes TableAdapter avec une nouvelle requête

  1. Ouvrez votre dataset dans le Concepteur de DataSet.

  2. Si vous créez une requête, faites glisser un objet Requête à partir de l’onglet Jeu de données de la Boîte à outils vers un DataTable, ou sélectionnez Ajouter une requête dans le menu contextuel de TableAdapter. Vous pouvez également faire glisser un objet Requête vers une zone vide du Concepteur de DataSet, ce qui crée un TableAdapter sans un DataTable associé. Ces requêtes peuvent uniquement retourner des valeurs uniques (scalaires) ou exécuter des commandes UPDATE, INSERT ou DELETE sur la base de données.

  3. Dans l’écran Choisir votre connexion de données, sélectionnez ou créez la connexion que la requête utilisera.

    Notes

    Cet écran s’affiche uniquement lorsque le concepteur ne peut pas déterminer la connexion appropriée à utiliser ou lorsqu’aucune connexion n’est disponible.

  4. Dans l’écran Choisir un type de commande, sélectionnez l’une des méthodes suivantes pour récupérer les données de la base de données :

    • L’option Utiliser des instructions SQL vous permet de taper une instruction SQL pour sélectionner les données de votre base de données.

    • L’option Créer des procédures stockées vous permet de demander à l’assistant de créer des procédures stockées (dans la base de données) en fonction de l’instruction SELECT spécifiée.

    • L’option Utiliser des procédures stockées existantes vous permet d’exécuter une procédure stockée existante lors de l’exécution de la requête.

Pour démarrer l’assistant de configuration de requêtes TableAdapter sur une requête existante

  • Si vous modifiez une requête TableAdapter existante, cliquez avec le bouton droit sur la requête, puis choisissez Configurer dans le menu contextuel.

    Remarque

    Cliquer avec le bouton droit sur la requête principale d’un TableAdapter reconfigure le TableAdapter et le schéma DataTable. Toutefois, le fait de cliquer avec le bouton droit sur une requête supplémentaire sur un TableAdapter configure uniquement la requête sélectionnée. L’assistant de configuration de TableAdapter reconfigure la définition TableAdapter, tandis que l’assistant de configuration de la requête TableAdapter reconfigure uniquement la requête sélectionnée.

Pour ajouter une requête globale à un TableAdapter

  • Les requêtes globales sont des requêtes SQL qui retournent une valeur unique (scalaire) ou aucune valeur. En règle générale, les fonctions globales effectuent des opérations de base de données telles que des insertions, des mises à jour et des suppressions. Elles regroupent également des informations, telles que le nombre de clients dans une table ou le total des frais pour tous les éléments d’une commande particulière.

    Pour ajouter des requêtes globales, faites glisser un objet Requête de l’onglet Jeu de données de la Boîte à outils vers une zone vide du Concepteur de DataSet.

  • Fournissez une requête qui effectue la tâche souhaitée, par exemple SELECT COUNT(*) AS CustomerCount FROM Customers.

    Notes

    Faire glisser un objet Requête directement vers le Concepteur de DataSet crée une méthode qui retourne uniquement une valeur scalaire (unique). Bien que la requête ou la procédure stockée que vous sélectionnez puisse retourner plusieurs valeurs, la méthode créée par l’assistant ne retourne qu’une seule valeur. Par exemple, la requête peut retourner la première colonne de la première ligne des données retournées.