Informations de référence sur les outils Entity Framework Core - CLI .NET Core

  • Article

Les outils d’interface de ligne de commande (CLI) pour Entity Framework Core effectuent des tâches de développement au moment du design. Par exemple, ils créent migrations, appliquent des migrations et génèrent du code pour un modèle basé sur une base de données existante. Les commandes sont une extension de la commande dotnet multiplateforme, qui fait partie du sdk .NET Core. Ces outils fonctionnent avec des projets .NET Core.

Lorsque vous utilisez Visual Studio, envisagez d’utiliser les outils de console du gestionnaire de package au lieu des outils CLI. Les outils de console du gestionnaire de package vont automatiquement :

  • Fonctionner avec le projet actuel sélectionné dans la console du gestionnaire de package sans avoir à changer manuellement de répertoires.
  • Ouvrir les fichiers générés par une commande une fois la commande terminée.
  • Fournir la saisie semi-automatique de tabulation des commandes, des paramètres, des noms de projet, des types de contexte et des noms de migration.

Installation des outils

dotnet ef peut être installé en tant qu’outil global ou local. La plupart des développeurs préfèrent installer dotnet ef en tant qu’outil global à l’aide de la commande suivante :

dotnet tool install --global dotnet-ef

Pour l’utiliser comme outil local, restaurez les dépendances d’un projet qui le déclare en tant que dépendance d’outil en utilisant un fichier manifeste d’outil.

Mettez à jour l’outil à l’aide de la commande suivante :

dotnet tool update --global dotnet-ef

Avant de pouvoir utiliser les outils d’un projet spécifique, vous devez y ajouter le package Microsoft.EntityFrameworkCore.Design.

dotnet add package Microsoft.EntityFrameworkCore.Design

Vérifier l’installation

Exécutez les commandes suivantes pour vérifier que les outils EF Core CLI sont correctement installés :

dotnet ef

La sortie de la commande identifie la version des outils en cours d’utilisation :


                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\\/\\

Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065

<Usage documentation follows, not shown.>

Mettre à jour Data Lake Tools

Utilisez dotnet tool update --global dotnet-ef pour mettre à jour les outils globaux vers la dernière version disponible. Si les outils sont installés localement dans votre projet, utilisez dotnet tool update dotnet-ef. Installez une version spécifique en ajoutant --version <VERSION> à votre commande. Pour plus d’informations, consultez la section Update de la documentation de l’outil dotnet.

Utilisation des outils

Avant d’utiliser les outils, vous devrez peut-être créer un projet de démarrage ou définir l’environnement.

Projet cible et projet de démarrage

Les commandes font référence à un projet et à un projet de start-up.

  • Le projet est également appelé projet cible, car il s’agit de l’emplacement où les commandes ajoutent ou suppriment des fichiers. Par défaut, le projet dans le répertoire actif est le projet cible. Vous pouvez spécifier un autre projet en tant que projet cible à l’aide du paramètre --project.

  • Le projet de start-up est celui que les outils créent et exécutent. Les outils doivent exécuter du code d’application au moment du design pour obtenir des informations sur le projet, telles que la chaîne de connexion de base de données et la configuration du modèle. Par défaut, le projet dans le répertoire actif est le projet de démarrage. Vous pouvez spécifier un autre projet en tant que projet de démarrage à l’aide de l’option --startup-project.

Le projet de démarrage et le projet cible sont souvent le même projet. Un scénario classique dans lequel ils sont des projets distincts est le cas :

  • Le contexte EF Core et les classes d’entité se trouvent dans une bibliothèque de classes .NET Core.
  • Une application console .NET Core ou une application web fait référence à la bibliothèque de classes.

Il est également possible de placer du code de migration dans une bibliothèque de classes distincte du contexte EF Core.

Autres frameworks cibles

