Entity Framework Core 工具參考 - .NET Core CLI

  • 發行項

Entity Framework Core 的命令列介面 （CLI） 工具會執行設計階段開發工作。 例如，他們會建立 移轉 、套用移轉，並根據現有的資料庫為模型產生程式碼。 這些命令是跨平臺 dotnet 命令的延伸模組，這是 .NET Core SDK 的 一部分。 這些工具可與 .NET Core 專案搭配使用。

使用 Visual Studio 時，請考慮使用 封裝管理員 主控台工具 ，而不是 CLI 工具。 自動封裝管理員主控台工具：

  • 使用封裝管理員主控台 中 選取的目前專案，而不需要手動切換目錄。
  • 開啟命令完成之後所產生的檔案。
  • 提供命令、參數、專案名稱、內容類型和移轉名稱的索引標籤完成。

安裝工具

dotnet ef 可以安裝為全域或本機工具。 大部分開發人員偏好使用下列命令安裝 dotnet ef 為全域工具：

dotnet tool install --global dotnet-ef

若要使用它做為本機工具，請使用工具資訊清單檔 還原專案宣告為工具相 依性的相依性。

使用下列命令更新工具：

dotnet tool update --global dotnet-ef

您必須先將套件新增 Microsoft.EntityFrameworkCore.Design 至特定專案，才能使用特定專案上的工具。

dotnet add package Microsoft.EntityFrameworkCore.Design

確認安裝

執行下列命令以確認 EF Core CLI 工具是否已正確安裝：

dotnet ef

命令的輸出會識別使用中工具的版本：


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

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

<Usage documentation follows, not shown.>

更新工具

使用 dotnet tool update --global dotnet-ef 將全域工具更新為最新的可用版本。 如果您已在專案中本機安裝工具，請使用 dotnet tool update dotnet-ef 。 將 附加 --version <VERSION> 至命令以安裝特定版本。 如需詳細資訊，請參閱 dotnet 工具檔的更新 一節。

使用工具

使用工具之前，您可能必須建立啟始專案或設定環境。

目標專案和啟始專案

命令會參考 專案 和 啟始專案 。

  • 專案 也稱為 目標專案 ，因為它是命令新增或移除檔案的位置。 根據預設，目前目錄中的專案是目標專案。 您可以使用 選項，將不同的專案指定為目標專案 --project 。

  • 啟動 專案 是工具建置和執行的專案。 這些工具必須于設計階段執行應用程式程式碼，才能取得專案的相關資訊，例如資料庫連接字串和模型的組態。 根據預設，目前目錄中的專案是啟動專案。 您可以使用 選項，將不同的專案指定為啟始專案 --startup-project 。

啟動專案和目標專案通常是相同的專案。 其為個別專案的一般案例是下列情況：

  • EF Core 內容和實體類別位於 .NET Core 類別庫中。
  • .NET Core 主控台應用程式或 Web 應用程式會參考類別庫。

您也可以將 移轉程式碼放在與 EF Core 內容 分開的類別庫中。

其他目標架構

CLI 工具會使用 .NET Core 專案和 .NET Framework 專案。 在 .NET Standard 類別庫中具有 EF Core 模型的應用程式可能沒有 .NET Core 或 .NET Framework 專案。 例如，這是 Xamarin 和 通用 Windows 平臺 應用程式。 在這種情況下，您可以建立 .NET Core 主控台應用程式專案，其唯一目的是做為工具的啟動專案。 專案可以是沒有實際程式碼的虛擬專案，只需要提供工具的目標。

為什麼需要虛擬專案？ 如先前所述，工具必須于設計階段執行應用程式程式碼。 若要這樣做，他們必須使用 .NET Core 執行時間。 當 EF Core 模型位於以 .NET Core 或 .NET Framework 為目標的專案時，EF Core 工具會從專案借用執行時間。 如果 EF Core 模型位於 .NET Standard 類別庫，則無法這麼做。 .NET Standard 不是實際的 .NET 實作;它是一組 .NET 實作必須支援的 API 規格。 因此，.NET Standard 不足以讓 EF Core 工具執行應用程式程式碼。 您建立做為啟始專案的虛擬專案提供可載入 .NET Standard 類別庫的具體目標平臺。

ASP.NET Core 環境

您可以在命令列上指定 ASP.NET Core 專案的環境 。 這個和任何其他引數會傳遞至 Program.CreateHostBuilder。

dotnet ef database update -- --environment Production

提示

