Menyambungkan dan mengkueri Azure SQL Database menggunakan .NET dan Entity Framework Core

Berlaku untuk:Azure SQL Database

Mulai cepat ini menjelaskan cara menyambungkan aplikasi ke database di Azure SQL Database dan melakukan kueri menggunakan .NET dan Entity Framework Core. Mulai cepat ini mengikuti pendekatan tanpa kata sandi yang direkomendasikan untuk menyambungkan ke database. Anda dapat mempelajari lebih lanjut tentang koneksi tanpa kata sandi di hub tanpa kata sandi.

Prasyarat

Langganan Azure.
Database SQL yang dikonfigurasi untuk autentikasi dengan ID Microsoft Entra (sebelumnya Azure Active Directory). Anda bisa membuatnya menggunakan Mulai Cepat: Membuat database tunggal - Azure SQL Database.
.NET 9.0 atau yang lebih baru.
Visual Studio versi terbaru atau lebih dengan beban kerja ASP.NET dan pengembangan web.
Versi terbaru dari Azure CLI.
Versi terbaru alat Entity Framework Core:
- Pengguna Visual Studio harus menginstal alat Konsol Manajer Paket untuk Entity Framework Core.
- Pengguna .NET CLI harus menginstal alat .NET CLI untuk Entity Framework Core.

Mengonfigurasi server database

Koneksi aman tanpa kata sandi ke Azure SQL Database memerlukan konfigurasi database tertentu. Verifikasi pengaturan berikut di server logis Anda di Azure untuk menyambungkan dengan benar ke Azure SQL Database di lingkungan lokal dan yang dihosting:

Untuk koneksi pengembangan lokal, pastikan server logis Anda dikonfigurasi untuk memungkinkan alamat IP komputer lokal Anda dan layanan Azure lainnya tersambung:
- Navigasi ke halaman Jaringan server Anda.
- Alihkan tombol radio Jaringan terpilih untuk menampilkan opsi konfigurasi tambahan.
- Pilih Tambahkan alamat IPv4 klien Anda(xx.xx.xx.xx) untuk menambahkan aturan firewall yang akan mengaktifkan koneksi dari alamat IPv4 komputer lokal Anda. Atau, Anda juga dapat memilih + Tambahkan aturan firewall untuk memasukkan alamat IP tertentu pilihan Anda.
- Pastikan kotak centang Izinkan layanan dan sumber daya Azure untuk mengakses server ini dipilih.
  Peringatan
  
  Mengaktifkan pengaturan Izinkan layanan dan sumber daya Azure untuk mengakses server ini bukanlah praktik keamanan yang direkomendasikan untuk skenario produksi. Aplikasi nyata harus menerapkan pendekatan yang lebih aman, seperti pembatasan firewall yang lebih kuat atau konfigurasi jaringan virtual.
  
  Anda bisa membaca selengkapnya tentang konfigurasi keamanan database pada sumber daya berikut:
  - Konfigurasikan aturan firewall Azure SQL Database.
  - Menyusun jaringan virtual dengan endpoint privat.
Server juga harus mengaktifkan autentikasi Microsoft Entra dan memiliki akun admin Microsoft Entra yang ditetapkan. Untuk koneksi pengembangan lokal, akun admin Microsoft Entra harus menjadi akun yang juga dapat Anda masuk ke Visual Studio atau Azure CLI dengan secara lokal. Anda dapat memverifikasi apakah server Anda mengaktifkan autentikasi Microsoft Entra di halaman ID Microsoft Entra server logis Anda.
Jika Anda menggunakan akun Azure pribadi, pastikan Anda sudah menyetel Microsoft Entra dan mengonfigurasikannya untuk Azure SQL Database agar dapat menetapkan akun Anda sebagai admin server. Jika Anda menggunakan akun perusahaan, ID Microsoft Entra kemungkinan besar sudah dikonfigurasi untuk Anda.

Membuat proyek

Langkah-langkah di bagian ini membuat .NET Minimal Web API dengan menggunakan .NET CLI atau Visual Studio 2022.

Visual Studio
.NET CLI