Les outils CLI fonctionnent avec des projets .NET Core et des projets .NET Framework. Les applications qui ont le modèle EF Core dans une bibliothèque de classes .NET Standard peuvent ne pas avoir de projet .NET Core ou .NET Framework. Par exemple, cela est vrai pour les applications de plateforme Windows universelle et Xamarin. Dans ce cas, vous pouvez créer un projet d’application console .NET Core dont seul l’objectif est d’agir comme projet de démarrage pour les outils. Le projet peut être un projet factice sans code réel, il n’est nécessaire que de fournir une cible pour les outils.

Pourquoi un projet factice est-il nécessaire ? Comme mentionné précédemment, les outils doivent exécuter du code d’application au moment du design. Pour ce faire, ils doivent utiliser le runtime .NET Core. Lorsque le modèle EF Core se trouve dans un projet qui cible .NET Core ou .NET Framework, les outils EF Core empruntent le runtime du projet. Ils ne peuvent pas le faire si le modèle EF Core se trouve dans une bibliothèque de classes .NET Standard. .NET Standard n’est pas une implémentation .NET réelle ; il s’agit d’une spécification d’un ensemble d’API que les implémentations .NET doivent prendre en charge. Par conséquent, .NET Standard n’est pas suffisant pour que les outils EF Core exécutent du code d’application. Le projet factice que vous créez à utiliser comme projet de démarrage fournit une plateforme cible concrète dans laquelle les outils peuvent charger la bibliothèque de classes .NET Standard.

Environnement ASP.NET Core

Vous pouvez spécifier l’environnement pour les projets ASP.NET Core sur la ligne de commande. Cela et tous les arguments supplémentaires sont passés dans Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Conseil

Le jeton -- dirige dotnet ef pour traiter tout ce qui suit comme argument, sans essayer de les analyser en tant qu’options. Tous les arguments supplémentaires, non utilisés par dotnet ef, sont transférés à l’application.

Options courantes

Option Court Description
--json Afficher la sortie JSON.
--context <DBCONTEXT> -c Classe DbContext à utiliser. Nom de classe uniquement ou qualifié complet avec des espaces de noms. Si cette option est omise, EF Core trouve la classe de contexte. S’il existe plusieurs classes de contexte, cette option est requise.
--project <PROJECT> -p Chemin d’accès relatif au dossier du projet cible. La valeur par défaut est le dossier actif.
--startup-project <PROJECT> -s Chemin d’accès relatif au dossier du projet de démarrage. La valeur par défaut est le dossier actif.
--framework <FRAMEWORK> Le Moniker de tramework cible pour le framework cible. Utilisez lorsque le fichier projet spécifie plusieurs frameworks cibles et que vous souhaitez sélectionner l’un d’eux.
--configuration <CONFIGURATION> Configuration de build, par exemple : Debug ou Release.
--runtime <IDENTIFIER> Identificateur du runtime cible pour lequel restaurer des packages. Pour connaître les identificateurs de runtime, consultez le catalogue des identificateurs de runtime.
--no-build Ne générez pas le projet. Destiné à être utilisé lorsque la build est à jour.
--help -h Afficher les informations d’aide.
--verbose -v Afficher la sortie détaillée.
--no-color Ne colorisez pas la sortie.
--prefix-output Sortie de préfixe avec niveau.

Tous les arguments supplémentaires sont passés à l’application.

dotnet ef database drop

Supprime la base de données.

Options :

Option Court Description
--force -f Ne confirmez pas.
--dry-run Affichez la base de données à supprimer, mais ne la supprimez pas.

Les options courantes sont répertoriées ci-dessus.

dotnet ef database update

Met à jour la base de données vers la dernière migration ou vers une migration spécifiée.

Arguments :

Argument Description
<MIGRATION> Migration cible. Les migrations peuvent être identifiées par nom ou par ID. Le nombre 0 est un cas spécial qui signifie avant le premier de migration et entraîne la restauration de toutes les migrations. Si aucune migration n’est spécifiée, la commande est définie par défaut sur la dernière migration.

Options :

Option Description
--connection <CONNECTION> Chaîne de connexion à la base de données. La valeur par défaut est celle spécifiée dans AddDbContext ou OnConfiguring.

Les options courantes sont répertoriées ci-dessus.

