Nous présentons à votre attention DbTool - un utilitaire de ligne de commande pour exporter des données de base de données vers divers formats et la bibliothèque open-source Korzh.DbUtils , dont l'utilisation peut grandement simplifier le «semis» initial de la base de données dans votre application .NET (Core).
Avec cette boîte à outils, vous pouvez:
- Enregistrez les données de votre base de données locale dans des fichiers d'un certain format de texte (XML, JSON), qui sont faciles à connecter au projet.
- Utilisez des fichiers enregistrés pour remplir la base de données de l'application elle-même lors de son premier démarrage.
Ci-dessous, je vais vous expliquer pourquoi tout cela est nécessaire, comment installer et configurer ces outils et décrire un scénario détaillé pour leur utilisation.
La tâche initiale était de créer un mécanisme de remplissage de base de données pratique dans les applications .NET (Core). En raison des spécificités de notre type d'activité (développement de composants), nous devons souvent créer de petits exemples d'applications qui présentent l'une ou l'autre des caractéristiques de notre produit. Ces projets de démonstration doivent fonctionner avec une certaine base de données de test et il est donc conseillé de créer et de remplir automatiquement cette base de données au premier démarrage de l'application.
Si le projet utilise Entity Framework (Core) (et cela arrive le plus souvent), la création de la base de données ne pose aucun problème. Vous appelez simplement dbContext.Database.EnsureCreated ou dbContext.Database.Migrate (s'il est important de conserver les migrations).
Mais avec le remplissage de la base de données, tout est un peu plus compliqué. La première chose qui me vient à l'esprit est simplement de créer un script SQL avec un tas d'INSERTS, de le mettre dans le projet et de l'exécuter au premier démarrage. Cela fonctionne (et nous l'avons fait depuis longtemps), mais il y a quelques problèmes avec cette approche. Tout d'abord, c'est une question de syntaxe SQL pour un SGBD spécifique. Très souvent, le SGBD d'origine est différent de celui qui est réellement utilisé par l'utilisateur et notre script SQL peut ne pas fonctionner.
Le deuxième problème possible est la migration de la base de données elle-même. De temps en temps, il est nécessaire de modifier légèrement la structure de la base de données (ajouter un nouveau champ, supprimer ou renommer l'ancien, ajouter une nouvelle relation entre les tables, etc.). Un script SQL créé sous l'ancienne structure devient généralement hors de propos dans ce cas et son exécution provoque une erreur. Le chargement de données à partir d'un format tiers se fait sans problème. Les champs nouveaux / modifiés sont simplement ignorés. Convenez qu'à des fins de démonstration, il vaut mieux que le programme démarre, quoique sans données dans un nouveau domaine, que qu'il ne démarre pas du tout.
En conséquence, nous sommes arrivés à la solution suivante:
- Les données de la "copie maître" de notre base de données de démonstration sont enregistrées dans un fichier dans un certain format "indépendant" (actuellement c'est XML ou JSON). Les fichiers résultants (ou un fichier d'archive) sont livrés avec le projet. Cette tâche, en fait, concerne DbTool.
- Un petit morceau de code est inséré dans notre programme qui, en utilisant les classes et les fonctions de la bibliothèque Korzh.DbUtils, remplit la base de données avec les données du ou des fichiers obtenus à la première étape.
En plus du scénario ci-dessus, DbTool peut être utilisé simplement pour exporter des données vers d'autres formats et pour transférer des données entre des bases de données. Ainsi, par exemple, vous pouvez télécharger des données de votre base de données vers SQL Server, puis les charger dans une base de données similaire dans MySQL
L'installation
DbTool est implémenté comme un outil global .NET Core, c'est-à -dire peut être facilement installé sur n'importe quel système sur lequel existe un SDK .NET version 2.1 ou supérieure.
Pour installer l'utilitaire, il vous suffit d'ouvrir la console (Terminal / Invite de commandes) et d'exécuter la commande suivante:
dotnet tool install -g Korzh.DbTool
Pour vérifier après l'installation, tapez dbtool dans la console et vous verrez de l'aide avec une liste des commandes disponibles.
Ajouter une connexion à la base de données
Pour commencer à travailler avec DbTool, vous devez ajouter une connexion à la base de données:
dbtool add {YourConnectionId} {DbType} {YourConnectionString}
Ici:
- {YourConnectionId} est un identifiant que vous souhaitez attribuer à cette connexion afin que vous puissiez y accéder ultérieurement lorsque vous exécutez d'autres commandes.
- DbType est le type de votre SGBD. Au moment d'écrire ces lignes, DbTool (version 1.1.7) supportait les bases de données SQL Server (mssql) et MySQL (mysql).
- Le dernier paramètre de cette commande est la chaîne de connexion. Identique à celui que vous utilisez déjà dans votre projet .NET (Core).
Un exemple:
Après cela, vous pouvez vérifier toutes vos connexions en tapant:
dbtool connections list
Exportation de données
Maintenant que nous avons ajouté la connexion, nous pouvons exporter notre base de données à l'aide de la commande d'exportation:
dbtool export {ConnectionId} [--format=xml|json] [--output={path-to-folder}] [--zip={file-name}]
Toute option mentionnée ci-dessus peut être omise. Si vous ne spécifiez pas de format alors JSON sera utilisé. Si vous omettez l'option de output , le résultat sera placé dans un répertoire du formulaire ConnectionId_yyyy-MM-dd sous une forme décompressée.
Par exemple, la commande suivante:
dbtool export MyDb01 --zip=MyDbData.zip
va créer une archive ZIP avec le nom MyDbData.zip dans le répertoire courant et la remplir avec des fichiers de données au format JSON (un fichier pour chaque table de base de données).
Importation de données
Vous pouvez réimporter les données créées à l'étape précédente dans votre base de données. Ou à toute autre base avec la même structure.
Important: DbTool ne crée pas de tables lors de l'importation. Ainsi, la base de données dans laquelle les données sont importées doit déjà exister et avoir la même structure (ou au moins similaire) que celle d'origine.
La commande d'importation elle-mĂŞme est la suivante:
dbtool import {ConnectionId} [--input=path-to-file-or-folder] [--format=xml|json]
L'option --input indique à l'utilitaire où rechercher les données importées. Si un chemin de dossier est spécifié, DbTool importera des fichiers .xml ou .json dans ce dossier. S'il s'agit d'un fichier ZIP, l'utilitaire décompressera d'abord cette archive et enlèvera les fichiers de données nécessaires.
Comme dans le cas précédent, --format peut être omis car DbTool peut reconnaître le format par les extensions de fichier.
Un exemple:
dbtool import MyDb01 --input=MyDbData.zip
Bibliothèque Korzh.DbUtils
L'utilitaire DbTool lui-même est construit sur la base de la bibliothèque open source Korzh.DbUtils , qui comprend plusieurs packages avec la mise en œuvre de certaines opérations de base de base de données.
Korzh.DbUtils
DĂ©finit les abstractions et les interfaces de base, telles que IDatasetExporter, IDatasetImporter, IDataPacker, IDbBridge
Korzh.DbUtils.Import
Contient des implémentations d'interfaces IDatasetImporter pour les formats XML et JSON. En outre, ce package comprend la classe DbInitializer, que vous pouvez utiliser pour remplir les données de vos projets (voir ci-dessous).
Korzh.DbUtils.Export
Contient des implémentations d'IDatasetExporter pour XML et JSON.
Korzh.DbUtils.SqlServer
Contient l'implémentation des interfaces des opérations de base de données (IDbBridge, IDbReader, IDbSeeder) pour MS SQL Server.
Korzh.DbUtils.MySQL
Contient des implémentations d'interfaces de base de données pour MySQL.
Ici vous pouvez trouver la référence complète sur l'API de la bibliothèque Korzh.DbUtils .
Utilisation de Korzh.DbUtils pour remplir la base de données avec des données au démarrage de l'application
Maintenant, en fait, nous verrons comment utiliser le DbTool et Korzh.DbUtils pour implémenter le script de base pour remplir (amorcer) la base de données au premier lancement de l'application.
Supposons que vous ayez une «copie principale» d'une base de données que vous devez «copier» sur l'ordinateur de l'utilisateur lorsque vous démarrez l'application pour la première fois.
Étape 1: exporter la copie principale vers JSON
Installez simplement DbTool, comme décrit ci-dessus, ajoutez une connexion à la base de données et exécutez la commande d'exportation pour enregistrer toutes les données de cette base de données dans un dossier séparé:
dotnet tool install -g Korzh.DbTool dbtool connections add MyMasterDb mssql "{ConnectionString}" dbtool export MyMasterDb
Étape 2: ajouter des fichiers de données à notre projet
Après l'étape précédente, nous avons un nouveau dossier, de la forme MyMasterDb-yyyy-MM-dd, avec un tas de fichiers JSON (un pour chaque table). Copiez simplement le contenu de ce dossier dans App_Data \ DbSeed de notre projet .NET (Core). Veuillez noter que pour les projets sous .NET Framework, vous devrez également ajouter manuellement ces fichiers au projet.
Étape 3: code d'initialisation de la base de données
Bien que le processus lui-même (jusqu'à certains détails) soit applicable à tout type de projet sous .NET Core ou .NET Framework (version 4.6.1 ou supérieure), pour simplifier la description, supposons que nous parlons d'un projet ASP.NET Core qui fonctionne avec Base de données SQL Server et que cette base de données est créée automatiquement à l'aide d'Entity Framework Core.
Ainsi, pour résoudre le problème de remplissage de la base de données avec des données au premier démarrage, nous avons besoin de:
1. Installez les packages de bibliothèque Korzh.DbUtils dans le projet NuGet
Dans ce cas, nous en avons besoin de 2:
- Korzh.DbUtils.Import
- Korzh.DbUtils.SqlServer
2. Ajoutez le code d'initialisation
Voici un exemple d'un tel code que nous devrions ajouter à la fin de la méthode Startup.Configure:
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { . . . . app.UseMvc(); using (var scope = app.ApplicationServices.GetRequiredService<IServiceScopeFactory>().CreateScope()) using (var context = scope.ServiceProvider.GetService<AppDbContext>()) { if (context.Database.EnsureCreated()) {
Pour tout rendre assez beau, ou si vous devez effectuer une initialisation supplémentaire au premier démarrage (par exemple, ajouter plusieurs comptes d'utilisateur et / ou rôles d'utilisateur), il est préférable d'organiser tout ce code en tant que méthode d'extension distincte (appelons-le EnsureDbInitialized ) pour l'interface IApplicationBuilder .
Un exemple d'une telle implémentation peut être trouvé sur GitHub dans le projet de démonstration de la bibliothèque EasyQuery .
Dans ce cas, il vous suffit d'ajouter un appel à la fin de votre méthode Startup.Configure:
public void Configure ( IApplicationBuilder, IHostingEnvironment) { . . . . app.UseMvc ();
Plans futurs
Bien que la bibliothèque et l'utilitaire aient été écrits dans un scénario très spécifique, nous avons essayé de tout faire aussi flexible et extensible que possible, afin d'activer des fonctionnalités supplémentaires ne serait pas un problème.
Parmi les améliorations possibles, nous voyons ce qui suit:
Prise en charge d'autres bases de données (PostgreSQL, Oracle, SQLite, MariaDB)
Nouveaux formats vers lesquels vous pouvez exporter des données (CSV, Excel, HTML)
L'opération de copie directe des données de la base de données vers la base de données (maintenant vous pouvez l'implémenter via quelques appels consécutifs aux commandes d'exportation / importation)
Opérations de sauvegarde / restauration complètes avec conservation complète de la structure de la base de données et sa création à partir de zéro pendant la restauration.
Nous serons heureux d'entendre toutes suggestions ou commentaires et sommes très reconnaissants pour les nouvelles étoiles pour le référentiel de la bibliothèque GitHub :)
Merci de votre attention!