Połączenie do usługi Azure SQL Database i wykonywania zapytań względem usługi Azure SQL Database przy użyciu platformy .NET i biblioteki Microsoft.Data.SqlClient

Dotyczy:Azure SQL Database

W tym przewodniku Szybki start opisano sposób łączenia aplikacji z bazą danych w usłudze Azure SQL Database i wykonywania zapytań przy użyciu platformy .NET i biblioteki Microsoft.Data.SqlClient . Ten przewodnik Szybki start jest zgodny z zalecanym podejściem bez hasła w celu nawiązania połączenia z bazą danych. Więcej informacji na temat połączeń bez hasła można uzyskać w centrum bez hasła.

Wymagania wstępne

• Subskrypcja platformy Azure.
• Baza danych Azure SQL Database skonfigurowana do uwierzytelniania przy użyciu identyfikatora Entra firmy Microsoft (dawniej Azure Active Directory). Możesz go utworzyć, korzystając z przewodnika Szybki start Tworzenie bazy danych.
• Najnowsza wersja interfejsu wiersza polecenia platformy Azure.
• Program Visual Studio lub nowszy z obciążeniem tworzenia aplikacji internetowych i ASP.NET.
• .NET 7.0 lub nowszy.

Konfigurowanie bazy danych

Bezpieczne, bez hasła połączenia z usługą Azure SQL Database wymagają pewnych konfiguracji bazy danych. Sprawdź następujące ustawienia na serwerze logicznym na platformie Azure , aby prawidłowo nawiązać połączenie z usługą Azure SQL Database w środowiskach lokalnych i hostowanych:

1. W przypadku lokalnych połączeń programistycznych upewnij się, że serwer logiczny jest skonfigurowany tak, aby zezwolić na nawiązywanie połączenia z adresem IP komputera lokalnego i innymi usługami platformy Azure:

   • Przejdź do strony Sieć serwera.

   • Przełącz przycisk radiowy Wybrane sieci, aby wyświetlić dodatkowe opcje konfiguracji.

   • Wybierz pozycję Dodaj adres IPv4 klienta (xx.xx.xx.xx.xx ), aby dodać regułę zapory, która umożliwi połączenia z adresu IPv4 komputera lokalnego. Alternatywnie możesz również wybrać pozycję + Dodaj regułę zapory, aby wprowadzić wybrany konkretny adres IP.

   • Upewnij się, że pole wyboru Zezwalaj usługom i zasobom platformy Azure na dostęp do tego serwera jest zaznaczone.

     

     Ostrzeżenie

     Włączenie opcji Zezwalaj usługom i zasobom platformy Azure na dostęp do tego ustawienia serwera nie jest zalecaną praktyką zabezpieczeń w scenariuszach produkcyjnych. Rzeczywiste aplikacje powinny implementować bezpieczniejsze podejścia, takie jak silniejsze ograniczenia zapory lub konfiguracje sieci wirtualnej.

     Więcej informacji na temat konfiguracji zabezpieczeń bazy danych można uzyskać w następujących zasobach:

     • Konfigurowanie reguł zapory usługi Azure SQL Database.
     • Konfigurowanie sieci wirtualnej z prywatnymi punktami końcowymi.

2. Serwer musi również mieć włączone uwierzytelnianie Microsoft Entra i mieć przypisane konto administratora firmy Microsoft Entra. W przypadku lokalnych połączeń programistycznych konto administratora firmy Microsoft Entra powinno być kontem, które można również zalogować się do programu Visual Studio lub interfejsu wiersza polecenia platformy Azure lokalnie. Możesz sprawdzić, czy serwer ma włączone uwierzytelnianie firmy Microsoft Entra na stronie Identyfikator entra firmy Microsoft serwera logicznego.

   

3. Jeśli używasz osobistego konta platformy Azure, upewnij się, że masz konfigurację usługi Microsoft Entra i skonfigurowaną dla usługi Azure SQL Database w celu przypisania konta jako administratora serwera. Jeśli używasz konta firmowego, identyfikator Firmy Microsoft najprawdopodobniej zostanie już skonfigurowany.

