Freigeben über

Herstellen einer Verbindung mit einer Instanz von Azure SQL-Datenbank mithilfe von .NET und der Microsoft.Data.SqlClient-Bibliothek und deren Abfrage

  • Artikel

Gilt für: Azure SQL-Datenbank

In diesem Schnellstart wird beschrieben, wie Sie eine Verbindung einer Anwendung mit einer Datenbank in Azure SQL-Datenbank herstellen und Abfragen mithilfe von .NET und der Bibliothek Microsoft.Data.SqlClient ausführen. In dieser Schnellstartanleitung wird der empfohlene kennwortlose Ansatz zum Herstellen einer Verbindung mit der Datenbank verwendet. Sie können mehr über kennwortlose Verbindungen auf dem kennwortlosen Hub erfahren.

Voraussetzungen

Konfigurieren der Datenbank

Sichere, kennwortlose Verbindungen mit Azure SQL-Datenbank erfordern bestimmte Datenbankkonfigurationen. Überprüfen Sie die folgenden Einstellungen auf Ihrem logischen Server in Azure, um eine ordnungsgemäße Verbindung mit Azure SQL-Datenbank in lokalen und gehosteten Umgebungen herzustellen:

  1. Stellen Sie für Verbindungen bei der lokalen Entwicklung sicher, dass Ihr logischer Server so konfiguriert ist, dass die IP-Adresse Ihres lokalen Computers und andere Azure-Dienste eine Verbindung herstellen können:

    • Wechseln Sie zur Seite Netzwerk für Ihren Server.

    • Verwenden Sie das Optionsfeld Ausgewählte Netzwerke, um zusätzliche Konfigurationsoptionen anzuzeigen.

    • Wählen Sie Client-IPv4-Adresse (xx.xx.xx.xx) hinzufügen aus, um eine Firewallregel hinzuzufügen, die Verbindungen von der IPv4-Adresse Ihres lokalen Computers ermöglicht. Alternativ können Sie auch + Firewallregel hinzufügen auswählen, um eine bestimmte IP-Adresse Ihrer Wahl einzugeben.

    • Vergewissern Sie sich, dass das Kontrollkästchen Azure-Diensten und -Ressourcen den Zugriff auf diesen Server gestatten aktiviert ist.

      Screenshot: Konfigurieren von Firewallregeln

      Warnung

      Das Aktivieren der Einstellung Azure-Diensten und -Ressourcen den Zugriff auf diesen Server gestatten ist kein empfohlenes Sicherheitsverfahren für Produktionsszenarien. Echte Anwendungen sollten sicherere Ansätze implementieren, z. B. stärkere Firewalleinschränkungen oder Konfigurationen mit virtuellen Netzwerken.

      Weitere Informationen zum Konfigurieren der Datenbanksicherheit finden Sie in den folgenden Ressourcen:

  2. Der Server muss auch die Microsoft Entra-Authentifizierung aktiviert haben und ein Microsoft Entra-Administratorkonto zugewiesen haben. Bei lokalen Entwicklungsverbindungen sollte das Microsoft Entra-Administratorkonto ein Konto sein, mit dem Sie sich auch lokal bei Visual Studio oder der Azure CLI anmelden können. Sie können überprüfen, ob der Server die Microsoft Entra-Authentifizierung auf der Microsoft Entra-ID-Seite Ihres logischen Servers aktiviert hat.

    Ein Screenshot, der das Aktivieren der Microsoft Entra-Authentifizierung anzeigt.

  3. Wenn Sie ein persönliches Azure-Konto verwenden, stellen Sie sicher, dass Sie Microsoft Entra für Azure SQL Database eingerichtet und konfiguriert haben, um Ihr Konto als Server-Admin zuzuweisen. Wenn Sie ein Unternehmenskonto verwenden, ist die Microsoft Entra ID höchstwahrscheinlich bereits für Sie konfiguriert.

Erstellen des Projekts