權杖 -- 會指示 dotnet ef 將後續的所有專案視為引數，而不是嘗試將它們剖析為選項。 未使用 dotnet ef 的任何額外引數會轉送至應用程式。

一般選項

選項 Short 描述
--json 顯示 JSON 輸出。
--context <DBCONTEXT> -c 要使用的 DbContext 類別。 僅限類別名稱或具有命名空間的完整名稱。 如果省略此選項，EF Core 會尋找內容類別別。 如果有多個內容類別別，則需要此選項。
--project <PROJECT> -p 目標專案之專案資料夾的相對路徑。 預設值為目前的資料夾。
--startup-project <PROJECT> -s 啟動專案之專案資料夾的相對路徑。 預設值為目前的資料夾。
--framework <FRAMEWORK> 目標 Framework 的目標 Framework Moniker 。 當專案檔指定多個目標架構，而且您想要選取其中一個時，請使用 。
--configuration <CONFIGURATION> 組建組態，例如： Debug 或 Release 。
--runtime <IDENTIFIER> 要還原封裝的目標執行時間識別碼。 如需執行階段識別項 (RID) 清單，請參閱 RID 目錄。
--no-build 請勿建置專案。 預期在組建為最新狀態時使用。
--help -h 顯示說明資訊。
--verbose -v 顯示詳細資訊輸出。
--no-color 不要將輸出著色。
--prefix-output 具有層級的前置詞輸出。

任何其他引數會傳遞至應用程式。

dotnet ef database drop

刪除資料庫。

選項：

選項 Short 描述
--force -f 請勿確認。
--dry-run 顯示要卸載的資料庫，但不要卸載。

上面 列出常見的選項 。

dotnet ef database update

更新資料庫到最後一次移轉或指定的移轉。

引數：

引數 描述
<MIGRATION> 目標移轉。 移轉可以依名稱或識別碼來識別。 數位 0 是特殊案例，表示 在第一次移 轉之前，並導致所有移轉都還原。 如果未指定任何移轉，命令會預設為上次移轉。

選項：

選項 描述
--connection <CONNECTION> 資料庫的連接字串。 預設為 或 OnConfiguring 中指定的 AddDbContext 。

上面 列出常見的選項 。

下列範例會將資料庫更新為指定的移轉。 第一個使用移轉名稱，第二個使用移轉識別碼和指定的連線：

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

dotnet ef dbcontext info

取得型別 DbContext 的相關資訊。

上面 列出常見的選項 。

dotnet ef dbcontext list

列出可用的 DbContext 類型。

上面 列出常見的選項 。

dotnet ef dbcontext optimize

產生 所 DbContext 使用之模型的編譯版本。

如需詳細資訊，請參閱 編譯的模型 。

選項：

選項 Short 描述
--output-dir <PATH> -o 要放入檔案的目錄。 路徑相對於專案目錄。
--namespace <NAMESPACE> -n 要用於所有產生的類別的命名空間。 預設為從根命名空間和輸出目錄加上 CompiledModels 產生的 。

上面 列出常見的選項 。

下列範例會使用預設設定，如果專案中只有一個 DbContext ，則適用：

dotnet ef dbcontext optimize

下列範例會針對具有指定名稱的內容優化模型，並將它放在個別的資料夾和命名空間中：

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

dotnet ef dbcontext scaffold

為資料庫產生 和 實體類型的程式碼 DbContext 。 為了讓此命令產生實體類型，資料庫資料表必須具有主鍵。

引數：

引數 描述
<CONNECTION> 資料庫的連接字串。 針對 ASP.NET Core 2.x 專案，此值可以是 name= < name of 連接字串 > 。 在此情況下，名稱來自為專案設定的組態來源。
<PROVIDER> 要使用的提供者。 一般而言，這是 NuGet 套件的名稱，例如： Microsoft.EntityFrameworkCore.SqlServer 。

選項：