Les exemples suivants mettent à jour la base de données vers une migration spécifiée. La première utilise le nom de la migration et la seconde utilise l’ID de migration et une connexion spécifiée :

dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string

dotnet ef dbcontext info

Obtient des informations sur un type de DbContext.

Les options courantes sont répertoriées ci-dessus.

dotnet ef dbcontext list

Répertorie les types de DbContext disponibles.

Les options courantes sont répertoriées ci-dessus.

dotnet ef dbcontext optimize

Génère une version compilée du modèle utilisé par DbContext.

Pour plus d’informations, consultez modèles compilés.

Options :

Option Court Description
--output-dir <PATH> -o Répertoire dans lequel placer des fichiers. Les chemins d’accès sont relatifs au répertoire du projet.
--namespace <NAMESPACE> -n Espace de noms à utiliser pour toutes les classes générées. Valeurs par défaut à générer à partir de l’espace de noms racine et du répertoire de sortie plus CompiledModels.

Les options courantes sont répertoriées ci-dessus.

L’exemple suivant utilise les paramètres par défaut et fonctionne s’il n’existe qu’un seule DbContext dans le projet :

dotnet ef dbcontext optimize

L’exemple suivant optimise le modèle pour le contexte avec le nom spécifié et le place dans un dossier et un espace de noms distincts :

dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext

dotnet ef dbcontext scaffold

Génère du code pour un DbContext et des types d’entités pour une base de données. Pour que cette commande génère un type d’entité, la table de base de données doit avoir une clé primaire.

Arguments :

Argument Description
<CONNECTION> Chaîne de connexion à la base de données. Pour ASP.NET projets Core 2.x, la valeur peut être name=<nom de la chaîne de connexion>. Dans ce cas, le nom provient des sources de configuration configurées pour le projet.
<PROVIDER> Fournisseur à utiliser. En règle générale, il s’agit du nom du package NuGet, par exemple : Microsoft.EntityFrameworkCore.SqlServer.

Options :

Option Court Description
--data-annotations -d Utilisez des attributs pour configurer le modèle (le cas échéant). Si cette option est omise, seule l’API Fluent est utilisée.
--context <NAME> -c Nom de la classe DbContext à générer.
--context-dir <PATH> Répertoire dans lequel placer le fichier de classe DbContext. Les chemins d’accès sont relatifs au répertoire du projet. Les espaces de noms sont dérivés des noms de dossiers.
--context-namespace <NAMESPACE> Espace de noms à utiliser pour la classe DbContext générée. Remarque : remplace --namespace.
--force -f Remplacer les fichiers existants.
--output-dir <PATH> -o Répertoire dans lequel placer des fichiers de classe d’entité. Les chemins d’accès sont relatifs au répertoire du projet.
--namespace <NAMESPACE> -n Espace de noms à utiliser pour toutes les classes générées. La valeur par défaut est générée à partir de l’espace de noms racine et du répertoire de sortie.
--schema <SCHEMA_NAME>... Schémas de tables et de vues pour générant des types d’entités. Pour spécifier plusieurs schémas, répétez --schema pour chacun d’eux. Si cette option est omise, tous les schémas sont inclus. Si cette option est utilisée, toutes les tables et vues dans les schémas seront incluses dans le modèle, même si elles ne sont pas explicitement incluses à l’aide de --table.
--table <TABLE_NAME>... -t Tables et vues pour générant des types d’entités. Pour spécifier plusieurs tables, répétez -t ou --table pour chacune d’elles. Vous pouvez inclure des tables ou des vues dans un schéma spécifique à l’aide du format « schema.table » ou « schema.view ». Si cette option est omise, toutes les tables et vues sont incluses.
--use-database-names Utilisez des noms de table, d’affichage, de séquence et de colonne exactement comme ils apparaissent dans la base de données. Si cette option est omise, les noms de base de données sont modifiés de manière plus étroitement conforme aux conventions de style de nom C#.
--no-onconfiguring Supprime la génération de la méthode OnConfiguring dans la classe DbContext générée.
--no-pluralize N’utilisez pas le pluralisateur.

Les options courantes sont répertoriées ci-dessus.