Für die folgenden Schritte müssen Sie eine .NET Minimal-Web-API mithilfe der .NET CLI oder mit Visual Studio 2022 erstellen.

  1. Navigieren Sie im Visual Studio-Menü zu Datei>Neu>Projekt.

  2. Geben Sie im Dialogfeld ASP.NET in das Suchfeld der Projektvorlage ein, und wählen Sie das Ergebnis „ASP.NET Core-Web-API“ aus. Wählen Sie unten im Dialogfeld Weiter aus.

  3. Geben Sie als ProjektnamenDotNetSQL ein. Übernehmen Sie bei den restlichen Feldern die Standardwerte, und wählen Sie Weiter aus.

  4. Wählen Sie für das Framework „.NET 7.0“ aus, und deaktivieren Sie Controller verwenden (deaktivieren, um minimale APIs zu verwenden). In dieser Schnellstartanleitung wird eine Minimal-API-Vorlage verwendet, um die Erstellung und Konfiguration von Endpunkten zu optimieren.

  5. Wählen Sie Erstellen. Das neue Projekt wird in der Visual Studio-Umgebung geöffnet.

Hinzufügen der Bibliothek „Microsoft.Data.SqlClient“

Um Verbindungen mit Azure SQL-Datenbank mithilfe von .NET herzustellen, installieren Sie Microsoft.Data.SqlClient. Dieses Paket fungiert als Datenanbieter für das Herstellen einer Verbindung mit Datenbanken, Ausführen von Befehlen und Abrufen von Ergebnissen.

Hinweis

Stellen Sie sicher, dass Sie Microsoft.Data.SqlClient und nicht System.Data.SqlClient installieren. Microsoft.Data.SqlClient ist eine neuere Version der SQL-Clientbibliothek, die zusätzliche Funktionen bietet.

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Abhängigkeiten, und wählen Sie NuGet-Pakete verwalten aus.

  2. Suchen Sie im daraufhin angezeigten Fenster nach SqlClient. Suchen Sie das Microsoft.Data.SqlClient-Ergebnis, und wählen Sie Installieren aus.

Konfigurieren der Verbindungszeichenfolge

Für die lokale Entwicklung mit kennwortlosen Verbindungen mit Azure SQL-Datenbank fügen Sie in der Datei appsettings.json den folgenden Abschnitt ConnectionStrings hinzu. Ersetzen Sie die Platzhalter <database-server-name> und <database-name> durch Ihre eigenen Werte.

"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\";"
}

Die Verbindungszeichenfolge für kennwortlose Verbindungen legt als Konfigurationswert Authentication="Active Directory Default" fest, mit dem die Microsoft.Data.SqlClient-Bibliothek angewiesen wird, mithilfe einer Klasse namens DefaultAzureCredential eine Verbindung mit Azure SQL-Datenbank herzustellen. DefaultAzureCredential ermöglicht kennwortlose Verbindungen mit Azure-Diensten und wird von der Azure Identity-Bibliothek bereitgestellt, von der die SQL-Clientbibliothek abhängt. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche zur Laufzeit in den unterschiedlichen Umgebungen verwendet wird.

Wenn die App beispielsweise lokal ausgeführt wird, authentifiziert sich DefaultAzureCredential über die Benutzer*innen, mit denen die Anmeldung bei Visual Studio erfolgt ist, oder über andere lokale Tools wie die Azure-Befehlszeilenschnittstelle. Sobald die App in Azure bereitgestellt wird, ermittelt derselbe Code die verwaltete Identität, die der gehosteten App zugeordnet ist, die Sie später konfigurieren werden, und wendet sie an. Die Reihenfolge und Speicherorte, in denen DefaultAzureCredential nach Anmeldeinformationen sucht, finden Sie in der Übersicht über die Azure Identity-Bibliothek.

Hinweis

Verbindungszeichenfolgen für kennwortlose Verbindungen können sicher in die Quellcodeverwaltung committet werden, da sie keine Geheimnisse wie Benutzernamen, Kennwörter oder Zugriffsschlüssel enthalten.

Hinzufügen des Codes zum Herstellen einer Verbindung mit Azure SQL-Datenbank

Ersetzen Sie den Inhalt der Datei Program.cs durch folgenden Code, der die folgenden wichtigen Schritte ausführt:

  • Abrufen der Verbindungszeichenfolge für kennwortlose Verbindungen aus der Datei appsettings.json
  • Erstellt während des Startvorgangs eine Persons-Tabelle in der Datenbank (nur für Testszenarien).
  • Erstellt einen HTTP GET-Endpunkt, um alle in der Tabelle Persons gespeicherten Datensätze abzurufen
  • Erstellt einen HTTP POST-Endpunkt, um der Tabelle Persons neue Datensätze hinzuzufügen
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();

Fügen Sie schließlich die Person-Klasse unten in der Datei Program.cshinzu. Diese Klasse stellt einen einzelnen Datensatz in der Persons-Tabelle der Datenbank dar.

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

