Menggunakan proyek SQL bergaya SDK dengan ekstensi Proyek SQL Database (Pratinjau)

  • Artikel

Artikel ini memperkenalkan proyek SQL bergaya Microsoft.Build.Sql untuk SDK di ekstensi Proyek SQL Database di Azure Data Studio atau Visual Studio Code. Proyek SQL bergaya SDK sangat menguntungkan untuk aplikasi yang dikirim melalui alur atau dibangun di lingkungan lintas platform. Pengumuman awal tersedia di TechCommunity.

Catatan

Microsoft.Build.Sql saat ini dalam pratinjau.

Membuat proyek database bergaya SDK

Anda bisa membuat proyek database bergaya SDK dari proyek kosong, atau dari database yang sudah ada.

Proyek kosong

Dalam tampilan Proyek Database, pilih tombol Proyek Baru dan masukkan nama proyek dalam input teks yang muncul. Dalam kotak dialog Pilih Folder yang muncul, pilih direktori untuk folder, file, .sqlproj dan konten proyek lainnya untuk berada.

Secara default, pilihan untuk proyek gaya SDK (Pratinjau) dicentang. Saat dialog selesai, proyek kosong dibuka dan terlihat dalam tampilan Proyek Database untuk pengeditan.

Dari database yang sudah ada

Dalam tampilan Proyek, pilih tombol Buat Proyek dari Database dan sambungkan ke SQL Server. Setelah koneksi dibuat, pilih database dari daftar database yang tersedia dan atur nama proyek. Pilih struktur target ekstraksi.

Secara default, pilihan untuk proyek gaya SDK (Pratinjau) dicentang. Ketika dialog selesai, proyek baru dibuka dan berisi skrip SQL untuk konten database yang dipilih.

Membuat dan menerbitkan

Dari antarmuka Azure Data Studio dan Visual Studio Code, membangun dan menerbitkan proyek SQL bergaya SDK diselesaikan dengan cara yang sama seperti format proyek SQL sebelumnya. Untuk informasi selengkapnya tentang proses ini, lihat Membangun dan Menerbitkan Proyek.

Untuk membangun proyek SQL gaya SDK dari baris perintah di Windows, macOS, atau Linux, gunakan perintah berikut:

dotnet build

File .dacpac yang dihasilkan dari membangun proyek SQL bergaya SDK kompatibel dengan alat yang terkait dengan kerangka kerja aplikasi tingkat data (.dacpac, .bacpac), termasuk SqlPackage dan GitHub sql-action.

Kemampuan proyek

Dalam proyek SQL ada beberapa kemampuan yang dapat ditentukan dalam .sqlproj file yang memengaruhi model database baik di build proyek atau penyebaran. Bagian berikut menjelaskan beberapa kemampuan ini yang tersedia untuk proyek Microsoft.Build.Sql.

Platform target

Properti platform target terkandung dalam DSP tag dalam file di .sqlproj<PropertyGroup> bawah item. Platform target digunakan selama build proyek untuk memvalidasi dukungan untuk fitur yang disertakan dalam proyek dan ditambahkan ke .dacpac file sebagai properti. Secara default, selama penyebaran, platform target diperiksa terhadap database target untuk memastikan kompatibilitas. Jika platform target tidak didukung oleh database target, penyebaran gagal kecuali opsi ambil alih penerbitan ditentukan.

<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>

Pengaturan yang valid untuk platform target adalah:

  • 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

Referensi database

Validasi model database pada waktu build dapat diperpanjang melewati konten proyek SQL melalui referensi database. Referensi database yang ditentukan dalam .sqlproj file dapat mereferensikan proyek SQL lain atau .dacpac file, yang mewakili database lain atau lebih komponen database yang sama.

Atribut berikut tersedia untuk referensi database yang mewakili database lain:

  • DatabaseSqlCmdVariable: nilainya adalah nama variabel yang digunakan untuk mereferensikan database
    • Pengaturan referensi: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
    • Contoh penggunaan: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
  • ServerSqlCmdVariable: nilainya adalah nama variabel yang digunakan untuk mereferensikan server tempat database berada. digunakan dengan DatabaseSqlCmdVariable, ketika database berada di server lain.
    • Pengaturan referensi: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
    • Contoh penggunaan: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
  • DatabaseVariableLiteralValue: nilainya adalah nama harfiah database seperti yang digunakan dalam proyek SQL, mirip DatabaseSqlCmdVariable dengan tetapi referensi ke database lain adalah nilai harfiah
    • Pengaturan referensi: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
    • Contoh penggunaan: SELECT * FROM [SomeOtherDatabase].dbo.Table1

Dalam file proyek SQL, referensi database ditentukan sebagai item dengan atribut yang ArtifactReferenceInclude diatur ke jalur .dacpac file.

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

Referensi paket

Referensi paket digunakan untuk mereferensikan paket NuGet yang berisi .dacpac file dan digunakan untuk memperluas model database pada waktu build sama seperti referensi database.

Contoh berikut dari file proyek SQL mereferensikan Microsoft.SqlServer.Dacpacspaket untuk master database.

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

Selain atribut yang tersedia untuk referensi database, atribut berikut DacpacName dapat ditentukan untuk memilih .dacpac dari paket yang berisi beberapa .dacpac file.

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

Variabel SqlCmd

Variabel SqlCmd dapat ditentukan dalam .sqlproj file dan digunakan untuk mengganti token dalam objek dan skrip SQL selama .dacpacpenyebaran. Contoh berikut dari file proyek SQL menentukan variabel bernama EnvironmentName yang tersedia untuk digunakan dalam objek dan skrip proyek.

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

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

Ketika proyek SQL yang dikompilasi (.dacpac) disebarkan, nilai variabel diganti dengan nilai yang ditentukan dalam perintah penyebaran. Misalnya, perintah berikut menyebarkan AdventureWorks.dacpac dan mengatur nilai EnvironmentName variabel ke production.

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

Skrip pra/pasca-penyebaran

Skrip pra-dan pasca-penyebaran adalah skrip SQL yang disertakan dalam proyek yang akan dijalankan selama penyebaran. Skrip pra/pasca-penyebaran disertakan dalam tetapi tidak dikompilasi atau divalidasi .dacpac dengan model objek database. Skrip pra-penyebaran dijalankan sebelum model database diterapkan dan skrip pasca-penyebaran dijalankan setelah model database diterapkan. Contoh berikut dari file proyek SQL menambahkan file populate-app-settings.sql sebagai skrip pasca-penyebaran.

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

Langkah berikutnya