Referencia de herramientas de Entity Framework Core: consola del Administrador de paquetes en Visual Studio

Las herramientas de la consola del Administrador de paquetes (PMC) para Entity Framework Core realizan tareas de desarrollo en tiempo de diseño. Por ejemplo, crean migraciones, aplican migraciones y generan código para un modelo basado en una base de datos existente. Los comandos se ejecutan dentro de Visual Studio mediante la consola del Administrador de paquetes. Estas herramientas funcionan con proyectos de .NET Framework y .NET Core.

Si no usa Visual Studio, se recomienda usar las herramientas de línea de comandos de EF Core en su lugar. Las herramientas de la CLI de .NET Core son multiplataforma y se ejecutan dentro de un símbolo del sistema.

Instalación de las herramientas

Instale las herramientas de consola del Administrador de paquetes ejecutando el siguiente comando en la consola del Administrador de paquetes:

Install-Package Microsoft.EntityFrameworkCore.Tools

Actualice las herramientas mediante la ejecución del siguiente comando en la consola del Administrador de paquetes.

Update-Package Microsoft.EntityFrameworkCore.Tools

Comprobación de la instalación

Para comprobar que las herramientas están instaladas, ejecute este comando:

Get-Help about_EntityFrameworkCore

La salida tiene este aspecto (no indica qué versión de las herramientas usa):


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

TOPIC
    about_EntityFrameworkCore

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

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

Uso de las herramientas

Antes de usar las herramientas:

  • Comprenda la diferencia entre el proyecto de destino y de inicio.
  • Aprenda a usar las herramientas con bibliotecas de clases de .NET Standard.
  • Para ASP.NET Core proyectos, establezca el entorno.

Proyecto de destino e inicio

Los comandos hacen referencia a un proyecto y a un proyecto de inicio.

  • El proyecto también se conoce como proyecto de destino porque es donde los comandos agregan o quitan archivos. De forma predeterminada, el proyecto Predeterminado seleccionado en la consola del Administrador de paquetes es el proyecto de destino. Puede especificar un proyecto diferente como proyecto de destino mediante el -Project parámetro .

  • El proyecto de inicio es el que las herramientas compilan y ejecutan. Las herramientas tienen que ejecutar código de aplicación en tiempo de diseño para obtener información sobre el proyecto, como la cadena de conexión de la base de datos y la configuración del modelo. De forma predeterminada, el proyecto de inicio de Explorador de soluciones es el proyecto de inicio. Puede especificar un proyecto diferente como proyecto de inicio mediante el -StartupProject parámetro .

El proyecto de inicio y el proyecto de destino suelen ser el mismo proyecto. Un escenario típico en el que son proyectos independientes es cuando:

  • Las clases de entidad y contexto de EF Core se encuentran en una biblioteca de clases de .NET Core.
  • Una aplicación de consola o aplicación web de .NET Core hace referencia a la biblioteca de clases.

También es posible colocar el código de migraciones en una biblioteca de clases independiente del contexto de EF Core.

Otras plataformas de destino

Las herramientas de consola del Administrador de paquetes funcionan con proyectos de .NET Core o .NET Framework. Es posible que las aplicaciones que tengan el modelo de EF Core en una biblioteca de clases de .NET Standard no tengan un proyecto de .NET Core o .NET Framework. Por ejemplo, esto es cierto en las aplicaciones de Xamarin y Plataforma universal de Windows. En tales casos, puede crear un proyecto de aplicación de consola de .NET Core o .NET Framework cuyo único propósito es actuar como proyecto de inicio para las herramientas. El proyecto puede ser un proyecto ficticio sin código real; solo es necesario proporcionar un destino para las herramientas.

¿Por qué se requiere un proyecto ficticio? Como se mencionó anteriormente, las herramientas tienen que ejecutar código de aplicación en tiempo de diseño. Para ello, deben usar el entorno de ejecución de .NET Core o .NET Framework. Cuando el modelo de EF Core está en un proyecto que tiene como destino .NET Core o .NET Framework, las herramientas de EF Core toman prestado el tiempo de ejecución del proyecto. No pueden hacerlo si el modelo de EF Core está en una biblioteca de clases de .NET Standard. .NET Standard no es una implementación real de .NET; es una especificación de un conjunto de API que las implementaciones de .NET deben admitir. Por lo tanto, .NET Standard no es suficiente para que las herramientas de EF Core ejecuten código de aplicación. El proyecto ficticio que se crea para usarlo como proyecto de inicio proporciona una plataforma de destino concreta en la que las herramientas pueden cargar la biblioteca de clases de .NET Standard.

entorno de ASP.NET Core