Lokales Ausführen und Testen der App

Die App kann lokal getestet werden. Stellen Sie sicher, dass Sie bei Visual Studio oder der Azure CLI mit demselben Konto angemeldet sind, das Sie als Administrator für Ihre Datenbank festgelegt haben.

  1. Klicken Sie oben in Visual Studio auf die Schaltfläche „Ausführen“, um das API-Projekt zu starten.

  2. Erweitern Sie auf der Swagger-UI-Seite die POST-Methode, und wählen Sie Ausprobieren aus.

  3. Ändern Sie den JSON-Beispielcode, um Werte für den first und last-Namen einzuschließen. Wählen Sie Ausführen aus, um der Datenbank einen neuen Datensatz hinzuzufügen. Die API gibt eine Erfolgsmeldung zurück.

    Screenshot, der zeigt, wie man die API testet.

  4. Erweitern Sie auf der Swagger-UI-Seite die GET-Methode, und wählen Sie Ausprobieren aus. Wählen Sie Ausführen aus, und die soeben erstellte Person wird zurückgegeben.

Bereitstellung in Azure App Service

Die App kann jetzt in Azure bereitgestellt werden. Visual Studio kann eine Azure App Service-Instanz erstellen und Ihre Anwendung in einem einzigen Workflow bereitstellen.

  1. Stellen Sie sicher, dass die App beendet und erfolgreich erstellt ist.

  2. Klicke Sie im Projektmappen-Explorer-Fenster von Visual Studio mit der rechten Maustaste auf den Projektknoten der obersten Ebene, und wählen Sie Veröffentlichen aus.

  3. Wählen Sie im Veröffentlichungsdialogfeld Azure als Bereitstellungsziel und dann Weiter aus.

  4. Wählen Sie als bestimmtes Ziel Azure App Service (Windows) und dann Weiter aus.

  5. Wählen Sie das +-Symbol aus, um eine neue App Service-Instanz zur Bereitstellung zu erstellen, und geben Sie die folgenden Werte ein:

    • Name: Behalten Sie den Standardwert bei.

    • Abonnementname: Wählen Sie das Abonnement aus, in das die Bereitstellung erfolgen soll.

    • Ressourcengruppe: Wählen Sie Neu aus, und erstellen Sie eine neue Ressourcengruppe mit dem Namen msdocs-dotnet-sql.

    • Hostingplan: Wählen Sie Neu aus, um das Dialogfeld „Hostingplan“ zu öffnen. Behalten Sie die Standardwerte bei, und wählen Sie OK aus.

    • Wählen Sie Erstellen aus, um das ursprüngliche Dialogfeld zu schließen. Visual Studio erstellt die App Service-Ressource in Azure.

      Screenshot zeigt, wie die Bereitstellung mit Visual Studio erfolgt.

  6. Sobald die Ressource erstellt ist, stellen Sie sicher, dass sie in der Liste der App-Dienste ausgewählt ist, und wählen Sie dann Weiter aus.

  7. Aktivieren Sie im Schritt API Management unten das Kontrollkästchen Diesen Schritt überspringen aus, und wählen Sie dann Fertig stellen aus.

  8. Wählen Sie im Schritt „Fertig stellen“ die Option Schließen aus, wenn das Dialogfeld nicht automatisch geschlossen wird.

  9. Wählen Sie oben rechts in der Zusammenfassung des Veröffentlichungsprofils Veröffentlichen aus, um die App in Azure bereitzustellen.

Wenn die Bereitstellung abgeschlossen ist, startet Visual Studio den Browser, um die gehostete App anzuzeigen, aber an diesem Punkt funktioniert die App nicht ordnungsgemäß in Azure. Sie müssen weiterhin die sichere Verbindung zwischen der App Service- und der SQL-Datenbank-Instanz konfigurieren, um Ihre Daten abzurufen.

Verbinden der App Service-Instanz mit Azure SQL-Datenbank

Die folgenden Schritte sind erforderlich, um eine kennwortlose Verbindung zwischen der App Service-Instanz und Azure SQL-Datenbank herzustellen:

  1. Erstellen Sie eine verwaltete Identität für die App Service-Instanz. Die in Ihrer App enthaltene Microsoft.Data.SqlClient-Bibliothek ermittelt automatisch die verwaltete Identität, so wie sie Ihren lokalen Visual Studio-Benutzer ermittelt hat.
  2. Erstellen Sie einen SQL-Datenbankbenutzer, und ordnen Sie ihn der verwalteten App Service-Identität zu.
  3. Weisen Sie dem Datenbankbenutzer SQL-Rollen zu, die über Lese-, Schreib- und möglicherweise andere Berechtigungen verfügen.