Tworzenie projektu

Aby wykonać te kroki, utwórz minimalny internetowy interfejs API platformy .NET przy użyciu interfejsu wiersza polecenia platformy .NET lub programu Visual Studio 2022.

Program Visual Studio

1. W menu programu Visual Studio przejdź do pozycji Plik>nowy>projekt...

2. W oknie dialogowym wprowadź ASP.NET w polu wyszukiwania szablonu projektu i wybierz wynik ASP.NET Core Web API. Wybierz pozycję Dalej w dolnej części okna dialogowego.

3. W polu Nazwa projektu wprowadź wartość DotNetSQL. Pozostaw wartości domyślne pozostałych pól i wybierz pozycję Dalej.

4. W obszarze Framework wybierz pozycję .NET 7.0 i usuń zaznaczenie pola wyboru Użyj kontrolerów (usuń zaznaczenie, aby używać minimalnych interfejsów API).. W tym przewodniku Szybki start użyto szablonu interfejsu API minimalnego w celu usprawnienia tworzenia i konfigurowania punktu końcowego.

5. Wybierz pozycję Utwórz. Nowy projekt zostanie otwarty w środowisku programu Visual Studio.

Interfejs wiersza polecenia platformy .NET

1. W oknie konsoli (takim jak cmd, PowerShell lub Bash) użyj dotnet new polecenia , aby utworzyć nową aplikację internetowego interfejsu API o nazwie DotNetSQL. To polecenie tworzy prosty projekt języka C# "Hello World" z jednym plikiem źródłowym: Program.cs.

   dotnet new web -o DotNetSQL
   

2. Przejdź do nowo utworzonego katalogu DotNetSQL i otwórz projekt w programie Visual Studio.

Dodawanie biblioteki Microsoft.Data.SqlClient

Aby nawiązać połączenie z usługą Azure SQL Database przy użyciu platformy .NET, zainstaluj program Microsoft.Data.SqlClient. Ten pakiet działa jako dostawca danych do nawiązywania połączenia z bazami danych, wykonywania poleceń i pobierania wyników.

Uwaga

Pamiętaj, aby zainstalować program Microsoft.Data.SqlClient , a nie System.Data.SqlClient. Microsoft.Data.SqlClient to nowsza wersja biblioteki klienta SQL, która zapewnia dodatkowe możliwości.

Program Visual Studio

1. W oknie Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł Zależności projektu i wybierz polecenie Zarządzaj pakietami NuGet.

2. W wyświetlonym oknie wyszukaj wartość SqlClient. Microsoft.Data.SqlClient Znajdź wynik i wybierz pozycję Zainstaluj.

Interfejs wiersza polecenia platformy .NET

Użyj następującego polecenia, aby zainstalować Microsoft.Data.SqlClient pakiet:

dotnet add package Microsoft.Data.SqlClient

Konfigurowanie parametrów połączenia

Bez hasła (zalecane)

W przypadku programowania lokalnego z połączeniami bez hasła z usługą Azure SQL Database dodaj następującą ConnectionStrings sekcję appsettings.json do pliku. <database-server-name> Zastąp symbole zastępcze i <database-name> własnymi wartościami.

"ConnectionStrings": {
    "AZURE_SQL_CONNECTIONSTRING": "Server=tcp:<database-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Authentication=\"Active Directory Default\";"
}

Bez hasła parametry połączenia ustawia wartość Authentication="Active Directory Default"konfiguracji , która instruuje Microsoft.Data.SqlClient bibliotekę w celu nawiązania połączenia z usługą Azure SQL Database przy użyciu klasy o nazwie DefaultAzureCredential. DefaultAzureCredential włącza połączenia bez hasła z usługami platformy Azure i jest zapewniana przez bibliotekę tożsamości platformy Azure, od której zależy biblioteka klienta SQL. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, które z nich mają być używane w czasie wykonywania dla różnych środowisk.

