Herramientas de Entity Framework Core: CLI de .NET Core

  • Artículo

Las herramientas de interfaz de la línea de comandos (CLI) 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 son una extensión para el comando dotnet multiplataforma, que forma parte del SDK de .NET Core. Estas herramientas funcionan con proyectos de .NET Core.

Al usar Visual Studio, considere la posibilidad de utilizar las herramientas de la consola del Administrador de paquetes en lugar de las herramientas de la CLI. De forma automática, las herramientas de la consola del Administrador de paquetes:

  • Trabajan con el proyecto actualmente seleccionado en la consola del Administrador de paquetes, sin necesidad de cambiar manualmente entre directorios.
  • Abren los archivos generados por un comando una vez que se completa el comando.
  • Proporcionan la finalización mediante tabulación de comandos, parámetros, nombres de proyecto, tipos de contexto y nombres de migración.

Instalación de las herramientas

dotnet ef se puede instalar como herramienta global o local. La mayoría de los desarrolladores prefieren instalar dotnet ef como herramienta global con el siguiente comando:

dotnet tool install --global dotnet-ef

Para usarlo como herramienta local, restaure las dependencias de un proyecto que lo declare como dependencia de herramientas mediante un archivo de manifiesto de herramientas.

Actualice la herramienta mediante el siguiente comando:

dotnet tool update --global dotnet-ef

Para poder usar las herramientas en un proyecto específico, tendrá que agregarles el paquete Microsoft.EntityFrameworkCore.Design.

dotnet add package Microsoft.EntityFrameworkCore.Design

Verificar instalación

Ejecute los siguientes comandos para comprobar que las herramientas de la CLI de EF Core están instaladas correctamente:

dotnet ef

La salida del comando identifica la versión de las herramientas en uso:


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

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

<Usage documentation follows, not shown.>

Actualización de las herramientas

Use dotnet tool update --global dotnet-ef para actualizar las herramientas globales a la versión más reciente disponible. Si tiene instaladas las herramientas localmente en el proyecto, use dotnet tool update dotnet-ef. Para instalar una versión específica, anexe --version <VERSION> al comando. Vea la sección Actualización de la documentación de la herramienta dotnet para obtener más detalles.

Uso de las herramientas

Antes de usar las herramientas, es posible que tenga que crear un proyecto de inicio o establecer el entorno.

Proyecto de destino y proyecto 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 forma predeterminada, el proyecto del directorio actual es el proyecto de destino. Puede especificar otro proyecto como proyecto de destino mediante la opción --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 del directorio actual es el proyecto de inicio. Puede especificar otro proyecto como proyecto de inicio mediante la opción --startup-project.

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 CLI funcionan con proyectos de .NET Core y .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 la Plataforma universal de Windows. En esos casos, puede crear un proyecto de aplicación de consola de .NET Core 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 ello, deben usar el entorno de ejecución de .NET Core. 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 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.

dotnet ef database update -- --environment Production

Sugerencia

El token -- indica adotnet ef que trate todo lo que sigue como si fuera un argumento y no intente analizarlo como opciones. Los argumentos adicionales no utilizados por dotnet ef se reenvían a la aplicación.

Opciones comunes

Opción Short Descripción
--json Muestran la salida JSON.
--context <DBCONTEXT> -c La clase DbContext que se va a usar. Nombre de clase solo o completo con espacios de nombres. Si se omite esta opción, EF Core encontrará la clase de contexto. Si hay varias clases de contexto, esta opción es obligatoria.
--project <PROJECT> -p Ruta de acceso relativa a la carpeta del proyecto de destino. El valor predeterminado es la carpeta actual.
--startup-project <PROJECT> -s Ruta de acceso relativa a la carpeta del proyecto de inicio. El valor predeterminado es la carpeta actual.
--framework <FRAMEWORK> El moniker de la plataforma de destino para la plataforma de destino. Se usa cuando el archivo del proyecto especifica varias plataformas de destino y se quiere seleccionar una de ellas.
--configuration <CONFIGURATION> La configuración de compilación, por ejemplo Debug o Release.
--runtime <IDENTIFIER> El identificador del tiempo de ejecución de destino para el que restaurar los paquetes. Para obtener una lista de identificadores de tiempo de ejecución (RID), consulte el catálogo de RID.
--no-build No compilar el proyecto. Está pensado para usarse cuando la compilación está actualizada.
--help -h Muestra información de ayuda.
--verbose -v Mostrar resultado detallado.
--no-color No colorear la salida.
--prefix-output Agregar nivel como prefijo a la salida.

