Condividi tramite

Informazioni di riferimento sugli strumenti di Entity Framework Core - Interfaccia della riga di comando di .NET Core

  • Articolo

Gli strumenti dell'interfaccia della riga di comando per Entity Framework Core eseguono attività di sviluppo in fase di progettazione. Ad esempio, creano migrazioni, applicano migrazioni e generano codice per un modello basato su un database esistente. I comandi sono un'estensione del comando dotnet multipiattaforma, che fa parte di .NET Core SDK. Questi strumenti funzionano con i progetti .NET Core.

Quando si usa Visual Studio, è consigliabile usare gli strumenti della console Gestione pacchetti anziché gli strumenti dell'interfaccia della riga di comando. Gestione pacchetti Strumenti console:

  • Funziona con il progetto corrente selezionato nella console Gestione pacchetti senza che sia necessario cambiare manualmente le directory.
  • Apre i file generati da un comando dopo il completamento del comando.
  • Fornisce il completamento tramite tabulazione di comandi, parametri, nomi di progetto, tipi di contesto e nomi di migrazione.

Installazione degli strumenti

dotnet ef può essere installato come strumento globale o locale. La maggior parte degli sviluppatori preferisce l'installazione dotnet ef come strumento globale usando il comando seguente:

dotnet tool install --global dotnet-ef

Per usarlo come strumento locale, ripristinare le dipendenze di un progetto che lo dichiara come dipendenza degli strumenti usando un file manifesto dello strumento.

Aggiornare lo strumento usando il comando seguente:

dotnet tool update --global dotnet-ef

Prima di poter usare gli strumenti in un progetto specifico, è necessario aggiungerlo Microsoft.EntityFrameworkCore.Design .

dotnet add package Microsoft.EntityFrameworkCore.Design

Verifica l'installazione

Eseguire i comandi seguenti per verificare che gli strumenti dell'interfaccia della riga di comando di EF Core siano installati correttamente:

dotnet ef

L'output del comando identifica la versione degli strumenti in uso:


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

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

<Usage documentation follows, not shown.>

Aggiornare gli strumenti

Usare dotnet tool update --global dotnet-ef per aggiornare gli strumenti globali alla versione più recente disponibile. Se nel progetto sono installati gli strumenti in locale, usare dotnet tool update dotnet-ef. Installare una versione specifica aggiungendo --version <VERSION> al comando. Per altri dettagli, vedere la sezione Update (Aggiornamento ) della documentazione dello strumento dotnet.

Uso degli strumenti

Prima di usare gli strumenti, potrebbe essere necessario creare un progetto di avvio o impostare l'ambiente.

Progetto di destinazione e progetto di avvio

I comandi fanno riferimento a un progetto e a un progetto di avvio.

  • Il progetto è noto anche come progetto di destinazione perché è la posizione in cui i comandi aggiungono o rimuovono file. Per impostazione predefinita, il progetto nella directory corrente è il progetto di destinazione. È possibile specificare un progetto diverso come progetto di destinazione usando l'opzione --project .

  • Il progetto di avvio è quello che gli strumenti compilano ed eseguono. Gli strumenti devono eseguire il codice dell'applicazione in fase di progettazione per ottenere informazioni sul progetto, ad esempio il database stringa di connessione e la configurazione del modello. Per impostazione predefinita, il progetto nella directory corrente è il progetto di avvio. È possibile specificare un progetto diverso come progetto di avvio usando l'opzione --startup-project .

Il progetto di avvio e il progetto di destinazione sono spesso lo stesso progetto. Uno scenario tipico in cui sono progetti separati è quando:

  • Il contesto di EF Core e le classi di entità si trovano in una libreria di classi .NET Core.
  • Un'app console .NET Core o un'app Web fa riferimento alla libreria di classi.

È anche possibile inserire il codice delle migrazioni in una libreria di classi separata dal contesto di EF Core.

Altri framework di destinazione

Gli strumenti dell'interfaccia della riga di comando funzionano con progetti .NET Core e progetti .NET Framework. Le app con il modello EF Core in una libreria di classi .NET Standard potrebbero non avere un progetto .NET Core o .NET Framework. Ad esempio, questo vale per le app Xamarin e piattaforma UWP (Universal Windows Platform). In questi casi, è possibile creare un progetto di app console .NET Core il cui unico scopo è quello di fungere da progetto di avvio per gli strumenti. Il progetto può essere un progetto fittizio senza codice reale, ma è necessario solo fornire una destinazione per gli strumenti.