Di bilah menu Visual Studio, navigasikan ke >...
Di jendela dialog, masukkan ASP.NET ke dalam kotak pencarian templat proyek dan pilih hasil ASP.NET Core Web API. Pilih Berikutnya di bagian bawah dialog.
Untuk Nama Proyek, masukkan DotNetSQL. Biarkan nilai default di bidang lain dan pilih Berikutnya.
Untuk Kerangka Kerja, pilih .NET 9.0 dan hapus centang Gunakan pengontrol. Panduan memulai cepat ini menggunakan templat API Minimal untuk menyederhanakan pembuatan dan konfigurasi titik akhir.
Pilih Buat. Proyek baru terbuka di dalam lingkungan Visual Studio.

Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan dotnet new perintah untuk membuat aplikasi API Web baru dengan nama DotNetSQL. Perintah ini membuat proyek C# "Halo Dunia" sederhana dengan file sumber tunggal: Program.cs.
```
dotnet new web -o DotNetSQL
```
Navigasikan ke direktori DotNetSQL yang baru dibuat dan buka proyek di Visual Studio.

Menambahkan Entity Framework Core ke proyek

Untuk menyambungkan ke Azure SQL Database dengan menggunakan .NET dan Entity Framework Core, Anda perlu menambahkan tiga paket NuGet ke proyek Anda menggunakan salah satu metode berikut:

Visual Studio
.NET CLI

Di jendela Penjelajah Solusi, klik kanan simpul Dependensi proyek dan pilih Kelola Paket NuGet.
Di jendela yang dihasilkan, cari EntityFrameworkCore. Temukan dan instal paket berikut:

Microsoft.EntityFrameworkCore: Menyediakan fungsionalitas dasar Kerangka Kerja Entitas Core
Microsoft.EntityFrameworkCore.SqlServer: Menyediakan komponen tambahan untuk terhubung ke server logis
Microsoft.EntityFrameworkCore.Design: Menyediakan dukungan untuk menjalankan migrasi Kerangka Kerja Entitas
Microsoft.EntityFrameworkCore.Tools: Menyediakan dukungan untuk alat Konsol Manajer Paket Visual Studio (hanya PowerShell)
Swashbuckle.AspNetCore: Opsional - menyediakan dukungan untuk interaksi SwaggerUI dengan titik akhir aplikasi

dotnet add package Gunakan perintah untuk menginstal paket berikut:

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Swashbuckle.AspNetCore

Menambahkan kode untuk menyambungkan ke Azure SQL Database

Pustaka Entity Framework Core menggunakan pustaka Microsoft.Data.SqlClient dan Azure.Identity untuk mengimplementasikan koneksi tanpa kata sandi ke Azure SQL Database. Azure.Identity Pustaka menyediakan kelas yang disebut DefaultAzureCredential yang menangani autentikasi tanpa kata sandi ke Azure.

DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan mana yang akan digunakan pada runtime. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per lingkungan. Ikhtisar pustaka Azure Identity menjelaskan urutan dan lokasi di mana DefaultAzureCredential mencari kredensial.

Selesaikan langkah-langkah berikut untuk menyambungkan ke Azure SQL Database menggunakan Entity Framework Core dan kelas yang mendasar DefaultAzureCredential :

ConnectionStrings Tambahkan bagian ke appsettings.Development.json file sehingga cocok dengan kode berikut. Ganti dengan nama server database tanpa kata sandi yang ingin Anda sambungkan <server>.database.windows.net , dan <database> dengan nama database.
```
{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "ConnectionStrings": {
        "AZURE_SQL_CONNECTIONSTRING": "Data Source=<server>.database.windows.net;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
    }
}
```
Catatan

Ingatlah untuk memperbarui <your database-server-name> dan <your-database-name> placeholder dalam string koneksi database. String koneksi tanpa kata sandi aman untuk berkomitmen pada kontrol sumber, karena tidak berisi rahasia apa pun seperti nama pengguna, kata sandi, atau kunci akses.

string koneksi tanpa kata sandi menyertakan nilai konfigurasi Authentication=Active Directory Default, yang memungkinkan Entity Framework Core untuk menggunakan DefaultAzureCredential guna menyambungkan ke layanan Azure. Saat aplikasi berjalan secara lokal, aplikasi akan mengautentikasi dengan pengguna yang Anda gunakan untuk masuk ke Visual Studio. Setelah aplikasi disebarkan ke Azure, kode yang sama menemukan dan menerapkan identitas terkelola yang terkait dengan aplikasi yang dihosting, yang Anda konfigurasikan nanti.

