Informations de référence sur les outils Entity Framework Core - Console du Gestionnaire de package dans Visual Studio

  • Article

Les outils PMC (Package Manager Console) 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 s’exécutent à l’intérieur de Visual Studio à l’aide de la console du Gestionnaire de package. Ces outils fonctionnent avec les projets .NET Framework et .NET Core.

Si vous n’utilisez pas Visual Studio, nous vous recommandons outils en ligne de commande EF Core à la place. Les outils CLI .NET Core sont multiplateformes et s’exécutent à l’intérieur d’une invite de commandes.

Installation des outils

Installez les outils de console du Gestionnaire de package en exécutant la commande suivante dans console du Gestionnaire de package:

Install-Package Microsoft.EntityFrameworkCore.Tools

Mettez à jour les outils en exécutant la commande suivante dans console du Gestionnaire de package.

Update-Package Microsoft.EntityFrameworkCore.Tools

Vérifier l’installation

Vérifiez que les outils sont installés en exécutant cette commande :

Get-Help about_EntityFrameworkCore

La sortie ressemble à ceci (elle ne vous indique pas quelle version des outils que vous utilisez) :


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

TOPIC
    about_EntityFrameworkCore

SHORT DESCRIPTION
    Provides information about the Entity Framework Core Package Manager Console Tools.

<A list of available commands follows, omitted here.>

Utilisation des outils

Avant d’utiliser les outils :

  • Comprendre la différence entre le projet cible et le projet de démarrage.
  • Découvrez comment utiliser les outils avec des bibliothèques de classes .NET Standard.
  • Pour ASP.NET projets Core, définissez l’environnement.

Projet cible et 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 par défaut sélectionné dans console du Gestionnaire de package 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 de start-up dans l’Explorateur de solutions est le projet de démarrage. Vous pouvez spécifier un autre projet en tant que projet de démarrage à l’aide du paramètre -StartupProject.

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 de console du Gestionnaire de package fonctionnent avec des projets .NET Core ou .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 ou .NET Framework 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 ou .NET Framework. 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.

Update-Database -Args '--environment Production'

Paramètres communs

Le tableau suivant présente les paramètres communs à toutes les commandes EF Core :

Paramètre Description
-Context <String> Classe DbContext à utiliser. Nom de classe uniquement ou qualifié complet avec des espaces de noms. Si ce paramètre est omis, EF Core recherche la classe de contexte. S’il existe plusieurs classes de contexte, ce paramètre est requis.
-Project <String> Projet cible. Si ce paramètre est omis, le projet par défaut pour console du Gestionnaire de package est utilisé comme projet cible.
-StartupProject <String> Projet de démarrage. Si ce paramètre est omis, le projet de démarrage dans propriétés de solution est utilisé comme projet cible.
-Args <String> Arguments passés à l’application.
-Verbose Afficher la sortie détaillée.

Pour afficher des informations d’aide sur une commande, utilisez la commande Get-Help powerShell.

Conseil

Les paramètres Context, Projectet StartupProject prennent en charge l’expansion de tabulation.

Migration des compléments

Ajoute une nouvelle migration.

Paramètres :

Paramètre Description
-Name <String> Nom de la migration. Il s’agit d’un paramètre positionnel et est requis.
-OutputDir <String> 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 <String> 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 paramètres courants sont répertoriés ci-dessus.

Migration groupée

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

Paramètres :

Paramètre Description
-Output <String> Chemin d’accès du fichier exécutable à créer.
-Force Remplacer les fichiers existants.
-SelfContained Regroupez également le runtime .NET afin qu’il n’ait pas besoin d’être installé sur l’ordinateur.
-TargetRuntime <String> Runtime cible pour lequel regrouper.
-Framework <String> Framework cible. La valeur par défaut est la première dans le projet.

Les paramètres courants sont répertoriés ci-dessus.

Drop-Database

Supprime la base de données.

Paramètres :

Paramètre Description
-WhatIf Affichez la base de données à supprimer, mais ne la supprimez pas.

Les paramètres courants sont répertoriés ci-dessus.

Get-DbContext

Répertorie et obtient des informations sur les types DbContext disponibles.

Les paramètres courants sont répertoriés ci-dessus.

Get-Migration

Répertorie les migrations disponibles.

Paramètres :

Paramètre Description
-Connection <String> Chaîne de connexion à la base de données. La valeur par défaut est celle spécifiée dans AddDbContext ou OnConfiguring.
-NoConnect Ne vous connectez pas à la base de données.

Les paramètres courants sont répertoriés ci-dessus.

Optimize-DbContext

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

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

Paramètres :

Paramètre Description
-OutputDir <String> Répertoire dans lequel placer des fichiers. Les chemins d’accès sont relatifs au répertoire du projet.
-Namespace <String> 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 paramètres courants sont répertoriés ci-dessus.

