Mengonversi proyek SQL asli ke proyek bergaya SDK

Berlaku untuk:SQL Server Azure SQL Database Azure SQL Managed Instance Database SQL di Microsoft Fabric

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

Setelah mengonversi project, Anda dapat menggunakan fitur baru project bergaya SDK, seperti:

Dukungan kompilasi lintas platform
Format file proyek yang disederhanakan
Referensi Paket

Untuk menyelesaikan konversi dengan hati-hati, ikuti langkah-langkah berikut:

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

SQL Server Data Tools (SSDT) di Visual Studio tidak mendukung proyek bergaya SDK. Setelah Anda mengonversi proyek, gunakan salah satu alat berikut untuk membuat atau mengedit proyek:

Ekstensi SQL Database Projects di Visual Studio Code
DevOps Database di SQL Server Management Studio (SSMS)
Baris perintah
SQL Server Data Tools, gaya SDK (pratinjau) di Visual Studio 2022

Note

Anda mungkin menemukan bahwa proyek SQL Anda berisi kustomisasi yang memperluas perubahan yang diperlukan di luar langkah-langkah ini. Selain artikel ini, repositori GitHub DacFx dapat digunakan untuk memahami perubahan yang diperlukan untuk meningkatkan dari proyek SQL asli ke proyek SQL bergaya SDK.

Prerequisites

SDK .NET 10

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 ke ekstensi file. Misalnya, MyProject.sqlproj menjadi MyProject.sqlproj.original.

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

Buka proyek di Visual Studio. 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 dengan Alat Data SQL Server asli terinstal.

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

Buka folder proyek di Visual Studio Code. Dalam tampilan Proyek Database Visual Studio Code, klik kanan simpul proyek dan pilih 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 dengan Alat Data SQL Server asli terinstal.

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

Anda dapat membangun proyek database SQL 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 File Explorer, temukan .dacpac yang dibuat oleh proses build dan salin ke dalam folder baru di luar direktori proyek sebagai original_project.dacpac. Gunakan file ini .dacpac untuk perbandingan untuk memvalidasi konversi Anda 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. Hapus item ini 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 apa pun .sql dalam hierarki folder proyek (**/*.sql) disertakan secara default. Hapus file .sql yang ditentukan dalam item <Build Include="...." /> untuk file tersebut guna menghindari masalah performa build.

Hapus baris seperti berikut dari file proyek:

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

Jangan hapus:

<Build Include="..." /> item untuk .sql file yang tidak berada di struktur folder proyek SQL
<PreDeploy Include="..." /> atau <PostDeploy Include="..." /> item, karena simpul ini menentukan perilaku tertentu untuk file tersebut
Item yang bukan .sql file, seperti .publish.xml file dalam <None Include="..." /> item, .refactorlog.xml file dalam <RefactorLog Include="..." /> item, atau .xsd file dalam <Build Include="..." /> item

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 menyertakan dua blok besar untuk pengaturan build Rilis dan Debug, sedangkan dalam proyek SQL bergaya SDK, SDK mengetahui default untuk opsi ini. 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: File solusi

File proyek Anda mungkin dirujuk dalam file solusi (.sln). Jika Anda memiliki file solusi, perbarui untuk mereferensikan file proyek bergaya SDK baru. Jika Anda tidak memiliki file solusi, Anda dapat melewati bagian ini dan melanjutkan ke Langkah 5.

Opsi 1: Membuat file solusi baru

Jika file solusi hanya berisi project SQL, akan lebih mudah untuk menghapus file solusi dan membuat file solusi baru dengan project bergaya SDK.

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

Opsi 2: Edit file penyelesaian

Jika file solusi berisi beberapa proyek, perbarui file solusi untuk mereferensikan file proyek bergaya 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. PROJECT_GUID ini adalah pengenal unik untuk proyek yang terdapat dalam elemen <ProjectGuid> pada file proyek. Jika Anda memiliki file solusi dengan proyek, Anda tidak perlu mengubah nilainya PROJECT_GUID . Ubah nilai PROJECT_TYPE_GUID menjadi GUID jenis proyek Microsoft.Build.Sql.

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

Proyek SQL tidak lagi kompatibel dengan Visual Studio 2022. Untuk membuat atau mengedit proyek, gunakan salah satu opsi berikut:

Baris perintah
Ekstensi SQL Database Projects di Visual Studio Code
SQL Server Data Tools, gaya SDK (pratinjau) di Visual Studio 2022
SQL Server Management Studio (SSMS) dengan beban kerja Database DevOps (pratinjau)

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 Studio Code. Dalam tampilan Proyek Database Visual Studio Code, klik kanan simpul proyek dan pilih Bangun.

Buka file proyek di SQL Server Management Studio (SSMS) dengan workload Database DevOps (pratinjau) yang sudah terpasang. Di Object Explorer, klik kanan pada proyek database dan pilih Bangun.

Anda dapat membangun proyek database SQL 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. Di File Explorer, temukan .dacpac yang dibuat oleh proses build dan salin ke dalam folder baru di luar direktori proyek. Gunakan file ini .dacpac untuk perbandingan untuk memvalidasi konversi Anda nanti.

Langkah 6: Verifikasi bahwa `.dacpac` filenya sama

Untuk memverifikasi bahwa konversi berhasil, bandingkan file yang .dacpac dibuat dari proyek asli dan yang dimodifikasi. Gunakan kemampuan perbandingan skema proyek SQL untuk memvisualisasikan perbedaan model database antara kedua .dacpac file. Atau, gunakan utilitas baris perintah DacpacVerify untuk membandingkan kedua .dacpac file, termasuk skrip pra/pasca-penyebaran dan pengaturan proyeknya.

Anda dapat menginstal DacpacVerify sebagai alat dotnet. 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 untuk membandingkan .dacpac objek dalam file.

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 Visual Studio Code untuk membandingkan skema.

Di Visual Studio Code, 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 tidak tersedia di SQL Server Management Studio. Gunakan Visual Studio Code atau Visual Studio untuk membandingkan skema.

Perbandingan skema grafis tersedia di Visual Studio dan Visual Studio Code.

Saat Anda menjalankan perbandingan skema, tidak ada hasil yang akan ditampilkan. Kurangnya perbedaan menunjukkan bahwa proyek asli dan yang dimodifikasi setara, menghasilkan model database yang sama dalam .dacpac file.

Note

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.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-22

Mengonversi proyek SQL asli ke proyek bergaya SDK

Prerequisites

Langkah 1: Buat cadangan file proyek asli

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

Langkah 3: Ubah file proyek ke proyek bergaya SDK

Diperlukan: Tambahkan referensi SDK

Diperlukan: Menghapus impor target build yang tidak perlu

Diperlukan: Hapus folder Properties

Diperlukan: Hapus item Build yang disertakan secara default

Opsional: Menghapus referensi SSDT

Opsional: Menghapus pengaturan build default

Langkah 4: File solusi

Opsi 1: Membuat file solusi baru

Opsi 2: Edit file penyelesaian

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

Langkah 6: Verifikasi bahwa .dacpac filenya sama

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

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

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

Langkah 6: Verifikasi bahwa `.dacpac` filenya sama