Schnellstart: Erstellen einer App für dauerhafte Funktionen, die den MSSQL-Speicheranbieter verwendet

Verwenden Sie Durable Functions, ein Feature von Azure Functions, um zustandsbehaftete Funktionen in einer serverlosen Umgebung zu schreiben. Durable Functions verwaltet Zustand, Prüfpunkte und Neustarts in Ihrer Anwendung.

Durable Functions unterstützt mehrere Speicheranbieter, auch als Backend-Systeme bezeichnet, um den Orchestrierungs- und Entitätslaufzeitzustand zu speichern. In dieser Schnellstartanleitung erstellen Sie eine App für dauerhafte Funktionen, um den Microsoft SQL Server (MSSQL)-Speicheranbieter mit Visual Studio Code zu verwenden.

Diese Schnellstartanleitung erstellt eine .NET-App (isoliertes Modell) zu Demonstrationszwecken. Inhalte in diesem Artikel gelten auf ähnliche Weise für andere Sprachen.

Hinweis

• Das MSSQL-Back-End wurde entwickelt, um die Anwendungsportabilität und Kontrolle über Ihre Daten zu maximieren. Es verwendet Microsoft SQL Server, um alle Task Hub-Daten beizubehalten, sodass Benutzer die Vorteile einer modernen Datenbankverwaltungsinfrastruktur (DBMS) auf Unternehmensniveau erhalten. Weitere Informationen zur Verwendung des MSSQL-Speicheranbieters finden Sie in der Übersicht zu Speicheranbietern.

• Das Migrieren von Task Hub-Daten über Speicheranbieter wird derzeit nicht unterstützt. Funktions-Apps mit vorhandenen Laufzeitdaten beginnen mit einem frischen, leeren Aufgabenhub, nachdem sie zum MSSQL-Back-End gewechselt sind. Ebenso können die mithilfe von MSSQL erstellten Aufgabenhubinhalte nicht beibehalten werden, wenn Sie zu einem anderen Speicheranbieter wechseln.

Voraussetzungen

Für die Durchführung dieses Schnellstarts benötigen Sie Folgendes:

• Installation von Visual Studio Code.

• Die Visual Studio Code-Erweiterung von Azure Functions wurde installiert.

• Installation der aktuellen Version der Azure Functions Core Tools

• .NET 8.0 SDK installiert.

• Docker ist installiert.

• Ein Azure-Abonnement.

• Ein HTTP-Testtool, das Ihre Daten schützt. Weitere Informationen finden Sie unter HTTP-Testtools.

Erstellen eines Azure Functions-Projekts

Erstellen Sie in Visual Studio Code ein lokales Azure Functions-Projekt.

1. Wählen Sie im Menü AnsichtBefehlspalette aus, oder drücken Sie STRG+UMSCHALT+P.

2. Geben Sie in der Eingabeaufforderung (>) Azure Functions: Neues Projekt erstellen ein, und wählen Sie diese Option aus.

   

3. Wählen Sie Durchsuchen aus. Wechseln Sie im Dialogfeld Ordner auswählen zu einem Ordner, der für Ihr Projekt verwendet werden soll, und wählen Sie dann Auswählen aus.

4. Wählen Sie die folgenden Werte aus, bzw. geben Sie sie ein, wenn Sie dazu aufgefordert werden:

   Prompt	Maßnahme	BESCHREIBUNG
   Sprache des Funktions-App-Projekts auswählen	Wählen Sie .NET aus.	Erstellt ein lokales C#-Funktionen-Projekt
   Auswählen einer .NET-Laufzeit	Wählen Sie .NET 8.0 isoliert aus.	Erstellt ein Functions-Projekt, das .NET 8 unterstützt und in einem isolierten Workerprozess und mit Azure Functions Runtime 4.0 ausgeführt wird.
   Auswählen einer Vorlage für die erste Funktion Ihres Projekts	Wählen Sie Orchestrierung für Durable Functions aus.	Erstellen Sie eine Orchestrierung für Durable Functions.
   Dauerhaften Speichertyp auswählen	Wählen Sie MSSQL aus.	Wählt den MSSQL-Speicheranbieter aus.
   Angeben eines Funktionsnamens	Geben Sie HelloOrchestration ein.	Ein Name für die Orchestrierungsfunktion
   Bereitstellen eines Namespaces	Geben Sie Company.Function ein.	Ein Namespace für die generierte Klasse
   Auswählen, wie Sie Ihr Projekt öffnen möchten	Wählen Sie In aktuellem Fenster öffnen aus.	Öffnet Visual Studio Code im ausgewählten Ordner

