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

Les outils PMC (Package Manager Console, ou console de gestionnaire de packages) pour Entity Framework Core effectuent des tâches de développement au moment du design. Par exemple, ils créent des 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 packages. Ces outils fonctionnent avec les projets .NET Framework et .NET.

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

Warning

Cet article utilise une base de données locale qui ne nécessite pas l’authentification des utilisateurs. Les applications de production doivent utiliser le flux d’authentification le plus sécurisé disponible. Pour plus d’informations sur l’authentification pour les applications de test et de production déployées, consultez Flux d’authentification sécurisés.

Installer les outils

Installez les outils de la console du gestionnaire de packages en exécutant la commande suivante dans la console du gestionnaire de packages :

Install-Package Microsoft.EntityFrameworkCore.Tools

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

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.>

Utiliser les 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 les projets ASP.NET Core, définissez l’environnement.

Projets cible et de démarrage

Les commandes font référence à un projet et à un projet de démarrage.

• 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 la console du gestionnaire de packages 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 démarrage 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 démarrage 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 un seul et même projet. Scénario classique dans lequel ce sont des projets distincts :

• Le contexte EF Core et les classes d’entité se trouvent dans une bibliothèque de classes .NET.
• Une application console .NET 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 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 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 ou .NET Framework dont seul l’objectif est d’agir en tant que projet de démarrage pour les outils. Le projet peut être un projet factice sans code réel ; il est nécessaire seulement pour fournir une cible aux outils.

Important

Xamarin.Android, Xamarin.iOS, Xamarin.Mac sont désormais intégrés directement à .NET (à partir de .NET 6) en tant que .NET pour Android, .NET pour iOS et .NET pour macOS. Si vous créez avec ces types de projets aujourd’hui, ils doivent être mis à niveau vers des projets de style SDK .NET pour une prise en charge continue. Pour plus d’informations sur la mise à niveau de projets Xamarin vers .NET, consultez la documentation Upgrade from Xamarin to .NET & .NET MAUI documentation.

Pourquoi un projet factice est-il nécessaire ? Comme mentionné précédemment, les outils doivent exécuter du code d’application au moment de la conception. Pour ce faire, ils doivent utiliser le runtime .NET ou .NET Framework. Lorsque le modèle EF Core se trouve dans un projet qui cible .NET ou .NET Framework, les outils EF Core empruntent le runtime à partir du projet. Mais ce n'est pas possible 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 et allez utiliser comme projet de démarrage constitue 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. Cet élément et tous les arguments supplémentaires sont transmis dans Program.CreateHostBuilder.

Update-Database -Args '--environment Production'

Common parameters

La table suivante présente les paramètres communs à toutes les commandes EF Core :

Parameter	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>	Le projet cible. Si ce paramètre est omis, le projet par défaut pour console du gestionnaire de packages est utilisé comme projet cible.
-StartupProject <String>	Le 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 PowerShell Get-Help.

Tip

Les paramètres Context, Project et StartupProject prennent en charge le développement par tabulation.

Add-Migration

Ajoute une nouvelle migration.

Parameters:

Parameter	Description
-Name <String>	Nom de la migration. Il s’agit d’un paramètre positionnel 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.

Bundle-Migration

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

Parameters:

Parameter	Description
-Output <String>	Le chemin d'accès d’un 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 la machine.
-TargetRuntime <String>	Runtime cible pour lequel créer un bundle.
-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.

Parameters:

Parameter	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 extraie des informations sur les types DbContext disponibles.

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

Get-Migration

Répertorie les migrations disponibles.

Parameters:

Parameter	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 se connecte 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.

Parameters:

Parameter	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.

Note

Actuellement, les outils PMC ne prennent pas en charge la génération de code requis pour la compilation NativeAOT et les requêtes précompilées.

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).

Parameters:

Parameter	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 que Scaffold-DbContext génère un type d’entité, la table de base de données doit avoir une clé primaire.

Parameters:

Parameter	Description
-Connection <String>	Chaîne de connexion à la base de données. La valeur peut être name=<name of connection string>. Dans ce cas, le nom provient des sources de configuration définies pour le projet. Il s’agit d’un paramètre positionnel 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 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. Valeurs par défaut à générer à partir de l’espace de noms racine et du répertoire de sortie.
-ContextNamespace <String>	L'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 lesquelles générer 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 lesquelles générer des types d’entités. Vous pouvez inclure des tables ou des vues dans un schéma spécifique à l’aide des formats « 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, de vue, de séquence et de colonne exactement tels qu'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 pluraliseur :

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

Example:

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

Exemple qui structure 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 le chaîne de connexion à l’aide de Configuration.

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

Script-DbContext

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

Parameters:

Parameter	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.

Parameters:

Parameter	Description
-From <String>	Migration de départ. Les migrations peuvent être identifiées par un nom ou un ID. Le chiffre 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.

Tip

Les paramètres To, From et Output prennent en charge le développement par 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.

Parameter	Description
-Migration <String>	Migration cible. Les migrations peuvent être identifiées par un nom ou un ID. Le chiffre 0 est un cas spécial qui signifie avant la première 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.

Tip

Le paramètre Migration prend en charge le développement par 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 la migration ainsi qu'une connexion spécifiée :

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

Additional resources

• Migrations
• Reverse Engineering
• Compiled models