Perché è necessario un progetto fittizio? Come accennato in precedenza, gli strumenti devono eseguire il codice dell'applicazione in fase di progettazione. A tale scopo, è necessario usare il runtime di .NET Core. Quando il modello EF Core si trova in un progetto destinato a .NET Core o .NET Framework, gli strumenti di EF Core prendono in prestito il runtime dal progetto. Non possono farlo se il modello EF Core si trova in una libreria di classi .NET Standard. .NET Standard non è un'implementazione .NET effettiva; è una specifica di un set di API che le implementazioni di .NET devono supportare. Pertanto .NET Standard non è sufficiente per gli strumenti di EF Core per eseguire il codice dell'applicazione. Il progetto fittizio creato da usare come progetto di avvio fornisce una piattaforma di destinazione concreta in cui gli strumenti possono caricare la libreria di classi .NET Standard.

ambiente core ASP.NET

È possibile specificare l'ambiente per i progetti ASP.NET Core nella riga di comando. Questo e tutti gli argomenti aggiuntivi vengono passati a Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Suggerimento

Il -- token indirizza dotnet ef a trattare tutto ciò che segue come argomento e non cerca di analizzarli come opzioni. Eventuali argomenti aggiuntivi non usati da dotnet ef vengono inoltrati all'app.

Opzioni comuni

Opzione Short Descrizione
--json Visualizzare l'output JSON.
--context <DBCONTEXT> -c Classe DbContext da usare. Nome della classe solo o completo con spazi dei nomi. Se questa opzione viene omessa, EF Core troverà la classe di contesto. Se sono presenti più classi di contesto, questa opzione è obbligatoria.
--project <PROJECT> -p Percorso relativo alla cartella del progetto di destinazione. Il valore predefinito è la cartella corrente.
--startup-project <PROJECT> -s Percorso relativo alla cartella del progetto di avvio. Il valore predefinito è la cartella corrente.
--framework <FRAMEWORK> Moniker framework di destinazione per il framework di destinazione. Usare quando il file di progetto specifica più framework di destinazione e si vuole selezionare uno di essi.
--configuration <CONFIGURATION> Configurazione di compilazione, ad esempio: Debug o Release.
--runtime <IDENTIFIER> Identificatore del runtime di destinazione per il quale ripristinare i pacchetti. Per un elenco degli identificatori di runtime (RID, Runtime Identifier), vedere il catalogo RID.
--no-build Non compilare il progetto. Destinato a essere usato quando la compilazione è aggiornata.
--help -h Mostra informazioni della Guida.
--verbose -v Visualizzare l'output dettagliato.
--no-color Non colorare l'output.
--prefix-output Output del prefisso con livello.

Tutti gli argomenti aggiuntivi vengono passati all'applicazione.

dotnet ef database drop

Elimina il database.

Opzioni:

Opzione Short Descrizione
--force -f Non confermare.
--dry-run Visualizzare il database che verrà eliminato, ma non eliminarlo.

Le opzioni comuni sono elencate in precedenza.

dotnet ef database update

Aggiorna il database all'ultima migrazione o a una migrazione specificata.

Argomenti:

Argomento Descrizione
<MIGRATION> Migrazione di destinazione. Le migrazioni possono essere identificate in base al nome o all'ID. Il numero 0 è un caso speciale che indica prima della prima migrazione e fa sì che tutte le migrazioni vengano ripristinate. Se non viene specificata alcuna migrazione, per impostazione predefinita il comando corrisponde all'ultima migrazione.

Opzioni:

Opzione Descrizione
--connection <CONNECTION> Stringa di connessione al database. Il valore predefinito è quello specificato in AddDbContext o OnConfiguring.

Le opzioni comuni sono elencate in precedenza.

Negli esempi seguenti il database viene aggiornato a una migrazione specificata. Il primo usa il nome della migrazione e il secondo usa l'ID migrazione e una connessione specificata:

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

dotnet ef dbcontext info

Ottiene informazioni su un DbContext tipo.