Na przykład gdy aplikacja działa lokalnie, DefaultAzureCredential uwierzytelnia się za pośrednictwem zalogowanego użytkownika do programu Visual Studio lub innych narzędzi lokalnych, takich jak interfejs wiersza polecenia platformy Azure. Po wdrożeniu aplikacji na platformie Azure ten sam kod odnajduje i stosuje tożsamość zarządzaną skojarzona z hostowaną aplikacją, którą skonfigurujesz później. Omówienie biblioteki tożsamości platformy Azure wyjaśnia kolejność i lokalizacje, w których DefaultAzureCredential szuka poświadczeń.

Uwaga

Bez hasła parametry połączenia są bezpieczne do zatwierdzania kontroli źródła, ponieważ nie zawierają wpisów tajnych, takich jak nazwy użytkowników, hasła lub klucze dostępu.

Uwierzytelnianie SQL

W przypadku programowania lokalnego przy użyciu uwierzytelniania SQL w usłudze Azure SQL Database dodaj następującą ConnectionStrings sekcję appsettings.json do pliku. Zastąp <database-server-name>symbole zastępcze , <database-name>, <user-id>i <password> własnymi wartościami.

"ConnectionStrings": {
    "AZURE_SQL_CONNECTIONSTRING": "Server=tcp:<database-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Persist Security Info=False;User ID=<user-id>;Password=<password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;"
}

Ostrzeżenie

Należy zachować ostrożność podczas zarządzania parametry połączenia, które zawierają wpisy tajne, takie jak nazwy użytkowników, hasła lub klucze dostępu. Te wpisy tajne nie powinny być zatwierdzane w kontroli źródła ani umieszczane w niezabezpieczonych lokalizacjach, w których mogą uzyskiwać do nich dostęp niezamierzeni użytkownicy. Podczas programowania lokalnego w rzeczywistej aplikacji na ogół połączysz się z lokalną bazą danych, która nie wymaga przechowywania wpisów tajnych ani łączenia się bezpośrednio z platformą Azure.

Dodawanie kodu w celu nawiązania połączenia z usługą Azure SQL Database

Zastąp zawartość Program.cs pliku następującym kodem, który wykonuje następujące ważne kroki:

• Pobiera parametry połączenia bez hasła zappsettings.json
• Tworzy tabelę Persons w bazie danych podczas uruchamiania (tylko w przypadku scenariuszy testowania)
• Tworzy punkt końcowy HTTP GET w celu pobrania wszystkich rekordów przechowywanych w Persons tabeli
• Tworzy punkt końcowy HTTP POST w celu dodania Persons nowych rekordów do tabeli

using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// For production scenarios, consider keeping Swagger configurations behind the environment check
// if (app.Environment.IsDevelopment())
// {
    app.UseSwagger();
    app.UseSwaggerUI();
// }

app.UseHttpsRedirection();

string connectionString = app.Configuration.GetConnectionString("AZURE_SQL_CONNECTIONSTRING")!;

try
{
    // Table would be created ahead of time in production
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "CREATE TABLE Persons (ID int NOT NULL PRIMARY KEY IDENTITY, FirstName varchar(255), LastName varchar(255));",
        conn);
    using SqlDataReader reader = command.ExecuteReader();
}
catch (Exception e)
{
    // Table may already exist
    Console.WriteLine(e.Message);
}

app.MapGet("/Person", () => {
    var rows = new List<string>();

    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand("SELECT * FROM Persons", conn);
    using SqlDataReader reader = command.ExecuteReader();

    if (reader.HasRows)
    {
        while (reader.Read())
        {
            rows.Add($"{reader.GetInt32(0)}, {reader.GetString(1)}, {reader.GetString(2)}");
        }
    }

    return rows;
})
.WithName("GetPersons")
.WithOpenApi();

