Mengonversi proyek SQL asli ke proyek bergaya SDK

Berlaku bagi:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceSQL database di Microsoft Fabric

Membuat proyek SQL gaya SDK baru adalah tugas cepat. Namun, jika Anda memiliki proyek SQL yang ada, Anda dapat mengonversinya ke proyek SQL bergaya SDK untuk memanfaatkan fitur baru.

Setelah mengonversi proyek, Anda dapat menggunakan fitur baru proyek gaya SDK, seperti:

• Dukungan pembuatan lintas platform
• format file proyek yang disederhanakan
• referensi paket

Untuk menyelesaikan konversi dengan hati-hati, kami akan:

1. Buat cadangan file proyek asli.
2. Buat .dacpac file dari proyek asli untuk perbandingan.
3. Ubah file proyek menjadi proyek bergaya SDK.
4. Buat .dacpac file dari proyek yang dimodifikasi untuk perbandingan.
5. Verifikasi bahwa .dacpac filenya sama.

Proyek bergaya SDK tidak didukung di SQL Server Data Tools (SSDT) di Visual Studio. Setelah dikonversi, Anda harus menggunakan salah satu hal berikut untuk membangun atau mengedit proyek:

• baris perintah
• ekstensi Proyek SQL Database di Visual Studio Code
• ekstensi Proyek SQL Database di Azure Data Studio
• Alat Data SQL Server, gaya SDK (pratinjau) di Visual Studio 2022

Prasyarat

• .NET 8 SDK
• Komunitas Visual Studio 2022, Profesional, atau Perusahaan
• Menginstal SQL Server Data Tools (SSDT) untuk Visual Studio

• .NET 8 SDK
• Komunitas Visual Studio 2022, Profesional, atau Perusahaan
• SQL Server Data Tools bergaya SDK (pratinjau) yang diinstal di Visual Studio 2022

• .NET 8 SDK
• Visual Studio Code
• ekstensi Proyek SQL Database atau ekstensi Proyek SQL Database untuk VS Code

• .NET 8 SDK

Langkah 1: Buat cadangan file proyek asli

Sebelum Anda mengonversi proyek, buat cadangan file proyek asli. Dengan cara ini, Anda dapat kembali ke proyek asli jika diperlukan.

Di file explorer, buat salinan .sqlproj file untuk proyek yang ingin Anda konversi dengan .original ditambahkan di akhir ekstensi file. Misalnya, MyProject.sqlproj menjadi MyProject.sqlproj.original.

Langkah 2: Buat .dacpac file dari proyek asli untuk perbandingan

Buka proyek di Visual Studio 2022. File .sqlproj masih dalam format asli, jadi Anda membukanya di SQL Server Data Tools asli.

Buat proyek di Visual Studio dengan mengklik kanan simpul database di Penjelajah Solusi dan memilih Bangun.

Untuk membuat .dacpac file dari proyek asli, Anda harus menggunakan SQL Server Data Tools (SSDT) asli di Visual Studio. Buka file proyek di Visual Studio 2022 dengan SQL Server Data Tools asli terinstal.

Buat proyek di Visual Studio dengan mengklik kanan simpul database di Penjelajah Solusi dan memilih Bangun.

Buka folder proyek di VISUAL Code atau Azure Data Studio. Dalam tampilan Proyek Database visual Studio Code atau Azure Data Studio, klik kanan simpul proyek dan pilih Bangun.

Proyek database SQL dapat dibangun dari baris perintah menggunakan dotnet build perintah .

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

Proses build membuat .dacpac file di bin\Debug folder proyek secara default. Gunakan file explorer, temukan file .dacpac yang dibuat oleh proses build dan salin ke dalam folder baru di luar direktori proyek dengan nama original_project.dacpac. Kami menggunakan file ini .dacpac untuk perbandingan untuk memvalidasi konversi kami nanti.

Langkah 3: Ubah file proyek ke proyek bergaya SDK

Memodifikasi file proyek adalah proses manual, paling baik dilakukan di editor teks. .sqlproj Buka file di editor teks dan buat perubahan berikut:

Diperlukan: Tambahkan referensi SDK

Di dalam elemen proyek, tambahkan item Sdk untuk mereferensikan Microsoft.Build.Sql dan versi terbaru dari https://www.nuget.org/packages/Microsoft.build.sql tempat #.#.# disertakan dalam cuplikan di bawah ini.

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="4.0">
  <Sdk Name="Microsoft.Build.Sql" Version="#.#.#" />
...

Diperlukan: Menghapus impor target build yang tidak perlu

Proyek SQL asli mereferensikan beberapa target build dan properti dalam pernyataan Impor. Kecuali untuk <Import/> item yang Anda tambahkan secara eksplisit, yang merupakan perubahan unik dan sengaja, hapus baris yang dimulai dengan <Import ...>. Contoh yang harus dihapus jika ada dalam .sqlproj:

...
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
<Import Condition="..." Project="...\Microsoft.Data.Tools.Schema.SqlTasks.targets"/>
<Import Condition="'$(SQLDBExtensionsRefPath)' != ''" Project="$(SQLDBExtensionsRefPath)\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
<Import Condition="'$(SQLDBExtensionsRefPath)' == ''" Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
...

Diperlukan: Hapus folder Properties

Proyek SQL asli memiliki entri untuk Properties folder yang mewakili akses ke properti proyek di penjelajah solusi. Item ini perlu dihapus dari file proyek.

Contoh untuk menghapus jika terdapat di .sqlproj:

<ItemGroup>
  <Folder Include="Properties" />
</ItemGroup>

Diperlukan: Hapus item Build yang disertakan secara default

Proyek SQL asli mencantumkan semua file .sql yang mewakili objek database secara eksplisit dalam file proyek sebagai item <Build Include="..." />. Dalam proyek SQL gaya SDK, file .sql apa pun di pohon folder proyek (**/*.sql) disertakan secara default, jadi menghapus item <Build Include="...." /> untuk file tersebut diperlukan untuk menghindari masalah performa build.

Baris yang harus dihapus dari file proyek, misalnya:

  <Build Include="SalesLT/Products.sql" />
  <Build Include="SalesLT/SalesLT.sql" />
  <Build Include="SalesLT/Categories.sql" />
  <Build Include="SalesLT/CategoriesProductCount.sql" />

Anda tidak boleh menghapus item <PreDeploy Include="..." /> atau <PostDeploy Include="..." />, karena simpul ini menentukan perilaku tertentu untuk file tersebut. Anda juga tidak boleh menghapus item <Build Include="..." /> untuk file yang tidak ada di pohon folder proyek SQL.

Opsional: Menghapus referensi SSDT

SQL Server Data Tools (SSDT) asli memerlukan konten tambahan dalam file proyek untuk mendeteksi penginstalan Visual Studio. Baris ini tidak perlu dalam proyek SQL gaya SDK dan dapat dihapus:

  <PropertyGroup>
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">11.0</VisualStudioVersion>
    <!-- Default to the v11.0 targets path if the targets file for the current VS version is not found -->
    <SSDTExists Condition="Exists('$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets')">True</SSDTExists>
    <VisualStudioVersion Condition="'$(SSDTExists)' == ''">11.0</VisualStudioVersion>
  </PropertyGroup>

Opsional: Menghapus pengaturan build default

Proyek SQL asli mencakup dua blok besar untuk pengaturan build Rilis dan Debug, sementara dalam proyek SQL bergaya SDK, default untuk opsi ini diketahui oleh SDK. Jika Anda tidak memiliki kustomisasi ke pengaturan build, pertimbangkan untuk menghapus blok ini:

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <OutputPath>bin\Release\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>False</TreatWarningsAsErrors>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <DefineDebug>false</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <OutputPath>bin\Debug\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <DefineDebug>true</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>

Referensi properti proyek mencantumkan properti yang tersedia dan nilai defaultnya.

Langkah 4: Buat .dacpac file dari proyek yang dimodifikasi untuk perbandingan

Proyek SQL tidak lagi kompatibel dengan Visual Studio 2022. Untuk membangun atau mengedit proyek, Anda harus menggunakan salah satu dari:

• baris perintah
• ekstensi Proyek SQL Database di Visual Studio Code
• ekstensi Proyek SQL Database di Azure Data Studio
• Alat Data SQL Server, gaya SDK (pratinjau) di Visual Studio 2022

File proyek sekarang dalam format gaya SDK, tetapi untuk membukanya di Visual Studio 2022, Anda harus menginstal SQL Server Data Tools, gaya SDK (pratinjau) . Buka proyek di Visual Studio 2022 dengan SQL Server Data Tools, gaya SDK (pratinjau) yang terinstal.

Buka folder proyek di VISUAL Code atau Azure Data Studio. Dalam tampilan Proyek Database visual Studio Code atau Azure Data Studio, klik kanan simpul proyek dan pilih Bangun.

Proyek database SQL dapat dibangun dari baris perintah menggunakan dotnet build perintah .

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

Proses build membuat .dacpac file di bin\Debug folder proyek secara default. Dengan menggunakan penjelajah berkas (file explorer), temukan berkas .dacpac yang dibuat oleh proses penyusunan dan salin ke folder baru di luar direktori proyek. Kami menggunakan file ini .dacpac untuk perbandingan untuk memvalidasi konversi kami nanti.

Langkah 5: Verifikasi bahwa .dacpac filenya sama

Untuk memverifikasi bahwa konversi berhasil, bandingkan file yang .dacpac dibuat dari proyek asli dan yang dimodifikasi. Perbandingan skema kemampuan proyek SQL memungkinkan kami memvisualisasikan perbedaan model database antara dua file .dacpac. Atau, utilitas baris perintah DacpacVerify dapat digunakan untuk membandingkan dua file .dacpac, termasuk skrip pra/pasca-penyebaran dan pengaturan proyek.

DacpacVerify tersedia untuk diinstal sebagai dotnet tool . Untuk menginstal alat, jalankan perintah berikut:

dotnet tool install --global Microsoft.DacpacVerify --prerelease

Sintaks DacpacVerify adalah dengan menentukan jalur file untuk dua file .dacpac sebagai dacpacverify <source DACPAC path> <target DACPAC path>. Untuk membandingkan dua file .dacpac, jalankan perintah berikut:

DacpacVerify original_project.dacpac modified_project.dacpac

Anda dapat menggunakan alat perbandingan skema di Visual Studio atau Azure Data Studio untuk membandingkan objek dalam file .dacpac.

Luncurkan Visual Studio tanpa proyek yang dimuat. Buka Alat>SQL Server>Perbandingan Skema Baru. Pilih file asli .dacpac sebagai sumber dan file yang dimodifikasi .dacpac sebagai target. Untuk informasi selengkapnya tentang menggunakan Schema Compare di Visual Studio, lihat cara menggunakan perbandingan skema untuk membandingkan definisi database yang berbeda.

Perbandingan skema grafis belum tersedia dalam pratinjau proyek SQL bergaya SDK di Visual Studio. Gunakan Azure Data Studio untuk membandingkan skema.

Perbandingan skema tidak tersedia di Visual Studio Code. Gunakan Azure Data Studio atau Visual Studio untuk membandingkan skema.

Di Azure Data Studio, instal ekstensi SQL Server Schema Compare jika belum diinstal. Luncurkan perbandingan skema baru dari palet perintah dengan membuka palet perintah dengan Ctrl/Cmd+Shift+P dan mengetik Schema Compare.

Pilih file asli .dacpac sebagai sumber dan file yang dimodifikasi .dacpac sebagai target.

Perbandingan skema grafis tersedia di Visual Studio dan Azure Data Studio.

Ketika perbandingan skema dijalankan, tidak ada hasil yang harus ditampilkan. Kurangnya perbedaan menunjukkan bahwa proyek asli dan yang dimodifikasi setara, menghasilkan model database yang sama dalam .dacpac file.

Catatan

Perbandingan file .dacpac melalui perbandingan skema tidak memvalidasi skrip pra/pasca-penerapan, refaktorlog, atau pengaturan proyek lainnya. Ini hanya memvalidasi model database. Menggunakan utilitas baris perintah DacpacVerify adalah cara yang disarankan untuk memvalidasi bahwa dua file .dacpac setara.

Langkah 6: File solusi

File proyek Anda mungkin dirujuk dalam file solusi (.sln). Jika Anda memiliki file solusi, Anda harus memperbaruinya untuk mereferensikan file proyek gaya SDK baru.

Opsional: Membuat file solusi baru

Untuk file solusi yang hanya berisi proyek SQL, lebih mudah untuk menghapus file solusi dan membuat file solusi baru dengan proyek gaya SDK.

dotnet new sln --name MySolution
dotnet sln MySolution.sln add MyDatabaseProject\MyDatabaseProject.sqlproj

Opsional: Mengedit file solusi

Saat file solusi berisi beberapa proyek, Anda harus memperbarui file solusi untuk mereferensikan file proyek gaya SDK baru. Anda dapat mengedit file solusi di editor teks dan mengubah referensi proyek ke file proyek gaya SDK baru. Referensi proyek dalam file solusi akan terlihat seperti ini:

Project("{PROJECT_TYPE_GUID}") = "MyDatabaseProject", "MyDatabaseProject\MyDatabaseProject.sqlproj", "{PROJECT_GUID}"
EndProject

Nilai PROJECT_TYPE_GUID untuk proyek Microsoft.Build.Sql adalah 42EA0DBD-9CF1-443E-919E-BE9C484E4577, dan PROJECT_GUID adalah pengidentifikasi unik untuk proyek yang ditemukan dalam elemen file <ProjectGuid> proyek. Nilai PROJECT_GUID tidak diperlukan untuk diubah dan dapat tetap sama seperti dalam file proyek asli. Nilai PROJECT_TYPE_GUID diperlukan untuk diubah ke GUID jenis proyek Microsoft.Build.Sql.

Konten terkait

• Apa itu proyek database SQL?
• Mulai menggunakan proyek database SQL
• referensi proyek SQL paket