Le opzioni comuni sono elencate in precedenza.

dotnet ef dbcontext list

Elenca i tipi disponibili DbContext .

Le opzioni comuni sono elencate in precedenza.

dotnet ef dbcontext optimize

Genera una versione compilata del modello usato dalle DbContext query e precompila.

Per altre informazioni, vedere Modelli compilati .

Opzioni:

Opzione Short Descrizione
--output-dir <PATH> -o Directory in cui inserire i file. I percorsi sono relativi alla directory del progetto.
--namespace <NAMESPACE> -n Spazio dei nomi da usare per tutte le classi generate. L'impostazione predefinita è generata dallo spazio dei nomi radice e dalla directory di output più CompiledModels.
--suffix <SUFFIX> Suffisso da allegare al nome di tutti i file generati. Ad esempio, .g può essere usato per indicare che questi file contengono codice generato
--no-scaffold Non generare un modello compilato. Viene usato quando il modello compilato è già stato generato.
--precompile-queries Generare query precompilate. Questa operazione è necessaria per la compilazione NativeAOT se il progetto di destinazione contiene query
--nativeaot Generare codice aggiuntivo nel modello compilato necessario per la compilazione NativeAOT e le query precompilate

Nota

Il supporto nativeAOT e le query precompilate sono considerati sperimentali in EF 9 e potrebbero cambiare notevolmente nella versione successiva.

Le opzioni comuni sono elencate in precedenza.

L'esempio seguente usa le impostazioni predefinite e funziona se ne esiste una DbContext sola nel progetto:

dotnet ef dbcontext optimize

L'esempio seguente ottimizza il modello per il contesto con il nome specificato e lo inserisce in una cartella e uno spazio dei nomi separati:

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

dotnet ef dbcontext scaffold

Genera codice per i DbContext tipi di entità e per un database. Affinché questo comando generi un tipo di entità, la tabella di database deve avere una chiave primaria.

Argomenti:

Argomento Descrizione
<CONNECTION> Stringa di connessione al database. Per ASP.NET progetti Core 2.x, il valore può essere name=<name di stringa di connessione>. In tal caso il nome proviene dalle origini di configurazione configurate per il progetto.
<PROVIDER> Provider da usare. In genere si tratta del nome del pacchetto NuGet, ad esempio: Microsoft.EntityFrameworkCore.SqlServer.

Opzioni:

Opzione Short Descrizione
--data-annotations -d Usare gli attributi per configurare il modello (laddove possibile). Se questa opzione viene omessa, viene usata solo l'API Fluent.
--context <NAME> -c Nome della DbContext classe da generare.
--context-dir <PATH> Directory in cui inserire il file di DbContext classe. I percorsi sono relativi alla directory del progetto. Gli spazi dei nomi sono derivati dai nomi delle cartelle.
--context-namespace <NAMESPACE> Spazio dei nomi da usare per la classe generata DbContext . Nota: esegue l'override di --namespace.
--force -f Sovrascrivere i file esistenti.
--output-dir <PATH> -o Directory in cui inserire i file di classe di entità. I percorsi sono relativi alla directory del progetto.
--namespace <NAMESPACE> -n Spazio dei nomi da usare per tutte le classi generate. Il valore predefinito è generato dallo spazio dei nomi radice e dalla directory di output.
--schema <SCHEMA_NAME>... Schemi di tabelle e viste per cui generare tipi di entità. Per specificare più schemi, ripetere --schema per ognuno di essi. Se questa opzione viene omessa, vengono inclusi tutti gli schemi. Se si usa questa opzione, tutte le tabelle e le viste negli schemi verranno incluse nel modello, anche se non sono incluse in modo esplicito tramite --table.
--table <TABLE_NAME>... -t Tabelle e viste per cui generare tipi di entità. Per specificare più tabelle, ripetere -t o --table per ognuna di esse. È possibile includere tabelle o viste in uno schema specifico usando il formato 'schema.table' o 'schema.view'. Se questa opzione viene omessa, vengono incluse tutte le tabelle e le viste.
--use-database-names Usare nomi di tabella, vista, sequenza e colonna esattamente come vengono visualizzati nel database. Se questa opzione viene omessa, i nomi dei database vengono modificati in modo da essere più conformi alle convenzioni di stile dei nomi C#.
--no-onconfiguring Elimina la OnConfiguring generazione del metodo nella classe generata DbContext .
--no-pluralize Non usare il pluralizzatore.