L’exemple suivant génère une structure de tous les schémas et tables et place les nouveaux fichiers dans le dossier Models .

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models

L’exemple suivant crée uniquement des tables sélectionnées et crée le contexte dans un dossier distinct avec un nom et un espace de noms spécifiés :

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models -t Blog -t Post --context-dir Context -c BlogContext --context-namespace New.Namespace

L’exemple suivant lit la chaîne de connexion à partir du jeu de configuration du projet à l’aide de l’outil Secret Manager.

dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging"
dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer

L’exemple suivant ignore la structure d’une méthode OnConfiguring. Cela peut être utile lorsque vous souhaitez configurer DbContext en dehors de la classe. Par exemple, ASP.NET applications Core le configurent généralement dans Startup.ConfigureServices.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;User Id=myUsername;Password=myPassword;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring

dotnet ef dbcontext script

Génère un script SQL à partir de DbContext. Contourne toutes les migrations.

Options :

Option Court Description
--output <FILE> -o Fichier dans lequel écrire le résultat.

Les options courantes sont répertoriées ci-dessus.

dotnet ef migrations add

Ajoute une nouvelle migration.

Arguments :

Argument Description
<NAME> Nom de la migration.

Options :

Option Court Description
--output-dir <PATH> -o Répertoire utilisé pour générer les fichiers. Les chemins d’accès sont relatifs au répertoire du projet cible. La valeur par défaut est « Migrations ».
--namespace <NAMESPACE> -n Espace de noms à utiliser pour les classes générées. Valeurs par défaut à générer à partir du répertoire de sortie.

Les options courantes sont répertoriées ci-dessus.

dotnet ef migrations bundle

Crée un exécutable pour mettre à jour la base de données.

Options :

Option Court Description
--output <FILE> -o Chemin d’accès du fichier exécutable à créer.
--force -f Remplacer les fichiers existants.
--self-contained Regroupez également le runtime .NET afin qu’il n’ait pas besoin d’être installé sur l’ordinateur.
--target-runtime <RUNTIME_IDENTIFIER> -r Runtime cible pour lequel regrouper.

Les options courantes sont répertoriées ci-dessus.

dotnet ef migrations has-pending-model-changes

Remarque

Cette commande a été ajoutée dans EF Core 8.0.

Vérifie si des modifications ont été apportées au modèle depuis la dernière migration.

Options :

Les options courantes sont répertoriées ci-dessus.

dotnet ef migrations list

Répertorie les migrations disponibles.

Options :

Option Description
--connection <CONNECTION> Chaîne de connexion à la base de données. La valeur par défaut est celle spécifiée dans AddDbContext ou OnConfiguring.
--no-connect Ne vous connectez pas à la base de données.

Les options courantes sont répertoriées ci-dessus.

dotnet ef migrations remove

Supprime la dernière migration, en supprimant les modifications de code effectuées pour la dernière migration.

Options :

Option Court Description
--force -f Rétablir la dernière migration, restaurer à la fois le code et les modifications de base de données effectuées pour la dernière migration. Continue de restaurer uniquement le code si une erreur se produit lors de la connexion à la base de données.

Les options courantes sont répertoriées ci-dessus.

dotnet ef migrations script

Génère un script SQL à partir de migrations.

Arguments :

Argument Description
<FROM> Migration de départ. Les migrations peuvent être identifiées par nom ou par ID. Le nombre 0 est un cas spécial qui signifie avant la première migration. La valeur par défaut est 0.
<TO> Migration de fin. Valeur par défaut de la dernière migration.

Options :

Option Court Description
--output <FILE> -o Fichier dans lequel écrire le script.
--idempotent -i Générez un script qui peut être utilisé sur une base de données à n’importe quelle migration.
--no-transactions Ne générez pas d’instructions de transaction SQL.

Les options courantes sont répertoriées ci-dessus.

L’exemple suivant crée un script pour la migration InitialCreate :

dotnet ef migrations script 0 InitialCreate

L’exemple suivant crée un script pour toutes les migrations après la migration InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Ressources supplémentaires