app.MapPost("/Person", (Person person) => {
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "INSERT INTO Persons (firstName, lastName) VALUES (@firstName, @lastName)",
        conn);

    command.Parameters.Clear();
    command.Parameters.AddWithValue("@firstName", person.FirstName);
    command.Parameters.AddWithValue("@lastName", person.LastName);

    using SqlDataReader reader = command.ExecuteReader();
})
.WithName("CreatePerson")
.WithOpenApi();

app.Run();

Na koniec dodaj klasę Person do dołu Program.cs pliku. Ta klasa reprezentuje pojedynczy rekord w tabeli bazy danych Persons .

public class Person
{
    public required string FirstName { get; set; }
    public required string LastName { get; set; }
}

Uruchamianie i testowanie aplikacji lokalnie

Aplikacja jest gotowa do testowania lokalnie. Upewnij się, że logujesz się do programu Visual Studio lub interfejsu wiersza polecenia platformy Azure przy użyciu tego samego konta, które zostało ustawione jako administrator bazy danych.

1. Naciśnij przycisk Uruchom w górnej części programu Visual Studio, aby uruchomić projekt interfejsu API.

2. Na stronie Swagger UI rozwiń metodę POST i wybierz pozycję Wypróbuj.

3. Zmodyfikuj przykładowy kod JSON, aby uwzględnić wartości dla pierwszego i nazwiska. Wybierz pozycję Wykonaj , aby dodać nowy rekord do bazy danych. Interfejs API zwraca pomyślną odpowiedź.

   

4. Rozwiń metodę GET na stronie interfejsu użytkownika programu Swagger i wybierz pozycję Wypróbuj. Wybierz pozycję Wykonaj, a utworzona osoba zostanie zwrócona.

Wdrażanie w usłudze Azure App Service

Aplikacja jest gotowa do wdrożenia na platformie Azure. Program Visual Studio może utworzyć usługę aplikacja systemu Azure i wdrożyć aplikację w jednym przepływie pracy.

1. Upewnij się, że aplikacja została zatrzymana i została pomyślnie skompilowana.

2. W oknie Eksplorator rozwiązań programu Visual Studio kliknij prawym przyciskiem myszy węzeł projektu najwyższego poziomu i wybierz pozycję Publikuj.

3. W oknie dialogowym publikowania wybierz pozycję Azure jako element docelowy wdrożenia, a następnie wybierz pozycję Dalej.

4. Dla określonego elementu docelowego wybierz pozycję aplikacja systemu Azure Service (Windows), a następnie wybierz przycisk Dalej.

5. Wybierz ikonę, + aby utworzyć nową usługę App Service do wdrożenia, a następnie wprowadź następujące wartości:

   • Nazwa: pozostaw wartość domyślną.

   • Nazwa subskrypcji: wybierz subskrypcję do wdrożenia.

   • Grupa zasobów: wybierz pozycję Nowy i utwórz nową grupę zasobów o nazwie msdocs-dotnet-sql.

   • Plan hostingu: wybierz pozycję Nowy , aby otworzyć okno dialogowe planu hostingu. Pozostaw wartości domyślne i wybierz przycisk OK.

   • Wybierz pozycję Utwórz , aby zamknąć oryginalne okno dialogowe. Program Visual Studio tworzy zasób usługi App Service na platformie Azure.

     

6. Po utworzeniu zasobu upewnij się, że został wybrany na liście usług app Services, a następnie wybierz pozycję Dalej.

7. W kroku API Management zaznacz pole wyboru Pomiń ten krok u dołu, a następnie wybierz pozycję Zakończ.

8. W kroku Zakończ wybierz pozycję Zamknij , jeśli okno dialogowe nie zostanie zamknięte automatycznie.

9. Wybierz pozycję Publikuj w prawym górnym rogu podsumowania profilu publikowania, aby wdrożyć aplikację na platformie Azure.

Po zakończeniu wdrażania program Visual Studio uruchamia przeglądarkę, aby wyświetlić hostowaną aplikację, ale w tym momencie aplikacja nie działa poprawnie na platformie Azure. Nadal musisz skonfigurować bezpieczne połączenie między usługą App Service i bazą danych SQL, aby pobrać dane.