Visual Studio Code installiert Azure Functions Core Tools, wenn es zum Erstellen des Projekts erforderlich ist. Außerdem wird ein Funktions-App-Projekt in einem Ordner erstellt. Dieses Projekt enthält die Konfigurationsdateien host.json und local.settings.json.

Eine weitere Datei, HelloOrchestration.cs, enthält die grundlegenden Bausteine einer Durable Functions-App:

Methode	BESCHREIBUNG
HelloOrchestration	Definiert die App-Orchestrierung für Durable Functions. In diesem Fall wird die Orchestrierung gestartet, es wird eine Liste erstellt, und das Ergebnis der drei Funktionsaufrufe wird dann der Liste hinzugefügt. Wenn die drei Funktionsaufrufe abgeschlossen sind, wird die Liste zurückgegeben.
SayHello	Eine einfache Funktions-App, die hello zurückgibt. Diese Funktion enthält die Geschäftslogik, die orchestriert wird.
HelloOrchestration_HttpStart	Eine per HTTP ausgelöste Funktion, mit der eine Instanz der Orchestrierung gestartet und eine Antwort zur Überprüfung des Status zurückgegeben wird.

Weitere Informationen zu diesen Funktionen finden Sie unter Typen und Features für Durable Functions.

Einrichten Ihrer Datenbank

Hinweis

Wenn Sie bereits über eine MSSQL-kompatible Datenbank verfügen, können Sie diesen Abschnitt und den nächsten Abschnitt zum Einrichten einer Docker-basierten lokalen Datenbank überspringen.

Da das MSSQL-Back-End auf Portabilität ausgelegt ist, haben Sie mehrere Optionen zum Einrichten Der Sicherungsdatenbank. Beispielsweise können Sie eine lokale SQL Server-Instanz einrichten, eine vollständig verwaltete Instanz der Azure SQL-Datenbank verwenden oder eine andere mit SQL Server kompatible Hostingoption verwenden.

Sie können auch die lokale Offlineentwicklung mit SQL Server Express auf Ihrem lokalen Windows-Computer durchführen oder ein SQL Server-Docker-Image verwenden, das in einem Docker-Container ausgeführt wird.

Diese Schnellstartanleitung konzentriert sich auf die Verwendung eines SQL Server Docker-Images.

Einrichten Ihrer lokalen Docker-basierten SQL Server-Instanz

Verwenden Sie die folgenden PowerShell-Befehle, um eine lokale SQL Server-Datenbank in Docker einzurichten. Sie können PowerShell unter Windows, macOS oder Linuxinstallieren.

# primary parameters
$pw        = "yourStrong(!)Password"
$edition   = "Developer"
$port      = 1433
$tag       = "2019-latest"
$dbname    = "DurableDB"
$collation = "Latin1_General_100_BIN2_UTF8"

# pull the image from the Microsoft container registry
docker pull mcr.microsoft.com/mssql/server:$tag

# run the image and provide some basic setup parameters
docker run --name mssql-server -e 'ACCEPT_EULA=Y' -e "MSSQL_SA_PASSWORD=$pw" -e "MSSQL_PID=$edition" -p ${port}:1433 -d mcr.microsoft.com/mssql/server:$tag

# wait a few seconds for the container to start...

# create the database with strict binary collation
docker exec -it mssql-server /opt/mssql-tools/bin/sqlcmd -S . -U sa -P "$pw" -Q "CREATE DATABASE [$dbname] COLLATE $collation"

# if sqlcmd is in the mssql-tools18 folder
# docker exec -it mssql-server /opt/mssql-tools18/bin/sqlcmd -C -S . -U sa -P "$pw" -Q "CREATE DATABASE [$dbname] COLLATE $collation"