Ganti isi file Program.cs dengan kode berikut:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var connection = String.Empty;
if (builder.Environment.IsDevelopment())
{
    builder.Configuration.AddEnvironmentVariables().AddJsonFile("appsettings.Development.json");
    connection = builder.Configuration.GetConnectionString("AZURE_SQL_CONNECTIONSTRING");
}
else
{
    connection = Environment.GetEnvironmentVariable("AZURE_SQL_CONNECTIONSTRING");
}

builder.Services.AddDbContext<PersonDbContext>(options =>
    options.UseSqlServer(connection));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });
}

app.MapGet("/", () => "Hello world!");

app.MapGet("/Person", (PersonDbContext context) =>
{
    return context.Person.ToList();
});

app.MapPost("/Person", (Person person, PersonDbContext context) =>
{
    context.Add(person);
    context.SaveChanges();
});

app.Run();

public class Person
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class PersonDbContext : DbContext
{
    public PersonDbContext(DbContextOptions<PersonDbContext> options)
        : base(options)
    {
    }

    public DbSet<Person> Person { get; set; }
}

Kode sebelumnya menangani langkah-langkah berikut:

Mengambil string koneksi database tanpa kata sandi dari file appsettings.Development.json untuk pengembangan lokal, atau dari variabel lingkungan untuk skenario produksi yang dihosting.
Mendaftarkan kelas Entity Framework Core DbContext dengan kontainer injeksi dependensi .NET. Anda dapat membaca lebih lanjut tentang DbContext dalam panduan Memulai dokumentasi untuk Entity Framework Core.
Mengonfigurasi dukungan .NET 9.0 OpenAPI dengan SwaggerUI untuk menyediakan UI yang dapat Anda gunakan untuk berinteraksi dengan titik akhir dan database aplikasi.
Menambahkan titik akhir untuk mengambil dan menambahkan entitas dalam database.
Mendefinisikan kelas Person untuk mewakili satu rekaman dalam tabel database Persons, serta kelas PersonDbContext yang telah terdaftar dalam kontainer injeksi dependensi .NET.

Menjalankan migrasi untuk membuat database

Untuk memperbarui skema database agar sesuai dengan model data Anda menggunakan Entity Framework Core, Anda harus menggunakan migrasi. Migrasi dapat membuat dan memperbarui skema database secara bertahap agar tetap sinkron dengan model data aplikasi Anda. Anda dapat mempelajari selengkapnya tentang pola ini dalam gambaran umum migrasi.

Buka jendela terminal ke akar proyek Anda.
Jalankan perintah berikut untuk menghasilkan migrasi awal yang dapat membuat database:
- Visual Studio
- .NET CLI
```
Add-Migration InitialCreate
```
```
dotnet ef migrations add InitialCreate
```

Folder Migrations akan muncul di direktori proyek Anda, bersama dengan file yang disebut InitialCreate dengan angka unik yang telah ditambahkan sebelumnya. Jalankan migrasi untuk membuat database menggunakan perintah berikut, dan alat Entity Framework Core membuat skema database di Azure yang PersonDbContext ditentukan oleh kelas .
- Visual Studio
- .NET CLI
```
Update-Database
```
```
dotnet ef database update
```

Uji aplikasi secara lokal

Aplikasi ini siap untuk diuji secara lokal. Pastikan Anda masuk ke Visual Studio atau Azure CLI dengan akun yang sama dengan yang Anda tetapkan sebagai admin untuk database Anda.

Tekan tombol jalankan di bagian atas Visual Studio untuk meluncurkan proyek API.
Pada halaman UI Swagger, perluas metode POST dan pilih Coba.
Ubah contoh JSON untuk menyertakan nilai untuk nama depan dan nama keluarga. Pilih Jalankan untuk menambahkan rekaman baru ke database. API mengembalikan respons yang berhasil.
GET Perluas metode pada halaman antarmuka pengguna Swagger dan pilih Coba. Pilih Jalankan, dan orang yang baru saja Anda buat dikembalikan.