選項 Short 描述
--data-annotations -d 使用屬性來設定模型（可能的話）。 如果省略此選項，則只會使用 Fluent API。
--context <NAME> -c 要產生之 DbContext 類別的名稱。
--context-dir <PATH> 要放入類別檔案的 DbContext 目錄。 路徑相對於專案目錄。 命名空間衍生自資料夾名稱。
--context-namespace <NAMESPACE> 要用於所 DbContext 產生類別的命名空間。 注意：覆寫 --namespace 。
--force -f 覆寫現有檔案。
--output-dir <PATH> -o 要放置實體類別檔案的目錄。 路徑相對於專案目錄。
--namespace <NAMESPACE> -n 要用於所有產生的類別的命名空間。 預設為從根命名空間和輸出目錄產生。
--schema <SCHEMA_NAME>... 要為其產生實體類型的資料表和檢視的架構。 若要指定多個架構，請針對每個架構重複 --schema 一次。 如果省略此選項，則會包含所有架構。 如果使用此選項，則即使未使用 --table 明確包含架構中的所有資料表和檢視，也會包含在模型中。
--table <TABLE_NAME>... -t 要為其產生實體類型的資料表和檢視表。 若要指定多個資料表，請針對每個資料表重複 -t 或 --table 。 特定架構中的資料表或檢視表可以使用 'schema.table' 或 'schema.view' 格式來包含。 如果省略此選項，則會包含所有資料表和檢視表。
--use-database-names 使用資料表、檢視、序列和資料行名稱，與資料庫中顯示的名稱完全相同。 如果省略此選項，資料庫名稱會變更為更符合 C# 名稱樣式慣例。
--no-onconfiguring 抑制在產生的 DbContext 類別中產生 OnConfiguring 方法。
--no-pluralize 請勿使用複數化程式。

上面 列出常見的選項 。

下列範例會建構所有架構和資料表，並將新檔案 放入 Models 資料夾中。

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

下列範例只會建立選取的資料表，並在具有指定名稱和命名空間的個別資料夾中建立內容：

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

下列範例會使用 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

下列範例會略過方法的 Scaffold。 OnConfiguring 當您想要在 類別外部設定 DbCoNtext 時，這非常有用。 例如，ASP.NET Core 應用程式通常會在 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

從 DbCoNtext 產生 SQL 腳本。 略過任何移轉。

選項：

選項 Short 描述
--output <FILE> -o 要寫入結果的檔案。

上面 列出常見的選項 。

dotnet ef migrations add

新增移轉。

引數：

引數 描述
<NAME> 移轉的名稱。

選項：

選項 Short 描述
--output-dir <PATH> -o 目錄會使用 來輸出檔案。 路徑相對於目標專案目錄。 預設為 「移轉」。
--namespace <NAMESPACE> -n 要用於所產生類別的命名空間。 預設為從輸出目錄產生。

上面 列出常見的選項 。

dotnet ef migrations bundle

建立可執行檔以更新資料庫。

選項：

選項 Short 描述
--output <FILE> -o 要建立之可執行檔的路徑。
--force -f 覆寫現有檔案。
--self-contained 此外，也會將 .NET 執行時間組合在一起，因此不需要安裝在機器上。
--target-runtime <RUNTIME_IDENTIFIER> -r 要配套的目標執行時間。

上面 列出常見的選項 。

dotnet ef migrations has-pending-model-changes

注意

此命令已在 EF Core 8.0 中新增。

檢查自上次移轉後是否已對模型進行任何變更。

選項：

上面 列出常見的選項 。

dotnet ef migrations list

列出可用的移轉。

選項：

選項 描述
--connection <CONNECTION> 資料庫的連接字串。 預設為 AddDbCoNtext 或 OnConfiguring 中指定的 。
--no-connect 請勿連線到資料庫。

上面 列出常見的選項 。

dotnet ef migrations remove

移除最後一個移轉，復原針對最新移轉所完成的程式碼變更。

選項：

選項 Short 描述
--force -f 還原最新的移轉，復原針對最新移轉所做的程式碼和資料庫變更。 如果連線到資料庫時發生錯誤，請繼續回復程式碼變更。

上面 列出常見的選項 。

dotnet ef migrations script

從移轉產生 SQL 腳本。

引數：

引數 描述
<FROM> 開始移轉。 移轉可以依名稱或識別碼來識別。 數位 0 是特殊案例，表示 在第一次移 轉之前。 預設為 0。
<TO> 結束移轉。 預設為上次移轉。

選項：

選項 Short 描述
--output <FILE> -o 要寫入腳本的檔案。
--idempotent -i 產生可在任何移轉時在資料庫上使用的腳本。
--no-transactions 請勿產生 SQL 交易語句。

上面 列出常見的選項 。

下列範例會建立 InitialCreate 移轉的腳本：

dotnet ef migrations script 0 InitialCreate

下列範例會在 InitialCreate 移轉之後建立所有移轉的腳本。

dotnet ef migrations script 20180904195021_InitialCreate

其他資源