Sie sollten jetzt über einen lokalen SQL Server verfügen, der auf Docker ausgeführt wird und den Port 1443überwacht. Wenn ein Port 1443 mit einem anderen Dienst in Konflikt steht, führen Sie diese Befehle erneut aus, nachdem Sie die Variable $port in einen anderen Wert geändert haben.

Um die Datenbankinstallation zu überprüfen, fragen Sie die neue SQL-Datenbank ab:

docker exec -it mssql-server /opt/mssql-tools/bin/sqlcmd -S . -U sa -P "$pw" -Q "SELECT name FROM sys.databases"

Wenn das Datenbanksetup erfolgreich abgeschlossen wurde, wird der Name Ihrer Datenbank (z. B. DurableDB) in der Befehlszeilenausgabe angezeigt:

name

--------------------------------------------------------------
master

tempdb

model

msdb

DurableDB

Hinweis

Um einen ausgeführten Container zu beenden und zu löschen, können Sie docker stop <containerName> bzw. docker rm <containerName> verwenden. Sie können diese Befehle verwenden, um Ihren Container neu zu erstellen und den Container zu beenden, wenn Sie diese Schnellstartanleitung fertig stellen. Für weitere Unterstützung führen Sie docker --help aus.

Problembehandlung

Wenn beim Ausführen von zum docker exec der Datenbank der Fehler Fehlerantwort von Daemon: Fehler bei der Ausführung der OCI-Runtime auftritt, liegt dies wahrscheinlich daran, dass der Ordner /opt/mssql-tools/bin/sqlcmd nicht vorhanden ist. Öffnen Sie Docker Desktop, wählen Sie Ihren SQL Server-Docker-Container und anschließend „Dateien“ aus, und suchen Sie den Ordner „mssql-tools“. Überprüfen Sie, ob dieser Ordner einen anderen Namen, wie z. B. /opt/mssql-tools18/bin/sqlcmd, hat. Aktualisieren Sie den Befehl entsprechend.

In ODBC-Treiber 18 für SQL Server ist die Option "Verbindung verschlüsseln" standardmäßig auf "true" festgelegt. Wenn beim Ausführen von zum Durchführen von Datenbankvorgängen der Fehler docker exec angezeigt wird, fügen Sie -C an. Dies entspricht der ADO.net-Option TRUSTSERVERCERTIFICATE = true.

Hinzufügen einer SQL-Verbindungszeichenfolge zu local.settings.json

Das MSSQL-Back-End benötigt eine Verbindungszeichenfolge für den Zugriff auf Ihre Datenbank. Die Vorgehensweise zum Abrufen einer Verbindungszeichenfolge hängt primär von Ihrem spezifischen MSSQL-Serveranbieter ab.

Wenn Sie die vorherigen Docker-Befehle verwenden, ohne Parameter zu ändern, lautet ihre Verbindungszeichenfolge:

Server=localhost,1433;Database=DurableDB;User Id=sa;Password=yourStrong(!)Password;

In local.settings.json, weisen Sie die Verbindungszeichenfolge der Docker-basierten SQL Server-Instanz SQLDB_Connection zu. Diese Variable wurde von Visual Studio Code hinzugefügt, wenn Sie MSSQL als Back-End für Ihre Durable Functions-App ausgewählt haben:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true", 
    "SQLDB_Connection": "Server=localhost,1433;Database=DurableDB;User Id=sa;Password=yourStrong(!)Password;",
    "FUNCTIONS_WORKER_RUNTIME": "<dependent on your programming language>"
  }
}

Lokales Testen

Öffnen Sie ein Terminalfenster im Stammordner Ihrer App und führen Sie azurite start aus. Azurite ist der Azure Storage-Emulator, der zum Ausführen einer beliebigen Funktions-App benötigt wird.

Öffnen Sie ein weiteres Terminalfenster im Stammordner Ihrer App, und starten Sie die Funktions-App, indem Sie folgendes ausführen func host start.

1. Kopieren Sie im Terminalfenster den URL-Endpunkt Ihrer http-ausgelösten Funktion.

   