L’exemple suivant utilise les valeurs par défaut et fonctionne s’il n’existe qu’une seule DbContext dans le projet :

Optimize-DbContext

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 :

Optimize-DbContext -OutputDir Models -Namespace BlogModels -Context BlogContext

Remove-Migration

Supprime la dernière migration (restaure les modifications de code effectuées pour la migration).

Paramètres :

Paramètre Description
-Force Rétablir la migration (restaurer les modifications qui ont été appliquées à la base de données).

Les paramètres courants sont répertoriés ci-dessus.

Scaffold-DbContext

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

Paramètres :

Paramètre Description
-Connection <String> 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. Il s’agit d’un paramètre positionnel et est requis.
-Provider <String> Fournisseur à utiliser. En règle générale, il s’agit du nom du package NuGet, par exemple : Microsoft.EntityFrameworkCore.SqlServer. Il s’agit d’un paramètre positionnel et est requis.
-OutputDir <String> Répertoire dans lequel placer des fichiers de classe d’entité. Les chemins d’accès sont relatifs au répertoire du projet.
-ContextDir <String> Répertoire dans lequel placer le fichier DbContext. Les chemins d’accès sont relatifs au répertoire du projet.
-Namespace <String> 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.
-ContextNamespace <String> Espace de noms à utiliser pour la classe DbContext générée. Remarque : remplace -Namespace.
-Context <String> Nom de la classe DbContext à générer.
-Schemas <String[]> Schémas de tables et de vues pour générant des types d’entités. Si ce paramètre est omis, 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.
-Tables <String[]> Tables et vues pour générant des types d’entités. Vous pouvez inclure des tables ou des vues dans un schéma spécifique à l’aide du format « schema.table » ou « schema.view ». Si ce paramètre est omis, toutes les tables et vues sont incluses.
-DataAnnotations Utilisez des attributs pour configurer le modèle (le cas échéant). Si ce paramètre est omis, seule l’API Fluent est utilisée.
-UseDatabaseNames Utilisez des noms de table, d’affichage, de séquence et de colonne exactement comme ils apparaissent dans la base de données. Si ce paramètre est omis, les noms de base de données sont modifiés de manière plus étroitement conforme aux conventions de style de nom C#.
-Force Remplacer les fichiers existants.
-NoOnConfiguring Ne générez pas DbContext.OnConfiguring.
-NoPluralize N’utilisez pas le pluralisateur.

Les paramètres courants sont répertoriés ci-dessus.

Exemple :

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

Exemple qui crée uniquement les tables sélectionnées et crée le contexte dans un dossier distinct avec un nom et un espace de noms spécifiés :

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models -Tables "Blog","Post" -ContextDir Context -Context BlogContext -ContextNamespace New.Namespace

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

Scaffold-DbContext "Name=ConnectionStrings:Blogging" Microsoft.EntityFrameworkCore.SqlServer

Script-DbContext

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

Paramètres :

Paramètre Description
-Output <String> Fichier dans lequel écrire le résultat.

Les paramètres courants sont répertoriés ci-dessus.

Script-Migration

Génère un script SQL qui applique toutes les modifications d’une migration sélectionnée vers une autre migration sélectionnée.

Paramètres :

Paramètre Description
-From <String> 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 <String> Migration de fin. Valeur par défaut de la dernière migration.
-Idempotent Générez un script qui peut être utilisé sur une base de données à n’importe quelle migration.
-NoTransactions Ne générez pas d’instructions de transaction SQL.
-Output <String> Fichier dans lequel écrire le résultat. SI ce paramètre est omis, le fichier est créé avec un nom généré dans le même dossier que les fichiers runtime de l’application, par exemple : /obj/Debug/netcoreapp2.1/ghbkztfz.sql/.

Les paramètres courants sont répertoriés ci-dessus.

Conseil

Les paramètres To, Fromet Output prennent en charge l’expansion de tabulation.

L’exemple suivant crée un script pour la migration InitialCreate (à partir d’une base de données sans migrations), à l’aide du nom de migration.

Script-Migration 0 InitialCreate

L’exemple suivant crée un script pour toutes les migrations après la migration InitialCreate, à l’aide de l’ID de migration.

Script-Migration 20180904195021_InitialCreate

Update-Database

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

Paramètre Description
-Migration <String> 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.
-Connection <String> Chaîne de connexion à la base de données. La valeur par défaut est celle spécifiée dans AddDbContext ou OnConfiguring.

Les paramètres courants sont répertoriés ci-dessus.

Conseil

Le paramètre Migration prend en charge l’extension de tabulation.

L’exemple suivant rétablit toutes les migrations.

Update-Database 0

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 :

Update-Database InitialCreate
Update-Database 20180904195021_InitialCreate -Connection your_connection_string

Ressources supplémentaires