Menyebarkan ke Azure App Service

Aplikasi ini siap disebarkan ke Azure. Visual Studio dapat membuat Azure App Service dan menyebarkan aplikasi Anda dalam satu alur kerja.

Pastikan aplikasi dihentikan dan berhasil dibuat.
Di jendela Penjelajah Solusi Visual Studio, klik kanan pada simpul proyek tingkat atas dan pilih Terbitkan.
Dalam dialog penerbitan, pilih Azure sebagai target penyebaran, lalu pilih Berikutnya.
Untuk target tertentu, pilih Azure App Service (Windows), lalu pilih Berikutnya.
Pilih ikon hijau + untuk membuat App Service baru untuk disebarkan dan masukkan nilai berikut:
- Nama: Biarkan nilai default.
- Nama langganan: Pilih langganan yang akan disebarkan.
- Grup sumber daya: Pilih Baru dan buat grup sumber daya baru yang disebut msdocs-dotnet-sql.
- Paket Hosting: Pilih Baru untuk membuka dialog paket hosting. Biarkan nilai default dan pilih OK.
- Pilih Buat untuk menutup dialog asli. Visual Studio membuat sumber daya App Service di Azure.
Setelah sumber daya dibuat, pastikan Anda memilih dalam daftar layanan aplikasi, lalu pilih Berikutnya.
Pada langkah API Management, pilih kotak centang Lewati langkah ini di bagian bawah lalu pilih Selesai.
Pilih Terbitkan di kanan atas ringkasan profil penerbitan untuk menyebarkan aplikasi ke Azure.

Setelah penyebaran selesai, Visual Studio meluncurkan browser untuk menampilkan aplikasi yang dihosting. Anda akan melihat Hello world pesan dari titik akhir default. Namun, pada titik ini titik akhir database tidak berfungsi dengan benar di Azure. Anda masih perlu mengonfigurasi koneksi aman antara App Service dan database SQL untuk mengambil data Anda.

Menyambungkan App Service ke Azure SQL Database

Langkah-langkah berikut diperlukan untuk menyambungkan instans App Service ke Azure SQL Database:

Buat identitas terkelola untuk App Service. Pustaka Microsoft.Data.SqlClient yang disertakan dalam aplikasi Anda secara otomatis menemukan identitas terkelola, sama seperti menemukan pengguna Visual Studio lokal Anda.
Buat pengguna database SQL dan kaitkan dengan identitas terkelola App Service.
Tetapkan peran SQL ke pengguna database yang memungkinkan izin baca, tulis, dan berpotensi lainnya.

Ada beberapa alat yang tersedia untuk menerapkan langkah-langkah ini:

Konektor Layanan (Disarankan)
Portal Azure

Konektor Layanan adalah alat yang menyederhanakan koneksi terautentikasi antara layanan yang berbeda di Azure. Konektor Layanan saat ini mendukung menyambungkan App Service ke database SQL menggunakan ekstensi tanpa kata sandi Azure CLI.

Instal atau tingkatkan ekstensi tanpa kata sandi Konektor Layanan:
```
az extension add --name serviceconnector-passwordless --upgrade
```

Jalankan az webapp connection create sql perintah untuk menyambungkan aplikasi web Anda ke database menggunakan identitas terkelola yang ditetapkan sistem. Ganti tempat penampung dengan nilai yang sesuai:

az webapp connection create sql
-g <your-resource-group>
-n <your-app-service-name>
--tg <your-database-server-resource-group>
--server <your-database-server-name>
--database <your-database-name>
--system-identity

Anda dapat memverifikasi perubahan yang dibuat oleh Konektor Layanan pada pengaturan App Service.

Navigasi ke halaman Identitas untuk App Service Anda. Di bawah tab Sistem yang ditetapkan, Status harus diatur ke Aktif. Nilai ini berarti bahwa identitas terkelola yang ditetapkan sistem diaktifkan untuk aplikasi Anda.
Navigasi ke halaman Konfigurasi untuk App Service Anda. Di bawah tab String koneksi , Anda akan melihat string koneksi yang disebut AZURE_SQL_CONNECTIONSTRING. Pilih Klik untuk menampilkan teks nilai untuk melihat string koneksi tanpa kata sandi yang dihasilkan. Nama string koneksi ini selaras dengan yang Anda konfigurasi di aplikasi Anda, sehingga ditemukan secara otomatis saat berjalan di Azure.