Los argumentos adicionales se pasan a la aplicación.

dotnet ef database drop

Elimina la base de datos.

Opciones:

Opción Short Descripción
--force -f No confirmar.
--dry-run Mostrar qué base de datos se va a quitar, pero no quitarla.

Las opciones comunes se enumeran anteriormente.

dotnet ef database update

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

Argumentos:

Argumento Descripción
<MIGRATION> 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.

Opciones:

Opción Descripción
--connection <CONNECTION> La cadena de conexión a la base de datos. El valor predeterminado es el especificado en AddDbContext o OnConfiguring.

Las opciones comunes se enumeran anteriormente.

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:

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

dotnet ef dbcontext info

Obtiene información sobre un tipo DbContext.

Las opciones comunes se enumeran anteriormente.

dotnet ef dbcontext list

Enumera los tipos DbContext disponibles.

Las opciones comunes se enumeran anteriormente.

dotnet ef dbcontext optimize

Genera una versión compilada del modelo que usaDbContext.

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

Opciones:

Opción Short Descripción
--output-dir <PATH> -o Directorio en el que se van a colocar los archivos. Las rutas de acceso son relativas al directorio del proyecto.
--namespace <NAMESPACE> -n 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.

Las opciones comunes se enumeran anteriormente.

En el ejemplo siguiente se usa la configuración predeterminada y funciona si solo hay una instancia de DbContext en el proyecto:

dotnet ef dbcontext optimize

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:

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

dotnet ef dbcontext scaffold

Genera código para una instancia de DbContext y tipos de entidad para una base de datos. Para que este comando genere un tipo de entidad, la tabla de base de datos debe tener una clave principal.

Argumentos:

Argumento Descripción
<CONNECTION> 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.
<PROVIDER> Proveedor que se va a usar. Normalmente, este es el nombre del paquete NuGet, por ejemplo: Microsoft.EntityFrameworkCore.SqlServer.

Opciones:

Opción Short Descripción
--data-annotations -d Use atributos para configurar el modelo (siempre que sea posible). Si se omite esta opción, solo se usa la API fluida.
--context <NAME> -c Nombre de la clase DbContext que se va a generar.
--context-dir <PATH> Directorio en el que se va a colocar el archivo de clase DbContext. Las rutas de acceso son relativas al directorio del proyecto. Los espacios de nombres se derivan de los nombres de carpeta.
--context-namespace <NAMESPACE> Espacio de nombres que se va a usar para la clase DbContext generada. Nota: Invalida --namespace.
--force -f Sobrescribe los archivos existentes.
--output-dir <PATH> -o Directorio en el que se van a colocar los archivos de clase de entidad. Las rutas de acceso son relativas al directorio del proyecto.
--namespace <NAMESPACE> -n 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.
--schema <SCHEMA_NAME>... Esquemas de tablas y vistas para los que se van a generar tipos de entidad. Para especificar varios esquemas, repita --schema para cada uno. Si se omite esta opción, 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.
--table <TABLE_NAME>... -t Tablas y vistas para las que se van a generar tipos de entidad. Para especificar varias tablas, repita -t o --table para cada una. Las tablas o vistas de un esquema específico se pueden incluir mediante el formato "schema.table" o "schema.view". Si se omite esta opción, se incluyen todas las tablas y vistas.
--use-database-names Use nombres de tabla, vista, secuencia y columna exactamente como aparecen en la base de datos. Si se omite esta opción, los nombres de base de datos se cambian para ajustarse más estrechamente a las convenciones de estilo de nombres de C#.
--no-onconfiguring Suprime la generación del método OnConfiguring en la clase DbContext generada.
--no-pluralize No use el pluralizador.