2. Verwenden Sie ein HTTP-Testtool, um eine HTTP POST-Anforderung an den URL-Endpunkt zu senden.

   Die Antwort ist das initiale Ergebnis der HTTP-Funktion. Es teilt Ihnen mit, dass die Durable Functions-Orchestrierung erfolgreich gestartet wurde. Das Endergebnis der Orchestrierung wird noch nicht angezeigt. Die Antwort enthält einige nützliche URLs.

3. Kopieren Sie den URL-Wert für statusQueryGetUri, fügen Sie diesen in die Adressleiste des Browsers ein, und führen Sie die Anforderung aus. Alternativ können Sie auch weiterhin das HTTP-Testtool verwenden, um die GET-Anforderung ausstellen zu können.

   Die Anforderung fragt die Orchestrierungsinstanz der Status ab. Es sollte angezeigt werden, dass die Instanz abgeschlossen ist und diese die Ausgaben oder Ergebnisse der Durable Functions-App wie im folgenden Beispiel enthält:

   {
       "name":"HelloCities",
       "instanceId":"7f99f9474a6641438e5c7169b7ecb3f2",
       "runtimeStatus":"Completed",
       "input":null,
       "customStatus":null,
       "output":"Hello, Tokyo! Hello, London! Hello, Seattle!",
       "createdTime":"2023-01-31T18:48:49Z",
       "lastUpdatedTime":"2023-01-31T18:48:56Z"
   }
   

Ausführen Ihrer App in Azure

Um Ihre App in Azure auszuführen, müssen Sie verschiedene Ressourcen erstellen. Zum späteren Aufräumen erstellen Sie alle Ressourcen in derselben Ressourcengruppe.

Erstellen einer Azure SQL-Datenbank

Hinweis

Wenn Sie bereits über eine Azure SQL-Datenbank oder eine andere öffentlich zugängliche SQL Server-Instanz verfügen, die Sie verwenden möchten, können Sie mit dem nächsten Abschnitt fortfahren.

Vermeiden Sie es, die Einstellung Zulassen, dass Azure-Dienste und -Ressourcen auf diesen [SQL]-Server zugreifen, für Produktionsszenarien zu aktivieren. Echte Anwendungen sollten sicherere Ansätze implementieren, z. B. stärkere Firewalleinschränkungen oder Konfigurationen mit virtuellen Netzwerken.

Im Azure-Portal können Sie eine Azure SQL-Datenbank erstellen. Während der Erstellung:

• Aktivieren von Azure-Diensten und -Ressourcen für den Zugriff auf diesen Server (unter Netzwerk)
• Legen Sie den Wert für die Datenbanksortierung (unter zusätzlichen Einstellungen) auf Latin1_General_100_BIN2_UTF8.

Erstellen einer Azure Functions-App und unterstützender Ressourcen

1. Öffnen Sie ein Terminalfenster, und melden Sie sich bei Azure an:

   az login
   

2. Erstellen Sie die folgenden Ressourcen in derselben Ressourcengruppe und -region wie Ihre SQL-Datenbank:

   • Ein allgemeines Speicherkonto, das zum Speichern wichtiger App-Daten verwendet wird, z. B. den Anwendungscode selbst. Namen von Speicherkonten dürfen nur drei bis 24 Zeichen enthalten, und nur Kleinbuchstaben.
   • Ein Premium-Funktions-App-Tarif
   • Eine Funktions-App

   # Variables
   location=<REGION>
   resourceGroup=<RESOURCE_GROUP_NAME>
   storage=<STORAGE_NAME>
   planName=<PREMIUM_PLAN_NAME>
   functionApp=<APP_NAME>
   skuStorage="Standard_LRS"
   skuPlan="EP1"
   functionsVersion="4"
   
   # Create an Azure storage account
   echo "Creating $storage"
   az storage account create --name $storage --location "$location" --resource-group $resourceGroup --sku $skuStorage --allow-blob-public-access false
   
   # Create a premium plan
   echo "Creating $premiumPlan"
   az functionapp plan create --name $planName --resource-group $resourceGroup --location "$location" --sku $skuPlan
   
   # Create a function app hosted in the premium plan
   echo "Creating $functionApp"
   az functionapp create --name $functionApp --storage-account $storage --plan $planName --resource-group $resourceGroup --functions-version $functionsVersion
   