Puede especificar el entorno para ASP.NET Core proyectos en la línea de comandos. Esto y los argumentos adicionales se pasan a Program.CreateHostBuilder.

Update-Database -Args '--environment Production'

Parámetros comunes

En la tabla siguiente se muestran los parámetros comunes a todos los comandos de EF Core:

Parámetro Descripción
-Context <String> La clase DbContext que se va a usar. Nombre de clase solo o completo con espacios de nombres. Si se omite este parámetro, EF Core busca la clase de contexto. Si hay varias clases de contexto, se requiere este parámetro.
-Project <String> El proyecto de destino. Si se omite este parámetro, el proyecto predeterminado para la consola del Administrador de paquetes se usa como proyecto de destino.
-StartupProject <String> Proyecto de inicio. Si se omite este parámetro, el proyecto de inicio de las propiedades de la solución se usa como proyecto de destino.
-Args <String> Argumentos pasados a la aplicación.
-Verbose Mostrar resultado detallado.

Para mostrar información de ayuda sobre un comando, use el comando de Get-Help PowerShell.

Sugerencia

Los Contextparámetros , Projecty StartupProject admiten la expansión de tabulación.

Add-Migration

Agrega una nueva migración.

Parámetros:

Parámetro Descripción
-Name <String> Nombre de la migración. Se trata de un parámetro posicional y es necesario.
-OutputDir <String> El directorio usa para generar los archivos. Las rutas de acceso son relativas al directorio del proyecto de destino. El valor predeterminado es "Migraciones".
-Namespace <String> Espacio de nombres que se va a usar para las clases generadas. El valor predeterminado es generado a partir del directorio de salida.

Los parámetros comunes se enumeran anteriormente.

Bundle-Migration

Crea un archivo ejecutable para actualizar la base de datos.

Parámetros:

Parámetro Descripción
-Output <String> Ruta de acceso del archivo ejecutable que se va a crear.
-Force Sobrescribe los archivos existentes.
-SelfContained Incluya también el entorno de ejecución de .NET para que no sea necesario instalarlo en la máquina.
-TargetRuntime <String> Tiempo de ejecución de destino para el que se va a agrupar.
-Framework <String> La plataforma de destino. El valor predeterminado es el primero del proyecto.

Los parámetros comunes se enumeran anteriormente.

Drop-Database

Quita la base de datos.

Parámetros:

Parámetro Descripción
-WhatIf Muestre qué base de datos se quitaría, pero no la quite.

Los parámetros comunes se enumeran anteriormente.

Get-DbContext

Muestra y obtiene información sobre los tipos disponibles DbContext .

Los parámetros comunes se enumeran anteriormente.

Get-Migration

Enumera las migraciones disponibles.

Parámetros:

Parámetro Descripción
-Connection <String> La cadena de conexión a la base de datos. El valor predeterminado es el especificado en AddDbContext o OnConfiguring.
-NoConnect No se conecte a la base de datos.

Los parámetros comunes se enumeran anteriormente.

Optimize-DbContext

Genera una versión compilada del modelo utilizado por .DbContext

Consulte Modelos compilados para obtener más información.

Parámetros:

Parámetro Descripción
-OutputDir <String> Directorio en el que se van a colocar archivos. Las rutas de acceso son relativas al directorio del proyecto.
-Namespace <String> Espacio de nombres que se va a usar para todas las clases generadas. El valor predeterminado es generado a partir del espacio de nombres raíz y el directorio de salida más CompiledModels.

Los parámetros comunes se enumeran anteriormente.

En el ejemplo siguiente se usan los valores predeterminados y funciona si solo hay uno DbContext en el proyecto:

Optimize-DbContext

En el ejemplo siguiente se optimiza el modelo para el contexto con el nombre especificado y se coloca en una carpeta y espacio de nombres independiente:

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

Remove-Migration

Quita la última migración (revierte los cambios de código realizados para la migración).

Parámetros:

Parámetro Descripción
-Force Revierta la migración (revierta los cambios que se aplicaron a la base de datos).

Los parámetros comunes se enumeran anteriormente.

Scaffold-DbContext

Genera código para los tipos de entidad DbContext y para una base de datos. Para Scaffold-DbContext generar un tipo de entidad, la tabla de base de datos debe tener una clave principal.

Parámetros:

Parámetro Descripción
-Connection <String> La cadena de conexión a la base de datos. Para los proyectos de ASP.NET Core 2.x, el valor puede ser name=<name de la cadena> de conexión. En ese caso, el nombre procede de los orígenes de configuración que se configuran para el proyecto. Se trata de un parámetro posicional y es necesario.
-Provider <String> Proveedor que se va a usar. Normalmente, este es el nombre del paquete NuGet, por ejemplo: Microsoft.EntityFrameworkCore.SqlServer. Se trata de un parámetro posicional y es necesario.
-OutputDir <String> Directorio en el que se van a colocar los archivos de clase de entidad. Las rutas de acceso son relativas al directorio del proyecto.
-ContextDir <String> Directorio en el que se va a colocar el DbContext archivo. Las rutas de acceso son relativas al directorio del proyecto.
-Namespace <String> Espacio de nombres que se va a usar para todas las clases generadas. El valor predeterminado es generado a partir del espacio de nombres raíz y el directorio de salida.
-ContextNamespace <String> Espacio de nombres que se va a usar para la clase generada DbContext . Nota: invalida -Namespace.
-Context <String> Nombre de la DbContext clase que se va a generar.
-Schemas <String[]> Esquemas de tablas y vistas para los que se van a generar tipos de entidad. Si se omite este parámetro, se incluyen todos los esquemas. Si se usa esta opción, todas las tablas y vistas de los esquemas se incluirán en el modelo, aunque no se incluyan explícitamente mediante -Table.
-Tables <String[]> Tablas y vistas para las que se van a generar tipos de entidad. Las tablas o vistas de un esquema específico se pueden incluir con el formato "schema.table" o "schema.view". Si se omite este parámetro, se incluyen todas las tablas y vistas.
-DataAnnotations Use atributos para configurar el modelo (siempre que sea posible). Si se omite este parámetro, solo se usa la API fluida.
-UseDatabaseNames Use nombres de tabla, vista, secuencia y columna exactamente como aparecen en la base de datos. Si se omite este parámetro, los nombres de base de datos se cambian para ajustarse más estrechamente a las convenciones de estilo de nombre de C#.
-Force Sobrescribe los archivos existentes.
-NoOnConfiguring No genere DbContext.OnConfiguring.
-NoPluralize No use el pluralizador.

Los parámetros comunes se enumeran anteriormente.

Ejemplo:

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

Ejemplo que aplica scaffolding solo a las tablas seleccionadas y crea el contexto en una carpeta independiente con un nombre y un espacio de nombres especificados:

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

En el ejemplo siguiente se lee la cadena de conexión de la configuración del proyecto posiblemente establecida mediante la herramienta Administrador de secretos.

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

Script-DbContext

Genera un script SQL desde DbContext. Omite las migraciones.

Parámetros:

Parámetro Descripción
-Output <String> Archivo en el que se va a escribir el resultado.

Los parámetros comunes se enumeran anteriormente.

Script-Migration

Genera un script SQL que aplica todos los cambios de una migración seleccionada a otra migración seleccionada.

Parámetros:

Parámetro Descripción
-From <String> La migración inicial. Las migraciones se pueden identificar por nombre o por identificador. El número 0 es un caso especial que significa antes de la primera migración. El valor predeterminado es 0.
-To <String> Migración final. El valor predeterminado es la última migración.
-Idempotent Genere un script que se pueda usar en una base de datos en cualquier migración.
-NoTransactions No genere instrucciones de transacción SQL.
-Output <String> Archivo en el que se va a escribir el resultado. SI se omite este parámetro, el archivo se crea con un nombre generado en la misma carpeta que los archivos en tiempo de ejecución de la aplicación, por ejemplo: /obj/Debug/netcoreapp2.1/ghbkztfz.sql/.

Los parámetros comunes se enumeran anteriormente.

Sugerencia

Los Toparámetros , Fromy Output admiten la expansión de tabulaciones.

En el ejemplo siguiente se crea un script para la migración InitialCreate (desde una base de datos sin ninguna migración), con el nombre de la migración.

Script-Migration 0 InitialCreate

En el ejemplo siguiente se crea un script para todas las migraciones después de la migración InitialCreate, mediante el identificador de migración.

Script-Migration 20180904195021_InitialCreate

Update-Database

Novedades la base de datos a la última migración o a una migración especificada.

Parámetro Descripción
-Migration <String> Migración de destino. Las migraciones se pueden identificar por nombre o por identificador. El número 0 es un caso especial que significa antes de la primera migración y hace que se reviertan todas las migraciones. Si no se especifica ninguna migración, el comando tiene como valor predeterminado la última migración.
-Connection <String> La cadena de conexión a la base de datos. El valor predeterminado es el especificado en AddDbContext o OnConfiguring.

Los parámetros comunes se enumeran anteriormente.

Sugerencia

El Migration parámetro admite la expansión de tabulación.

En el ejemplo siguiente se revierten todas las migraciones.

Update-Database 0

En los ejemplos siguientes se actualiza la base de datos a una migración especificada. La primera usa el nombre de la migración y la segunda usa el identificador de migración y una conexión especificada:

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

Recursos adicionales