Panoramica delle migrazioni

Nei progetti reali, i modelli di dati cambiano quando vengono implementate le funzionalità: nuove entità o proprietà vengono aggiunte e rimosse e gli schemi di database devono essere modificati di conseguenza per essere mantenuti sincronizzati con l'applicazione. La funzionalità delle migrazioni in EF Core rappresenta un metodo per l'aggiornamento incrementale dello schema del database per mantenere quest'ultimo sincronizzato con il modello di dati dell'applicazione mantenendo i dati esistenti nel database.

A livello generale, le migrazioni funzionano nel modo seguente:

  • Quando viene introdotta una modifica del modello di dati, lo sviluppatore usa gli strumenti di EF Core per aggiungere una migrazione corrispondente in cui sono descritti gli aggiornamenti necessari per la sincronizzazione dello schema del database. EF Core confronta il modello corrente con uno snapshot del modello precedente per determinare le differenze e genera i file di origine della migrazione. È possibile tenere traccia dei file nel controllo del codice sorgente del progetto, come per qualsiasi altro file di origine.
  • Dopo aver generato una nuova migrazione, è possibile applicarla a un database in vari modi. EF Core registra tutte le migrazioni applicate in una tabella di cronologia speciale, consentendo di individuare quali migrazioni sono state applicate e quali non sono state applicate.

La parte restante di questa pagina contiene istruzioni dettagliate per principianti sull'uso delle migrazioni. Per informazioni più dettagliate, leggere le altre pagine di questa sezione.

Introduzione

Si supponga di aver appena completato la prima applicazione EF Core contenente il semplice modello seguente:

public class Blog
{
    public int Id { get; set; }
    public string Name { get; set; }
}

Durante lo sviluppo, è possibile che siano state usate le API di creazione ed eliminazione per eseguire un'iterazione rapida, modificando il modello in base alle esigenze. Tuttavia, ora che l'applicazione è in fase di produzione, è necessario un modo per evolvere in modo sicuro lo schema senza eliminare l'intero database.

Installare gli strumenti

Per prima cosa, è necessario installare gli strumenti da riga di comando di EF Core:

Creare la prima migrazione

A questo punto si è pronti per aggiungere la prima migrazione. Chiedere a EF Core di creare una migrazione denominata InitialCreate:

dotnet ef migrations add InitialCreate

EF Core creerà una directory denominata Migrazioni nel progetto e genererà alcuni file. È consigliabile esaminare gli elementi generati da EF Core ed eventualmente modificarli. Per il momento si ignorerà questo passaggio.

Creare il database e lo schema

A questo punto EF può creare il database e lo schema dalla migrazione. È possibile eseguire questa operazione nel modo seguente:

dotnet ef database update

Tutto qui. L'applicazione è pronta per essere eseguita nel nuovo database e non è stato necessario scrivere una singola riga di SQL. Si noti che questo modo di applicare le migrazioni è ideale per lo sviluppo locale, ma è meno adatto per gli ambienti di produzione. Per altre informazioni, vedere la pagina Applicazione delle migrazioni.

Evoluzione del modello

Sono passati alcuni giorni e viene chiesto di aggiungere un timestamp di creazione ai blog. Sono state apportate le modifiche necessarie all'applicazione e il modello è ora simile al seguente:

public class Blog
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime CreatedTimestamp { get; set; }
}

Il modello e il database di produzione non sono ora sincronizzati. È necessario aggiungere una nuova colonna allo schema del database. Verrà ora creata una nuova migrazione a tale scopo:

dotnet ef migrations add AddBlogCreatedTimestamp

Si noti che alla migrazione viene assegnato un nome descrittivo in modo da facilitare poi la comprensione della cronologia del progetto.

Poiché non si tratta della prima migrazione del progetto, EF Core ora confronta il modello aggiornato con uno snapshot del modello precedente (prima che fosse aggiunta la colonna). Lo snapshot del modello è uno dei file generati da EF Core in fase di aggiunta di una migrazione e viene archiviato nel controllo del codice sorgente. In base a tale confronto, EF Core rileva che è stata aggiunta una colonna e aggiunge la migrazione appropriata.

È ora possibile applicare la migrazione come eseguito in precedenza:

dotnet ef database update

Si noti che questa volta EF rileva che il database esiste già. Quando è stata applicata la prima migrazione, questa operazione è stata anche registrata in una tabella di cronologia delle migrazioni speciale all'interno del database. Si consente così a EF di applicare automaticamente solo la nuova migrazione.

Esclusione di parti del modello

Nota

Questa funzionalità è stata introdotta in EF Core 5.0.

In alcuni casi può essere necessario fare riferimento a tipi da un altro DbContext. Ciò può causare conflitti di migrazione. Per evitare questo problema, escludere il tipo dalle migrazioni di uno degli oggetti DbContext.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<IdentityUser>()
        .ToTable("AspNetUsers", t => t.ExcludeFromMigrations());
}

Passaggi successivi

Sopra è stata riportata solo una breve introduzione alle migrazioni. Leggere le altre pagine della documentazione per informazioni dettagliate sulla gestione delle migrazioni, sulla relativa applicazione e su altri aspetti. Il riferimento allo strumento dell'interfaccia della riga di comando di .NET Core contiene anche informazioni utili sui diversi comandi

Risorse aggiuntive