Erstellen einer verwalteten Azure-Identität

Verwaltete Identitäten machen Ihre App sicherer, indem geheime Schlüssel aus Ihrer App entfernt werden, z. B. Anmeldeinformationen in den Verbindungszeichenfolgen. Sie können zwischen der vom System zugewiesenen und der vom Benutzer zugewiesenen verwalteten Identität wählen. In dieser Schnellstartanleitung wird das Einrichten der vom Benutzer zugewiesenen verwalteten Identität veranschaulicht, was die empfohlene Option ist, da sie nicht an den App-Lebenszyklus gebunden ist.

Mit den folgenden Befehlen wird die Identitätsressource erstellt und der App zugewiesen:

# Variables
subscription=<SUBSCRIPTION_ID>
identity=<IDENTITY_NAME>

# Create a managed identity resource
echo "Creating $identity"
az identity create -g $resourceGroup -n $identity --location "$location"

# Construct the identity resource ID 
resourceId="/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$identity"

# Assign the identity to the Azure Functions app
echo "Assigning $identity to app"
az functionapp identity assign -g $resourceGroup -n $functionApp --identities "$resourceId"

# Get the identity's ClientId and PrincipalId (also called ObjectId) for a later step. 
clientId=$(az identity show --name $identity --resource-group $resourceGroup --query 'clientId' --output tsv)

principalId=$(az identity show --name $identity --resource-group $resourceGroup --query 'principalId' --output tsv)

Gewähren des Zugriffs auf Azure Storage- und Azure SQL-Datenbank

Azure Storage

Weisen Sie die Rolle Besitzer von Speicherblobdaten für den Zugriff auf das Speicherkonto zu.

# Set the scope of the access
scope="/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.Storage/storageAccounts/$storage"

# Assign the role
echo "Assign Storage Blob Data Owner role to identity"
az role assignment create --assignee "$clientId" --role "Storage Blob Data Owner" --scope "$scope"

Azure SQL-Datenbank

Hinweis

Die Authentifizierung bei der Azure SQL-Datenbank mit verwalteter Identität wird beim Hosten einer App für dauerhafte Funktionen im Flex-Verbrauchsplan nicht unterstützt. Wenn Ihre App im Flex-Verbrauchsplan gehostet wird, fahren Sie mit dem Abschnitt " App-Einstellungen festlegen" fort .

1. Legen Sie zunächst Ihre Entwickleridentität als Administrator der Datenbank fest.

   Die zugewiesene Person ist Ihre Identität, ändern Sie daher Ihre E-Mail-Adresse:

   assignee=$(az ad user show --id "someone@example.com" --query "id" --output tsv)
   

   Legen Sie den Beauftragten als Administrator der Azure SQL-Datenbank fest.

   az sql server ad-admin create --resource-group $resourceGroup --server-name <SQL_SERVER_NAME> --display-name ADMIN --object-id "$assignee"
   

2. Stellen Sie eine Verbindung mit der zuvor mithilfe von Azure Data Studio oder SQL Management Server Studio erstellten SQL-Datenbank her. Sie können auch den folgenden SQLCMD-Befehl ausführen, um eine Verbindung herzustellen:

   sqlcmd -S <SQL_SERVER_NAME>.database.windows.net -d <DATABASE_NAME> -U <someone@example.com> -P "ACCOUNT_PASSWORD" -G -l 30
   

   Gewähren Sie Ihrer Identität Zugriff vom Typ db_owner, indem Sie die folgende Abfrage für die Datenbank ausführen. Dies IDENTITY_OBJECT_ID ist die PrincipalId aus dem Identitätserstellungsschritt.

   CREATE USER "<IDENTITY_NAME>" FROM EXTERNAL PROVIDER With OBJECT_ID='<IDENTITY_OBJECT_ID>'
   ALTER ROLE db_owner ADD MEMBER "<IDENTITY_NAME>";
   GO
   

3. Stellen Sie eine Verbindung mit der master Datenbank her, und gewähren Sie Ihrem Identitätsmanager Zugriff:

   CREATE USER "<IDENTITY_NAME>" FROM EXTERNAL PROVIDER With OBJECT_ID='<IDENTITY_OBJECT_ID>'
   ALTER ROLE dbmanager ADD MEMBER "<IDENTITY_NAME>";
   GO
   