Le opzioni comuni sono elencate in precedenza.

Nell'esempio seguente viene creato lo scaffolding di tutti gli schemi e le tabelle e i nuovi file vengono inseriti nella cartella Models .

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

L'esempio seguente esegue lo scaffolding solo delle tabelle selezionate e crea il contesto in una cartella separata con un nome e uno spazio dei nomi specificati:

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

L'esempio seguente legge il stringa di connessione dal set di configurazione del progetto usando lo strumento Secret Manager.

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

Nell'esempio seguente viene ignorato lo scaffolding di un OnConfiguring metodo. Ciò può essere utile quando si vuole configurare DbContext all'esterno della classe . Ad esempio, ASP.NET app Core la configurano in genere in 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 uno script SQL da DbContext. Ignora le migrazioni.

Opzioni:

Opzione Short Descrizione
--output <FILE> -o File in cui scrivere il risultato.

Le opzioni comuni sono elencate in precedenza.

dotnet ef migrations add

Aggiunge una nuova migrazione.

Argomenti:

Argomento Descrizione
<NAME> Nome della migrazione.

Opzioni:

Opzione Short Descrizione
--output-dir <PATH> -o Directory utilizzata per restituire i file. I percorsi sono relativi alla directory del progetto di destinazione. Il valore predefinito è "Migrazioni".
--namespace <NAMESPACE> -n Spazio dei nomi da usare per le classi generate. L'impostazione predefinita viene generata dalla directory di output.

Le opzioni comuni sono elencate in precedenza.

dotnet ef migrations bundle

Crea un eseguibile per aggiornare il database.

Opzioni:

Opzione Short Descrizione
--output <FILE> -o Percorso del file eseguibile da creare.
--force -f Sovrascrivere i file esistenti.
--self-contained Aggregare anche il runtime .NET in modo che non sia necessario installarlo nel computer.
--target-runtime <RUNTIME_IDENTIFIER> -r Runtime di destinazione per cui eseguire il bundle.

Le opzioni comuni sono elencate in precedenza.

dotnet ef migrations has-pending-model-changes

Nota

Questo comando è stato aggiunto in EF Core 8.0.

Controlla se sono state apportate modifiche al modello dall'ultima migrazione.

Opzioni:

Le opzioni comuni sono elencate in precedenza.

dotnet ef migrations list

Elenca le migrazioni disponibili.

Opzioni:

Opzione Descrizione
--connection <CONNECTION> Stringa di connessione al database. Il valore predefinito è quello specificato in AddDbContext o OnConfiguring.
--no-connect Non connettersi al database.

Le opzioni comuni sono elencate in precedenza.

dotnet ef migrations remove

Rimuove l'ultima migrazione, rollback delle modifiche al codice eseguite per la migrazione più recente.

Opzioni:

Opzione Short Descrizione
--force -f Ripristinare la migrazione più recente, eseguendo il rollback delle modifiche di codice e database eseguite per la migrazione più recente. Continua a eseguire il rollback solo del codice se si verifica un errore durante la connessione al database.

Le opzioni comuni sono elencate in precedenza.

dotnet ef migrations script

Genera uno script SQL dalle migrazioni.

Argomenti:

Argomento Descrizione
<FROM> Migrazione iniziale. Le migrazioni possono essere identificate in base al nome o all'ID. Il numero 0 è un caso speciale che indica prima della prima migrazione. Il valore predefinito è 0.
<TO> Migrazione finale. Il valore predefinito è l'ultima migrazione.

Opzioni:

Opzione Short Descrizione
--output <FILE> -o File in cui scrivere lo script.
--idempotent -i Generare uno script che può essere usato in un database in qualsiasi migrazione.
--no-transactions Non generare istruzioni di transazione SQL.

Le opzioni comuni sono elencate in precedenza.

L'esempio seguente crea uno script per la migrazione InitialCreate:

dotnet ef migrations script 0 InitialCreate

Nell'esempio seguente viene creato uno script per tutte le migrazioni dopo la migrazione InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Risorse aggiuntive