Referencia de las herramientas de Entity Framework Core: CLI de .NET Core

Las herramientas de la 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, aplican migraciones y generan código para un modelo basado en 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 usar las herramientas de consola del Administrador de paquetes en lugar de las herramientas de la CLI. Herramientas de consola del Administrador de paquetes automáticamente:

  • Funciona con el proyecto actual seleccionado en la consola del Administrador de paquetes sin necesidad de cambiar manualmente los directorios.
  • Abre los archivos generados por un comando una vez completado el comando.
  • Proporciona la finalización de 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 una 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, deberá agregarle el Microsoft.EntityFrameworkCore.Design paquete.

dotnet add package Microsoft.EntityFrameworkCore.Design

Comprobar la 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. Instale una versión específica anexando --version <VERSION> al comando . Consulte 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 un proyecto diferente como proyecto de destino mediante la --project opción .

  • El proyecto de inicio es el que las herramientas compilan y ejecutan. Las herramientas deben 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 un proyecto diferente como proyecto de inicio mediante la --startup-project opción .

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 de .NET Core o una aplicación web 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 la CLI funcionan con proyectos de .NET Core y proyectos de .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 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. 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 de .NET real; 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. Este y los argumentos adicionales se pasan a Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Sugerencia

El -- token dirige dotnet ef a tratar todo lo que sigue como argumento y no intenta analizarlos como opciones. Los argumentos adicionales no utilizados por dotnet ef se reenvía a la aplicación.

Opciones comunes

Opción Short Descripción
--json Mostrar 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 necesaria.
--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> Moniker de plataforma de destino para la plataforma de destino. Use cuando el archivo de proyecto especifique varias plataformas de destino y quiera seleccionar una de ellas.
--configuration <CONFIGURATION> La configuración de compilación, por ejemplo: Debug o Release.
--runtime <IDENTIFIER> Identificador del entorno de ejecución de destino para el que se van a restaurar los paquetes. Para obtener una lista de identificadores de tiempo de ejecución (RID), consulte el catálogo de RID.
--no-build No compile 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 Salida de prefijo con nivel.

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 confirmes.
--dry-run Muestra qué base de datos se quitaría, pero no la quites.

Las opciones comunes se enumeran anteriormente.

dotnet ef database update

Novedades 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. El primero usa el nombre de la migración y el segundo usa 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 DbContext tipo.

Las opciones comunes se enumeran anteriormente.

dotnet ef dbcontext list

Enumera los tipos disponibles DbContext .

Las opciones comunes se enumeran anteriormente.

dotnet ef dbcontext optimize

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

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

Opciones:

Opción Short Descripción
--output-dir <PATH> -o Directorio en el que se colocarán 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 generado a partir del 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 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 independiente y un espacio de nombres:

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

dotnet ef dbcontext scaffold

Genera código para los tipos de DbContext entidad y 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=<name 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 DbContext clase que se va a generar.
--context-dir <PATH> Directorio en el que se va a colocar el archivo de DbContext clase. 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 generada DbContext . Nota: invalida --namespace.
--force -f Sobrescribe los archivos existentes.
--output-dir <PATH> -o Directorio en el que se colocarán 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 generado a partir del 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 para --schema 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 Las 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 con 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 nombre de C#.
--no-onconfiguring Suprime la generación del OnConfiguring método en la clase generada DbContext .
--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 aplican 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 OnConfiguring método. Esto puede ser útil cuando desea configurar DbContext fuera de la clase . Por ejemplo, ASP.NET Core aplicaciones normalmente se configuran 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 desde 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 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 <NAMESPACE> -n Espacio de nombres que se va a usar para las clases generadas. El valor predeterminado es generado a partir del directorio de salida.

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 de acceso 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 va a agrupar.

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 el especificado 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, revierte los cambios de código que se realizaron para la migración más reciente.

Opciones:

Opción Short Descripción
--force -f Revierta la migración más reciente, revirtiendo los cambios de código y de base de datos que se realizaron para la migración más reciente. Continúa revieriendo 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 un script SQL a partir de 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