Herramientas de Entity Framework Core: CLI de .NET Core

Artículo
11/08/2024

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

dotnet ef database update -- --environment Production

Sugerencia

El token -- indica a dotnet 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>`	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.

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 utilizado por las DbContext consultas y precompila.

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`.
`--suffix <SUFFIX>`		Sufijo que se va a adjuntar al nombre de todos los archivos generados. Por ejemplo, `.g` podría usarse para indicar que estos archivos contienen código generado.
`--no-scaffold`		No genere un modelo compilado. Esto se usa cuando ya se ha generado el modelo compilado.
`--precompile-queries`		Generar consultas precompiladas. Esto es necesario para la compilación NativeAOT si el proyecto de destino contiene consultas.
`--nativeaot`		Generar código adicional en el modelo compilado necesario para la compilación NativeAOT y las consultas precompiladas

Nota:

La compatibilidad con NativeAOT y las consultas precompiladas se consideran experimentales en EF 9 y podrían cambiar drásticamente en la próxima versión.

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

Compartir a través de

Herramientas de Entity Framework Core: CLI de .NET Core

Instalación de las herramientas

Verificar instalación

Actualización de las herramientas

Uso de las herramientas

Proyecto de destino y proyecto de inicio

Otras plataformas de destino

Entorno de ASP.NET Core

Opciones comunes

`dotnet ef database drop`

`dotnet ef database update`

`dotnet ef dbcontext info`

`dotnet ef dbcontext list`

`dotnet ef dbcontext optimize`

`dotnet ef dbcontext scaffold`

`dotnet ef dbcontext script`

`dotnet ef migrations add`

`dotnet ef migrations bundle`

`dotnet ef migrations has-pending-model-changes`

`dotnet ef migrations list`

`dotnet ef migrations remove`

`dotnet ef migrations script`

Recursos adicionales

Recursos adicionales