Es stehen mehrere Tools zur Implementierung dieser Schritte zur Verfügung:

Der Dienstconnector ist ein Tool, das authentifizierte Verbindungen zwischen verschiedenen Diensten in Azure optimiert. Der Dienstconnector unterstützt derzeit das Verbinden einer App Service- mit einer SQL-Datenbank-Instanz über die Azure CLI mithilfe des az webapp connection create sql-Befehls. Dieser einzelne Befehl führt die drei oben genannten Schritte für Sie aus.

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

Sie können die vom Dienstconnector vorgenommenen Änderungen in den App Service-Einstellungen überprüfen.

  1. Navigieren Sie zur Seite Identität für Ihre App Service-Instanz. Auf der Registerkarte Systemseitig zugewiesen sollte der Status auf Ein festgelegt werden. Dieser Wert bedeutet, dass eine systemseitig zugewiesene verwaltete Identität für Ihre App aktiviert wurde.

  2. Navigieren Sie zur Seite Konfiguration für Ihre App Service-Ressource. Auf der Registerkarte Verbindungszeichenfolgen sollte eine Verbindungszeichenfolge namens AZURE_SQL_CONNECTIONSTRING angezeigt werden. Wählen Sie Klicken Sie, um den Wert anzuzeigen aus, um die generierte kennwortlose Verbindungszeichenfolge anzuzeigen. Der Name dieser Verbindungszeichenfolge entspricht dem, den Sie in Ihrer App konfiguriert haben, sodass sie bei der Ausführung in Azure automatisch ermittelt wird.

Wichtig

Obwohl diese Lösung einen einfachen Ansatz für die ersten Schritte bietet, stellt sie keine bewährte Methode für Produktionsumgebungen dar. In diesen Szenarien sollte die App nicht alle Vorgänge mit einer einzelnen Identität mit erhöhten Rechten ausführen. Sie sollten versuchen, das Prinzip der geringsten Rechte zu implementieren, indem Sie mehrere Identitäten mit bestimmten Berechtigungen für bestimmte Aufgaben konfigurieren.

Weitere Informationen zum Konfigurieren von Datenbankrollen und der Sicherheit finden Sie in den folgenden Ressourcen:

Testen der bereitgestellten Anwendung

  1. Wählen Sie oben auf Übersichtsseite App Service die Schaltfläche Durchsuchen aus, um die Stamm-URL Ihrer App aufzurufen.

  2. Fügen Sie den Pfad der Datei /swagger/index.html an die URL an, um dieselbe Swagger-Testseite zu laden, die Sie lokal verwendet haben.

  3. Führen Sie GET- und POST-Testanforderungen aus, um zu überprüfen, ob die Endpunkte wie erwartet funktionieren.

Tipp

Wenn beim Testen ein Fehler 500 (internal Serverfehler) angezeigt wird, kann dies auf die Netzwerkkonfiguration Ihrer Datenbank zurückzuführen sein. Vergewissern Sie sich, dass Ihr logischer Server mit den Einstellungen konfiguriert ist, die im Abschnitt Konfigurieren der Datenbank beschrieben sind.

Ihre Anwendung ist jetzt in lokalen und gehosteten Umgebungen mit Azure SQL-Datenbank verbunden.

Bereinigen der Ressourcen

Wenn Sie Ihre Arbeit mit der Azure SQL-Datenbank abgeschlossen haben, löschen Sie die Ressource, um unbeabsichtigte Gebühren zu vermeiden.

  1. Geben Sie in der Suchleiste des Azure-Portals Azure SQL ein, und wählen Sie das entsprechende Ergebnis aus.

  2. Suchen Sie Ihre Datenbank in der Liste der Datenbanken, und wählen Sie sie aus.

  3. Wählen Sie auf der Seite Übersicht Ihrer Azure SQL-Datenbank die Option Löschen aus.

  4. Geben Sie auf der daraufhin geöffneten Azure-Seite Möchten Sie ... löschen zur Bestätigung den Namen Ihrer Datenbank ein, und wählen Sie dann Löschen aus.

Zugehöriger Inhalt