共用方式為


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

本文介紹在 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>

下一步