Herstellen einer Verbindung mit Azure SQL Datenbank und Abfragen mithilfe von .NET und Entity Framework Core

Gilt für: Azure SQL-Datenbank

In dieser Schnellstartanleitung wird beschrieben, wie Sie eine Anwendung mit einer Datenbank in Azure SQL-Datenbank verbinden und Abfragen mithilfe von .NET und Entity Framework Core 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 des Datenbankservers

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

Mit den Schritten in diesem Abschnitt wird über die .NET-CLI oder in Visual Studio 2022 eine .NET-Minimal-Web-API erstellt.

  1. Navigieren Sie auf der Visual Studio-Menüleiste 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 von Entity Framework Core zum Projekt

Um über .NET und Entity Framework Core eine Verbindung mit Azure SQL Datenbank herzustellen, müssen Sie Ihrem Projekt mithilfe einer der folgenden Methoden drei NuGet-Pakete hinzufügen:

  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 diesem Fenster nach EntityFrameworkCore. Suchen und installieren Sie die folgenden Pakete:

  • Microsoft.EntityFrameworkCore: Stellt wesentliche Entity Framework Core-Funktionen bereit.
  • Microsoft.EntityFrameworkCore.SqlServer: Stellt zusätzliche Komponenten zum Herstellen einer Verbindung mit dem logischen Server bereit
  • Microsoft.EntityFrameworkCore.Design: Stellt Unterstützung für laufende Entity Framework-Migrationen bereit.

Alternativ dazu können Sie auch das Cmdlet Install-Package im Fenster Paket-Manager-Konsole ausführen:

Install-Package Microsoft.EntityFrameworkCore
Install-Package Microsoft.EntityFrameworkCore.SqlServer
Install-Package Microsoft.EntityFrameworkCore.Design

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

Die Entity Framework Core-Bibliotheken nutzen die Bibliotheken Microsoft.Data.SqlClient und Azure.Identity, um kennwortlose Verbindungen mit Azure SQL Datenbank zu implementieren. Die Bibliothek Azure.Identity stellt eine Klasse namens DefaultAzureCredential bereit, die die kennwortlose Authentifizierung bei Azure verarbeitet.

DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche zur Runtime verwendet wird. Bei diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal gegenüber Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren. Die Reihenfolge und Speicherorte, in denen DefaultAzureCredential nach Anmeldeinformationen sucht, finden Sie in der Übersicht über die Azure Identity-Bibliothek.