Las opciones comunes se enumeran anteriormente.

En el ejemplo siguiente se aplica scaffolding a todos los esquemas y tablas, y se colocan los nuevos archivos en la carpeta Models.

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

En el ejemplo siguiente solo se aplica scaffolding a las tablas seleccionadas y se crea el contexto en una carpeta independiente con un nombre y un espacio de nombres especificados:

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

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

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

En el ejemplo siguiente se omite el scaffolding de un método OnConfiguring. Esto puede ser útil cuando se quiere configurar DbContext fuera de la clase. Por ejemplo, las aplicaciones de ASP.NET Core suelen configurarlo en 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

Genera un script SQL a partir de DbContext. Omite las migraciones.

Opciones:

Opción Short Descripción
--output <FILE> -o Archivo en el que se va a escribir el resultado.

Las opciones comunes se enumeran anteriormente.

dotnet ef migrations add

Agrega una nueva migración.

Argumentos:

Argumento Descripción
<NAME> Nombre de la migración.

Opciones:

Opción Short Descripción
--output-dir <PATH> -o 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 <NAMESPACE> -n Espacio de nombres que se va a usar para las clases generadas. El valor predeterminado es que se generen desde el directorio raíz.

Las opciones comunes se enumeran anteriormente.

dotnet ef migrations bundle

Crea un archivo ejecutable para actualizar la base de datos.

Opciones:

Opción Short Descripción
--output <FILE> -o Ruta del archivo ejecutable que se va a crear.
--force -f Sobrescribe los archivos existentes.
--self-contained Incluya también el entorno de ejecución de .NET para que no sea necesario instalarlo en la máquina.
--target-runtime <RUNTIME_IDENTIFIER> -r Tiempo de ejecución de destino para el que se realiza la agrupación.

Las opciones comunes se enumeran anteriormente.

dotnet ef migrations has-pending-model-changes

Nota:

Este comando se agregó en EF Core 8.0.

Comprueba si se han realizado cambios en el modelo desde la última migración.

Opciones:

Las opciones comunes se enumeran anteriormente.

dotnet ef migrations list

Enumera las migraciones disponibles.

Opciones:

Opción Descripción
--connection <CONNECTION> La cadena de conexión a la base de datos. El valor predeterminado es la especificada en AddDbContext o OnConfiguring.
--no-connect No se conecte a la base de datos.

Las opciones comunes se enumeran anteriormente.

dotnet ef migrations remove

Quita la última migración, lo que revierte los cambios de código que se han realizado para la migración más reciente.

Opciones:

Opción Short Descripción
--force -f Quita la última migración, lo que revierte los cambios de código y de la base de datos que se han realizado para la migración más reciente. Continúa para revertir solo los cambios de código si se produce un error al conectarse a la base de datos.

Las opciones comunes se enumeran anteriormente.

dotnet ef migrations script

Genera script SQL a partir de las migraciones.

Argumentos:

Argumento Descripción
<FROM> 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> La migración final. El valor predeterminado es la última migración.

Opciones:

Opción Short Descripción
--output <FILE> -o Archivo en el que se va a escribir el script.
--idempotent -i Genere un script que se pueda usar en una base de datos en cualquier migración.
--no-transactions No genere instrucciones de transacción SQL.

Las opciones comunes se enumeran anteriormente.

En el ejemplo siguiente se crea un script para la migración InitialCreate:

dotnet ef migrations script 0 InitialCreate

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

dotnet ef migrations script 20180904195021_InitialCreate

Recursos adicionales