Festlegen der erforderlichen App-Einstellungen

Sie müssen Ihrer App die folgenden App-Einstellungen hinzufügen:

• AzureWebJobsStorage__accountName: Name des Azure Storage-Kontos
• AzureWebJobsStorage__clientId: ClientId der verwalteten Identität
• AzureWebJobsStorage__credential: Anmeldeinformationstyp, d. h. managedidentity
• SQLDB_Connection: SQL-Datenbankverbindungszeichenfolge

Wenn Sie die vom Benutzer zugewiesene verwaltete Identität zum Authentifizieren bei der SQL-Datenbank verwenden, sollte die Verbindungszeichenfolge wie folgt aussehen:

dbserver=<SQL_SERVER_NAME>
sqlDB=<SQL_DB_NAME>
clientId=<IDENTITY_CLIENT_ID>

sqlconnstr="Server=tcp:$dbserver.database.windows.net,1433;Initial Catalog=$sqlDB;Persist Security Info=False;User ID=$clientId;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Authentication='Active Directory Managed Identity';"

Verwenden Sie für Apps vom Typ „Flex-Verbrauch“ vorerst eine Verbindungszeichenfolge für die Authentifizierung. Sie finden sie, indem Sie zur SQL-Datenbankressource im Azure-Portal wechseln, zur Registerkarte " Einstellungen " navigieren und dann auf "Verbindungszeichenfolgen" klicken:

Die Verbindungszeichenfolge sollte dieses Format aufweisen:

dbserver=<SQL_SERVER_NAME>
sqlDB=<SQL_DB_NAME>
username=<DB_USER_LOGIN>
password=<DB_USER_PASSWORD>

sqlconnstr="Server=tcp:$dbserver.database.windows.net,1433;Initial Catalog=$sqlDB;Persist Security Info=False;User ID=$username;Password=$password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Führen Sie den folgenden Befehl aus, um die Einstellungen festzulegen:

az functionapp config appsettings set --name $functionApp --resource-group $resourceGroup --settings AzureWebJobsStorage__accountName="$storage" AzureWebJobsStorage__clientId="$clientId" AzureWebJobsStorage__credential="managedidentity" SQLDB_Connection=$sqlconnstr

Löschen Sie die vorhandene AzureWebJobsStorage Einstellung:

az functionapp config appsettings delete --name $functionApp --resource-group $resourceGroup --setting-names "AzureWebJobsStorage"

Bereitstellen des lokalen Projekts in Azure und Testen

Stellen Sie schließlich in Ihrem Stammprojektordner Ihre App in Azure bereit, indem Sie Folgendes ausführen:

func azure functionapp publish $functionApp

Führen Sie nach Abschluss der Bereitstellung Folgendes aus, um die HTTP-Trigger-URL abzurufen:

az functionapp function list --resource-group $resourceGroup --name $functionApp  --query '[].{Function:name, URL:invokeUrlTemplate}' --output json

Testen Sie genau wie bei der lokalen Entwicklung mit einem HTTP-Testtool.

Sie können auch überprüfen, ob das MSSQL-Back-End ordnungsgemäß konfiguriert ist, indem Sie die Datenbank nach Task Hub-Daten abfragen.

Sie können ihre Orchestrierungsinstanzen beispielsweise im Übersichtsbereich Ihrer SQL-Datenbank abfragen. Wählen Sie den Abfrage-Editor aus, authentifizieren Sie, und führen Sie dann die folgende Abfrage aus:

SELECT TOP 5 InstanceID, RuntimeStatus, CreatedTime, CompletedTime FROM dt.Instances

Nachdem Sie einen einfachen Orchestrator ausgeführt haben, sollte mindestens ein Ergebnis angezeigt werden, wie in diesem Beispiel gezeigt:

Nächste Schritte

• Hosten Sie eine Durable Functions-App mit dem MSSQL-Back-End in Azure-Container-Apps.
• Weitere Informationen zur Architektur, Konfiguration und Workload des Backends finden Sie in der DOKUMENTATION des MSSQL-Speicheranbieters .