Führen Sie die folgenden Schritte aus, um mithilfe von Entity Framework Core und der zugrunde liegenden Klasse DefaultAzureCredential eine Verbindung mit Azure SQL Datenbank herzustellen:

  1. Fügen Sie der appsettings.Development.json Datei einen ConnectionStrings-Abschnitt entsprechend dem folgenden Code hinzu. Achten Sie darauf, die Platzhalter <your database-server-name> und <your-database-name> zu aktualisieren.

    Die kennwortlose Verbindungszeichenfolge enthält den Konfigurationswert Authentication=Active Directory Default, der es Entity Framework Core ermöglicht, DefaultAzureCredential zum Herstellen einer Verbindung mit Azure-Diensten zu verwenden. Wenn die App lokal ausgeführt wird, authentifiziert sie sich mit dem Benutzer, als der Sie bei Visual Studio angemeldet sind. 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.

    Hinweis

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

    {
        "Logging": {
            "LogLevel": {
                "Default": "Information",
                "Microsoft.AspNetCore": "Warning"
            }
        },
        "ConnectionStrings": {
            "AZURE_SQL_CONNECTIONSTRING": "Data Source=passwordlessdbserver.database.windows.net;
                Initial Catalog=passwordlessdb; Authentication=Active Directory Default; Encrypt=True;"
        }
    }
    
  2. Fügen Sie der Datei Program.cs oberhalb der Codezeile var app = builder.Build(); den folgenden Code hinzu. Dieser Code führt folgende Konfigurationen aus:

    • Ruft die kennwortlose Datenbank-Verbindungszeichenfolge für die lokale Entwicklung aus der Datei appsettings.Development.json oder in gehosteten Produktionsszenarien aus den Umgebungsvariablen ab.

    • Registriert die Entity Framework Core-Klasse DbContext beim .NET-Container für die Abhängigkeitsinjektion.

      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));
      
  3. Fügen Sie am Ende der Datei Program.cs oberhalb von app.Run() die folgenden Endpunkte hinzu, um Entitäten in der Datenbank mithilfe der PersonDbContext-Klasse abzurufen und hinzuzufügen.

    app.MapGet("/Person", (PersonDbContext context) =>
    {
        return context.Person.ToList();
    })
    .WithName("GetPersons")
    .WithOpenApi();
    
    app.MapPost("/Person", (Person person, PersonDbContext context) =>
    {
        context.Add(person);
        context.SaveChanges();
    })
    .WithName("CreatePerson")
    .WithOpenApi();
    

    Zum Schluss fügen Sie die Klassen Person und PersonDbContext am Ende der Datei Program.cs hinzu. Die Person-Klasse repräsentiert einen einzelnen Datensatz in der Persons-Tabelle der Datenbank. Die PersonDbContext-Klasse repräsentiert die Person-Datenbank und ermöglicht Ihnen, mithilfe von Code Vorgänge in der Datenbank auszuführen. Weitere Informationen zu DbContext finden Sie in der Dokumentation Erste Schritte für Entity Framework Core.

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

Ausführen der Migrationen zum Erstellen der Datenbank

Um das Datenbankschema so zu aktualisieren, dass es Ihrem Datenmodell mit Entity Framework Core entspricht, müssen Sie eine Migration verwenden. Migrationen können ein Datenbankschema erstellen und inkrementell aktualisieren, um es mit dem Datenmodell Ihrer Anwendung zu synchronisieren. Mehr über dieses Muster erfahren Sie in der Migrationsübersicht.

  1. Öffnen Sie ein Terminalfenster im Stamm Ihres Projekts.

  2. Führen Sie den folgenden Befehl aus, um eine Erstmigration zu generieren, mit der die Datenbank erstellt werden kann:

    Add-Migration InitialCreate
    
  3. In Ihrem Projektverzeichnis sollte der Ordner Migrations angezeigt werden, zusammen mit einer Datei mit dem Namen InitialCreate, dem eindeutige Ziffern vorangestellt sind. Führen Sie mit dem folgenden Befehl die Migration aus, um die Datenbank zu erstellen:

    Update-Database
    

    Die Entity Framework Core-Tools erstellen das Datenbankschema in Azure, das von der Klasse PersonDbContext definiert wird.

Lokales 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 Vor- und Nachnamen 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 grüne +-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, und wählen Sie dann Fertig stellen aus.

  8. 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 die App Service- mit der Azure SQL-Datenbank-Instanz zu verbinden:

  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 <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

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 automatisch ermittelt wird, wenn sie in Azure ausgeführt wird.

Wichtig

Obwohl diese Lösung einen einfachen Ansatz für die ersten Schritte bietet, ist sie keine bewährte Methode für Unternehmensproduktionsumgebungen. 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:

Tutorial: Schützen einer Datenbank in Azure SQL-Datenbank

Autorisieren des Datenbankzugriffs für SQL-Datenbank

Testen der bereitgestellten Anwendung

Navigieren Sie zur URL der App, um zu testen, ob die Verbindung mit Azure SQL-Datenbank funktioniert. Sie finden die URL Ihrer App auf der App Service-Übersichtsseite. Fügen Sie den /person-Pfad dem Ende der URL an, um zu dem Endpunkt zu navigieren, den Sie lokal getestet haben.

Die Person, die Sie lokal erstellt haben, sollte im Browser angezeigt werden. Glückwunsch! 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.