使用 SDK 樣式 SQL 專案搭配 SQL Database Projects 延伸模組 (預覽)

發行項
08/14/2024

本文介紹在 Azure Data Studio 或 Visual Studio Code 的 SQL Database Projects 延伸模組中，用於 SDK 樣式的 SQL 專案的 Microsoft.Build.Sql。 SDK 樣式 SQL 專案特別適合透過管線或內建跨平台環境所提供的應用程式。 TechCommunity 中會提供初始公告。

注意

Microsoft.Build.Sql 目前處於預覽。

建立 SDK 樣式的資料庫專案

您可以從空白專案或現有資料庫建立 SDK 樣式的資料庫專案。

空白專案

在 [資料庫專案] 檢視中，選取 [新增專案] 按鈕，然後在出現的文字輸入內容中輸入專案名稱。在出現的 [選取資料夾] 對話方塊中，選取專案資料夾的目錄、.sqlproj 檔案，以及要存放在其中的其他內容。

預設會勾選 [SDK 樣式專案 (預覽)] 選項。對話方塊完成時，空白專案會隨即開啟，並顯示在 [資料庫專案] 檢視中以供編輯。

從現有的資料庫

在 [專案] 檢視中，選取 [從資料庫建立專案] 按鈕並連線到 SQL Server。建立連線後，從可用的資料庫清單選取資料庫，並設定專案的名稱。選取擷取的目標結構。

預設會勾選 [SDK 樣式專案 (預覽)] 選項。對話方塊完成時，新專案隨即開啟，且包含所選取資料庫內容的 SQL 指令碼。

建置和發佈

從 Azure Data Studio 和 Visual Studio Code 介面，建置和發佈 SDK 樣式 SQL 專案會以與先前的 SQL 專案格式相同的方式完成。如需此程序的詳細資訊，請參閱建置和發佈專案。

若要在 Windows、macOS 或 Linux 上透過命令列建置 SDK 樣式 SQL 專案，請使用下列命令：

dotnet build

建置 SDK 樣式 SQL 專案所產生的 .dacpac 檔案與資料層應用程式架構 (.dacpac、.bacpac) 相關聯的工具相容，包括 SqlPackage 和 GitHub sql-action。

專案功能

在 SQL 專案中，有數個功能可以在 .sqlproj 檔案中指定，其會影響專案建置或部署的資料庫模型。下列各節描述 Microsoft.Build.Sql 專案可用的一些功能。

目標平台

目標平台屬性會包含在 <PropertyGroup> 項目下 .sqlproj 檔案的 DSP 標記中。目標平台會在專案建置期間用來驗證對專案中所包含功能的支援，並新增至 .dacpac 檔案作為屬性。根據預設，在部署期間，將對照目標資料庫檢查目標平台，以確保相容性。如果目標資料庫不支援該目標平台，除非指定覆寫 [發佈選項]，否則部署會失敗。

<Project DefaultTargets="Build">
  <Sdk Name="Microsoft.Build.Sql" Version="0.1.12-preview" />
  <PropertyGroup>
    <Name>AdventureWorks</Name>
    <DSP>Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider</DSP>
  </PropertyGroup>

目標平台的有效設定如下：

Microsoft.Data.Tools.Schema.Sql.Sql120DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql130DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql140DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql150DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlDwDatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlServerlessDatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlDwUnifiedDatabaseSchemaProvider

資料庫參考

建置時間的資料庫模型驗證可以透過資料庫參考來延伸 SQL 專案的內容。 .sqlproj 檔案中指定的資料庫參考可以參考另一個 SQL 專案或 .dacpac 檔案，代表相同資料庫的另一個資料庫或多個元件。

下列屬性可供代表另一個資料庫的資料庫參考使用：

DatabaseSqlCmdVariable：值是用來參考資料庫的變數名稱
- 參考設定：<DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
- 使用範例：SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
ServerSqlCmdVariable：值是用來參考資料庫所在伺服器的變數名稱。當資料庫位於另一部伺服器時，會與 DatabaseSqlCmdVariable 搭配使用。
- 參考設定：<ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
- 使用範例：SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
DatabaseVariableLiteralValue：值是 SQL 專案中所使用資料庫的常值名稱，類似於 DatabaseSqlCmdVariable，但其他資料庫的參考是常值
- 參考設定：<DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
- 使用範例：SELECT * FROM [SomeOtherDatabase].dbo.Table1

在 SQL 專案檔中，資料庫參考會指定為 Include 屬性設定為 .dacpac 檔案路徑的 ArtifactReference 項目。

  <ItemGroup>
    <ArtifactReference Include="SampleA.dacpac">
      <DatabaseSqlCmdVariable>DatabaseA</DatabaseSqlCmdVariable>
    </ArtifactReference>
  </ItemGroup>
</Project>

套件參考

封裝參考可用來參考包含 .dacpac 檔案的 NuGet 封裝，並用來在建置時間延伸資料庫模型，類似於資料庫參考。

來自 SQL 專案檔的下列範例會參考 master 資料庫的 Microsoft.SqlServer.Dacpacs 封裝。

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0" />
  </ItemGroup>
</Project>

除了資料庫參考可用的屬性之外，還可以指定下列 DacpacName 屬性，以從包含多個 .dacpac 檔案的封裝中選取 .dacpac。

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0">
      <DacpacName>msdb</DacpacName>
    </PackageReference>
  </ItemGroup>
</Project>

SqlCmd 變數

SqlCmd 變數可以在 .sqlproj 檔案中定義，並用來在 .dacpac 部署期間取代 SQL 物件和指令碼中的權杖。來自 SQL 專案檔的下列範例會定義名為 EnvironmentName 的變數，可用於專案的物件和指令碼中。

  <ItemGroup>
    <SqlCmdVariable Include="EnvironmentName">
      <DefaultValue>testing</DefaultValue>
      <Value>$(SqlCmdVar__1)</Value>
    </SqlCmdVariable>
  </ItemGroup>
</Project>

IF '$(EnvironmentName)' = 'testing'
BEGIN
    -- do something
END

部署編譯的 SQL 專案 (.dacpac) 時，變數的值會以部署命令中指定的值取代。例如，下列命令會部署 AdventureWorks.dacpac，並將 EnvironmentName 變數的值設定為 production。

SqlPackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /v:EnvironmentName=production

部署前/後指令碼

部署前和部署後指令碼是 SQL 指令碼，其包含在專案中以於部署期間執行。部署前/部署後指令碼包含在 .dacpac 中，但不會編譯成或使用資料庫物件模型進行驗證。在套用資料庫模型之前，會先執行部署前指令碼，並在套用資料庫模型之後執行部署後指令碼。來自 SQL 專案檔的下列範例會將檔案 populate-app-settings.sql 新增為部署後指令碼。

  <ItemGroup>
    <PostDeploy Include="populate-app-settings.sql" />
  </ItemGroup>
</Project>

共用方式為