Połączenie usługi App Service do usługi Azure SQL Database

Bez hasła (zalecane)

Aby utworzyć połączenie bez hasła między wystąpieniem usługi App Service i usługą Azure SQL Database, wymagane są następujące kroki:

1. Utwórz tożsamość zarządzaną dla usługi App Service. Biblioteka zawarta Microsoft.Data.SqlClient w aplikacji automatycznie odnajdzie tożsamość zarządzaną, podobnie jak w przypadku odnajdywania lokalnego użytkownika programu Visual Studio.
2. Utwórz użytkownika bazy danych SQL i skojarz ją z tożsamością zarządzaną usługi App Service.
3. Przypisz role SQL do użytkownika bazy danych, który zezwala na odczyt, zapis i potencjalnie inne uprawnienia.

Dostępnych jest wiele narzędzi do implementowania następujących kroków:

Połączenie or usługi (zalecane)

Usługa Połączenie or to narzędzie, które usprawnia uwierzytelnianie połączeń między różnymi usługami na platformie Azure. Usługa Połączenie or obsługuje obecnie łączenie usługi App Service z bazą danych SQL za pośrednictwem interfejsu az webapp connection create sql wiersza polecenia platformy Azure przy użyciu polecenia . To pojedyncze polecenie wykonuje trzy kroki wymienione powyżej.

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

Zmiany wprowadzone przez usługę Service Połączenie or można sprawdzić w ustawieniach usługi App Service.

1. Przejdź do strony Tożsamość dla usługi App Service. Na karcie Przypisane przez system stan powinien być ustawiony na Włączone. Ta wartość oznacza, że tożsamość zarządzana przypisana przez system została włączona dla aplikacji.

2. Przejdź do strony Konfiguracja usługi App Service. Na karcie Ciągi Połączenie ion powinny zostać wyświetlone parametry połączenia o nazwie AZURE_SQL_CONNECTIONSTRING. Wybierz pozycję Kliknij, aby wyświetlić tekst wartości, aby wyświetlić wygenerowany parametry połączenia bez hasła. Nazwa tej parametry połączenia jest zgodna z nazwą skonfigurowaną w aplikacji, więc zostanie ona odnaleziona automatycznie podczas uruchamiania na platformie Azure.

Witryna Azure Portal

Witryna Azure Portal umożliwia pracę z tożsamościami zarządzanymi i uruchamianie zapytań względem usługi Azure SQL Database. Wykonaj następujące kroki, aby utworzyć połączenie bez hasła z wystąpienia usługi App Service do usługi Azure SQL Database:

Tworzenie tożsamości zarządzanej

1. W witrynie Azure Portal przejdź do usługi App Service i wybierz pozycję Tożsamość w obszarze nawigacji po lewej stronie.

2. Na karcie Przypisano system na stronie Tożsamość upewnij się, że przełącznik Stan jest ustawiony na włączone. Po włączeniu tego ustawienia zostanie utworzona tożsamość zarządzana przypisana przez system o takiej samej nazwie jak usługa App Service. Tożsamości przypisane przez system są powiązane z wystąpieniem usługi i są niszczone z aplikacją po jej usunięciu.

Tworzenie użytkownika bazy danych i przypisywanie ról

1. W witrynie Azure Portal przejdź do bazy danych SQL i wybierz pozycję Edytor zapytań (wersja zapoznawcza).

2. Wybierz pozycję Kontynuuj po <your-username> prawej stronie ekranu, aby zalogować się do bazy danych przy użyciu konta.

3. W widoku edytora zapytań uruchom następujące polecenia języka T-SQL:

   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
   

   

   Ten skrypt SQL tworzy użytkownika bazy danych SQL, który mapuje z powrotem na tożsamość zarządzaną wystąpienia usługi App Service. Przypisuje również użytkownikowi niezbędne role SQL, aby umożliwić aplikacji odczytywanie, zapisywanie i modyfikowanie danych i schematu bazy danych. Po zakończeniu tego kroku usługi są połączone.

