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

  • Artículo

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, las aplican y generan código para un modelo según 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 en su lugar usar las herramientas de línea de comandos de EF Core. 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 la 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 la versión de las herramientas que está usando):


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

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 el de inicio.
  • Aprenda a usar las herramientas con bibliotecas de clases de .NET Standard.
  • Para los proyectos de ASP.NET Core, establezca el entorno.

Proyecto de destino y de 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 manera 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 parámetro -Project.

  • 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 en el Explorador de soluciones es el proyecto de inicio. Puede especificar un proyecto diferente como proyecto de inicio mediante el parámetro -StartupProject.

El proyecto de inicio y el proyecto de destino suelen ser el mismo. 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 de .NET Core o una aplicación web hace referencia a la biblioteca de clases.

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

Otras plataformas de destino

Las herramientas de la 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, es lo que sucede en las aplicaciones de Xamarin y de la 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 sea actuar como proyecto de inicio para las herramientas. Este proyecto de inicio puede ser un proyecto ficticio sin código real, ya que solo es necesario para proporcionar un destino para las herramientas.

¿Por qué se necesita un proyecto ficticio? Como se ha mencionado antes, las herramientas tienen que ejecutar código de aplicación en tiempo de diseño. Para hacerlo, 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 tanto, .NET Standard no es suficiente para que las herramientas de EF Core ejecuten el 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 proyectos de ASP.NET Core en la línea de comandos. Este 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, este parámetro es necesario.
-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> El proyecto de inicio. Si se omite este parámetro, el Proyecto de inicio en 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 Get-Help de PowerShell.

Sugerencia

Los parámetros Context, Project y StartupProject admiten la expansión de tabulación.

Agregar migración

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> Directorio que se 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 que se generen desde el directorio raíz.

Los parámetros comunes se enumeran arriba.

Migración en conjunto

Crea un archivo ejecutable para actualizar la base de datos.

Parámetros:

Parámetro Descripción
-Output <String> Ruta 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 realiza la agrupación.
-Framework <String> Marco de destino. El valor predeterminado es el primero del proyecto.

Los parámetros comunes se enumeran arriba.

Drop-Database

Quita la base de datos.

Parámetros:

Parámetro Descripción
-WhatIf Mostrar qué base de datos se va a quitar, pero no quitarla.

Los parámetros comunes se enumeran arriba.

Get-DbContext

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

Los parámetros comunes se enumeran arriba.

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 la especificada en AddDbContext u OnConfiguring.
-NoConnect No se conecte a la base de datos.

Los parámetros comunes se enumeran arriba.

Optimize-DbContext

Genera una versión compilada del modelo que usa DbContext.

Para más información, vea Modelos compilados.

Parámetros:

Parámetro Descripción
-OutputDir <String> Directorio en el que se van a colocar los 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 que se generen desde el espacio de nombres raíz y el directorio de salida más CompiledModels.

Los parámetros comunes se enumeran arriba.

En el ejemplo siguiente se usan los valores predeterminados y funciona si solo hay un 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 un espacio de nombres independientes:

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

Remove-Migration

Quita la última migración (revierte los cambios de código que se realizaron 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 arriba.

Scaffold-DbContext

Genera código para los tipos de entidad DbContext y para una base de datos. Para que Scaffold-DbContext genere 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=<nombre de la cadena de conexión>. En ese caso, el nombre procede de los orígenes de configuración que están configurados 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 archivo DbContext. 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 que se genere desde el espacio de nombres raíz y el directorio de salida.
-ContextNamespace <String> Espacio de nombres que se va a usar para la clase DbContext generada. Nota: invalida -Namespace.
-Context <String> Nombre de la clase DbContext 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 mediante 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 arriba.

Ejemplo:

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

Ejemplo que solo aplica scaffolding 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 a partir de 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 arriba.

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> La migración final. Establece el valor predeterminado a 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 arriba.

Sugerencia

Los parámetros To, From y Output admiten la expansión de tabulación.

En el ejemplo siguiente se crea un script para la migración InitialCreate (desde una base de datos sin migraciones) 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 id. de migración.

Script-Migration 20180904195021_InitialCreate

Update-Database

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

Parámetro Descripción
-Migration <String> La 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 arriba.

Sugerencia

El parámetro Migration 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. En el primero se usa el nombre de la migración y en el segundo el identificador de migración y una conexión especificada:

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

Recursos adicionales