portal Azure memungkinkan Anda bekerja dengan identitas terkelola dan menjalankan kueri terhadap Azure SQL Database. Selesaikan langkah-langkah berikut untuk membuat koneksi tanpa kata sandi dari instans App Service Anda ke Azure SQL Database:

Buat identitas terkelola

Di portal Azure, navigasikan ke App Service Anda dan pilih Identitas di navigasi kiri.
Pada halaman identitas, pastikan opsi Aktifkan identitas terkelola yang ditetapkan sistem diaktifkan. Saat pengaturan ini diaktifkan, identitas terkelola yang ditetapkan sistem dibuat dengan nama yang sama dengan App Service Anda. Identitas yang ditetapkan sistem terikat dengan instance layanan dan akan dihancurkan bersama aplikasi saat aplikasi tersebut dihapus.

Membuat pengguna database dan menetapkan peran

Di portal Azure, telusuri ke database SQL Anda dan pilih Editor kueri (pratinjau).
Pilih **Lanjutkan seperti <your-username> di sisi kanan layar untuk masuk ke database menggunakan akun Anda.
Pada tampilan editor kueri, jalankan perintah T-SQL berikut ini. Ganti <your-app-service-name> dengan nama layanan aplikasi Anda.
```
CREATE USER <your-app-service-name> FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER <your-app-service-name>;
ALTER ROLE db_datawriter ADD MEMBER <your-app-service-name>;
ALTER ROLE db_ddladmin ADD MEMBER <your-app-service-name>;
GO
```
Skrip SQL ini membuat pengguna database SQL yang terhubung kembali ke identitas terkelola dari instans App Service Anda. Ini juga menetapkan peran SQL yang diperlukan kepada pengguna untuk memungkinkan aplikasi Anda membaca, menulis, dan memodifikasi data dan skema database Anda. Setelah langkah ini selesai, layanan Anda tersambung.

Penting

Meskipun solusi ini menyediakan pendekatan sederhana untuk memulai, solusi ini bukan praktik terbaik untuk lingkungan produksi perusahaan. Dalam skenario tersebut, aplikasi tidak boleh melakukan semua operasi menggunakan satu identitas yang ditingkatkan. Anda harus mencoba menerapkan prinsip hak istimewa paling sedikit dengan mengonfigurasi beberapa identitas dengan izin tertentu untuk tugas tertentu. Untuk informasi selengkapnya tentang mengonfigurasi peran dan keamanan database, lihat:

Menguji aplikasi yang disebarkan

Telusuri ke URL aplikasi untuk menguji bahwa koneksi ke Azure SQL Database berfungsi. Anda dapat menemukan URL aplikasi Anda di halaman ringkasan App Service. Tambahkan /person jalur ke akhir URL untuk menelusuri ke titik akhir yang sama dengan yang Anda uji secara lokal.

Orang yang Anda buat secara lokal harus ditampilkan di browser. Selamat, aplikasi Anda sekarang terhubung ke Azure SQL Database di lingkungan lokal dan yang dihosting.

Membersihkan sumber daya

Setelah selesai bekerja dengan Azure SQL Database, hapus sumber daya untuk menghindari biaya yang tidak diinginkan.

Portal Azure
Azure CLI

Di bilah pencarian portal Azure, cari Azure SQL dan pilih hasil yang cocok.
Temukan dan pilih database Anda dalam daftar database.
Pada halaman Gambaran Umum Azure SQL Database Anda, pilih Hapus.
Pada halaman Azure yang Anda yakin ingin hapus... yang terbuka, ketik nama database Anda untuk mengonfirmasi, lalu pilih Hapus.

Hapus database Anda dengan menggunakan az sql db delete perintah . Ganti parameter tempat penampung dengan nilai Anda sendiri.

az sql db delete --name <database-name> --resource-group <resource-group-name> --server <logical-server-name>

Catatan

Jika Anda menyebarkan aplikasi sampel ke Azure, pastikan juga mencari dan menghapus sumber daya App Service untuk menghindari biaya yang tidak diinginkan.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-08-07