Ważne

Chociaż to rozwiązanie zapewnia proste podejście do rozpoczęcia pracy, nie jest to najlepsze rozwiązanie dla środowisk klasy produkcyjnej. W tych scenariuszach aplikacja nie powinna wykonywać wszystkich operacji przy użyciu jednej tożsamości z podwyższonym poziomem uprawnień. Należy spróbować zaimplementować zasadę najniższych uprawnień, konfigurując wiele tożsamości z określonymi uprawnieniami dla określonych zadań.

Więcej informacji na temat konfigurowania ról bazy danych i zabezpieczeń można uzyskać w następujących zasobach:

• Samouczek: zabezpieczanie bazy danych w usłudze Azure SQL Database
• Autoryzowanie dostępu do bazy danych w usłudze SQL Database

Uwierzytelnianie SQL

Aby połączyć usługę App Service z usługą Azure SQL Database przy użyciu uwierzytelniania SQL, nie są wymagane żadne dodatkowe kroki. Parametry połączenia skonfigurowany w appsettings.json pliku zawiera niezbędne poświadczenia do uwierzytelnienia.

Ostrzeżenie

Należy zachować ostrożność podczas zarządzania parametry połączenia, które zawierają wpisy tajne, takie jak nazwy użytkowników, hasła lub klucze dostępu. Te wpisy tajne nie powinny być zatwierdzane w kontroli źródła ani umieszczane w niezabezpieczonych lokalizacjach, w których mogą uzyskiwać do nich dostęp niezamierzeni użytkownicy. W przypadku rzeczywistej aplikacji w środowisku platformy Azure klasy produkcyjnej można przechowywać parametry połączenia w bezpiecznej lokalizacji, takiej jak ustawienia konfiguracji usługi App Service lub usługa Azure Key Vault. Podczas programowania lokalnego zazwyczaj łączysz się z lokalną bazą danych, która nie wymaga przechowywania wpisów tajnych ani bezpośredniego łączenia się z platformą Azure.

Testowanie wdrożonej aplikacji

1. Wybierz przycisk Przeglądaj w górnej części strony przeglądu usługi App Service, aby uruchomić główny adres URL aplikacji.

2. Dołącz ścieżkę /swagger/index.html do adresu URL, aby załadować tę samą stronę testu struktury Swagger, która była używana lokalnie.

3. Wykonaj testowanie żądań GET i POST, aby sprawdzić, czy punkty końcowe działają zgodnie z oczekiwaniami.

Napiwek

Jeśli podczas testowania wystąpi błąd 500 Wewnętrzny serwer, może to być spowodowane konfiguracjami sieci bazy danych. Sprawdź, czy serwer logiczny jest skonfigurowany z ustawieniami opisanymi w sekcji Konfigurowanie bazy danych .

Gratulacje! Aplikacja jest teraz połączona z usługą Azure SQL Database zarówno w środowiskach lokalnych, jak i hostowanych.

Oczyszczanie zasobów

Po zakończeniu pracy z usługą Azure SQL Database usuń zasób, aby uniknąć niezamierzonych kosztów.

Witryna Azure Portal

1. Na pasku wyszukiwania w witrynie Azure Portal wyszukaj ciąg Azure SQL i wybierz pasujący wynik.

2. Znajdź i wybierz bazę danych na liście baz danych.

3. Na stronie Przegląd usługi Azure SQL Database wybierz pozycję Usuń.

4. Na platformie Azure na pewno chcesz usunąć otwieraną stronę, wpisz nazwę bazy danych, aby potwierdzić, a następnie wybierz pozycję Usuń.

Interfejs wiersza polecenia platformy Azure

Usuń bazę danych przy użyciu az sql db delete polecenia . Zastąp parametry symbolu zastępczego własnymi wartościami.

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