Quickstart: Een Durable Functions-app maken die gebruikmaakt van de MSSQL-opslagprovider

Gebruik Durable Functions, een functie van Azure Functions, om stateful functies te schrijven in een serverloze omgeving. Durable Functions de status, controlepunten en het opnieuw opstarten in uw toepassing beheert.

Durable Functions ondersteunt verschillende opslagproviders, ook wel bekend als backends, voor het opslaan van de orchestratie- en runtime-status van entiteitstoestanden. In deze quickstart maakt u een Durable Functions-app die gebruikmaakt van de Microsoft SQL Server (MSSQL)-opslagprovider met Visual Studio Code.

In deze quickstart maakt u een .NET-app (geïsoleerd model) voor demonstratiedoeleinden. De concepten zijn op vergelijkbare manieren van toepassing op andere talen.

Vereiste voorwaarden

U hebt het volgende nodig om deze quickstart te voltooien:

• Visual Studio Code geïnstalleerd.

• Azure Functions Visual Studio Code-extensie geïnstalleerd.

• De nieuwste versie van Azure Functions Core Tools geïnstalleerd.

• .NET 8.0 SDK geïnstalleerd.

• Docker geïnstalleerd.

• Een Azure-abonnement.

• Een HTTP-testprogramma waarmee uw gegevens veilig blijven. Zie HTTP-testhulpprogramma's voor meer informatie.

Maak een Azure Functions-project aan

Maak in Visual Studio Code een lokaal Azure Functions project.

1. Selecteer in het menu Beeld het opdrachtpalet (of selecteer Ctrl+Shift+P).

2. Voer bij de prompt (>) Azure Functions in en selecteer vervolgens: Nieuw project maken.

   

3. Kies Bladeren. In het dialoogvenster Map selecteren, navigeer naar een map die u voor uw project wilt gebruiken en kies Selecteren.

4. Selecteer of voer de volgende waarden in bij de prompts:

   Snel	Action	Beschrijving
   Selecteer een taal voor uw functie-app-project	.NET selecteren	Hiermee maakt u een lokaal C#Functions-project
   Selecteer een .NET runtime	Selecteer .NET 8.0 geïsoleerd.	Hiermee maakt u een Functions-project dat ondersteuning biedt voor .NET 8 die wordt uitgevoerd in een geïsoleerd werkproces en de Azure Functions Runtime 4.0.
   Selecteer een sjabloon voor de eerste functie van uw project	Selecteer Durable Functions Orchestratie.	Maakt een Durable Functions-orkestratie aan.
   Een duurzaam opslagtype kiezen	Selecteer MSSQL.	Hiermee selecteert u de MSSQL-opslagprovider.
   Geef een functienaam op	Voer HelloOrchestration in.	Een naam voor de orchestratiefunctie.
   Geef een naamruimte op	Voer Company.Function in.	Een naamruimte voor de gegenereerde klasse.
   Selecteer hoe u uw project wilt openen	Selecteer Openen in het huidige venster.	Hiermee opent u Visual Studio Code in de map die u hebt geselecteerd.

Visual Studio Code installeert Azure Functions Core Tools als het nodig is om het project te maken. Er wordt ook een project voor een functie-app in een map gemaakt. Dit project bevat de configuratiebestanden host.json en local.settings.json.

Een ander bestand, HelloOrchestration.cs, bevat de basisbouwstenen van een Durable Functions-app:

Zie Durable Functions typen en functies voor meer informatie over deze functies.

Uw database opzetten

In deze quickstart wordt een SQL Server Docker-image gebruikt. Zie het overzicht van opslagproviders voor alternatieven (SQL Server Express, Azure SQL Database of een on-premises exemplaar).

Uw lokale SQL Server-exemplaar op basis van Docker instellen

Gebruik de volgende PowerShell-opdrachten om een lokale SQL Server-database in Docker in te stellen. U kunt PowerShell installeren op Windows, macOS of Linux.

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

U moet nu een lokale SQL Server hebben die wordt uitgevoerd op Docker en luistert op poort 1433. Als de poort 1433 conflicteert met een andere service, voert u deze opdrachten opnieuw uit nadat u de variabele $port hebt gewijzigd in een andere waarde.

Als u de installatie van uw database wilt valideren, voert u een query uit op uw nieuwe SQL-database:

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

Als de installatie van de database is voltooid, wordt de naam van uw database (bijvoorbeeld DurableDB) weergegeven in de opdrachtregeluitvoer:

name

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

tempdb

model

msdb

DurableDB

Troubleshooting

Als u 'Foutreactie van daemon: OCI Runtime exec is mislukt' tegenkomt bij het uitvoeren docker exec om de database te maken , bestaat de map /opt/mssql-tools/bin/sqlcmd waarschijnlijk niet. Open Docker Desktop, selecteer uw SQL Server Docker-container, selecteer Bestanden en blader naar de map mssql-tools. Controleer of deze map een andere naam heeft, zoals /opt/mssql-tools18/bin/sqlcmd. Werk de opdracht dienovereenkomstig bij.

In ODBC-stuurprogramma 18 voor SQL Server is de optie Verbinding versleutelen standaard ingesteld op true. Als u 'error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed:self signed certificate' tegenkomt bij het uitvoeren van docker exec om databasebewerkingen uit te voeren, voeg -C toe, wat gelijk is aan de optie ADO.net TRUSTSERVERCERTIFICATE = true.

SQL-verbindingsreeks toevoegen aan local.settings.json

De MSSQL-back-end heeft een verbindingsreeks nodig voor toegang tot uw database. Het verkrijgen van een verbindingsreeks is voornamelijk afhankelijk van uw specifieke MSSQL-serverprovider.

Als u de voorgaande Docker-opdrachten gebruikt zonder parameters te wijzigen, is het verbindingsreeks:

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

Wijs in local.settings.json de verbindingsreeks van het Sql Server-exemplaar op basis van Docker toe aan SQLDB_Connection. Deze variabele is door Visual Studio Code toegevoegd toen u MSSQL als back-end voor uw Durable Functions-app hebt gekozen:

{
  "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>"
  }
}

Lokaal testen

Open een terminalvenster in de hoofdmap van je app en voer azurite start uit. Azurite is de Azure Storage-emulator, die nodig is voor het uitvoeren van een functie-app.

Open een ander terminalvenster in de hoofdmap van uw app en start de functie-app door uit te voeren func host start.

1. Kopieer in het terminalvenster het URL-eindpunt van uw door HTTP geactiveerde functie.

   

2. Gebruik een HTTP-testhulpprogramma om een HTTP POST-aanvraag naar het URL-eindpunt te verzenden.

   Het antwoord is het eerste resultaat van de HTTP-functie. Het laat u weten dat de Durable Functions-orkestratie succesvol is gestart. Het eindresultaat van de orkestratie wordt nog niet weergegeven. De reactie bevat enkele nuttige URL's.

3. Kopieer de URL-waarde voor statusQueryGetUri, plak deze in de adresbalk van uw browser en voer de aanvraag uit. U kunt ook het HTTP-testhulpprogramma blijven gebruiken om de GET-aanvraag uit te geven.

   Het verzoek vraagt de orchestratie-instantie om de status. U ziet dat het exemplaar is voltooid en dat het de uitvoer of resultaten van de Durable Functions-app bevat, zoals in dit voorbeeld:

   {
       "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"
   }
   

Uw app uitvoeren in Azure (optioneel)

In de vorige secties wordt de lokale quickstart voltooid. In de volgende secties wordt uitgelegd hoe u implementeert in Azure. Hiervoor zijn aanvullende resources en configuratie vereist.

Als u uw app wilt uitvoeren in Azure, moet u verschillende resources maken. Voor handige opschoning later maakt u alle resources in dezelfde resourcegroep.

Een Azure SQL-database maken

In de Azure-portal kunt u een Azure SQL-database maken. Tijdens het maken:

• Azure-services en -resources toegang geven tot deze server (onder Netwerken)
• Stel de waarde voor databasesortering (onder Aanvullende instellingen) in op Latin1_General_100_BIN2_UTF8.

Een Azure Functions-app en ondersteunende resources maken

1. Open een terminalvenster en meld u aan bij Azure:

   az login
   

2. Maak de volgende resources in dezelfde resourcegroep en regio als uw SQL-database:

   • Een opslagaccount voor algemeen gebruik, dat wordt gebruikt voor het opslaan van belangrijke app-gegevens, zoals de toepassingscode zelf. Namen van opslagaccounts mogen alleen uit drie tot 24 tekens bestaan.
   • Een premium-functie-app-abonnement
   • Een functie-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
   

Een Azure beheerde identiteit maken

Beheerde identiteiten maken uw app veiliger door geheimen uit uw app te elimineren, zoals referenties in de verbindingsreeksen. U kunt kiezen tussen door het systeem toegewezen en door de gebruiker toegewezen beheerde identiteit. In deze quickstart ziet u hoe u een door de gebruiker toegewezen beheerde identiteit instelt. Dit is de aanbevolen optie omdat deze niet is gekoppeld aan de levenscyclus van de app.

Met de volgende opdrachten maakt u de identiteitsresource en wijst u deze toe aan de app:

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

Toegang verlenen tot Azure Storage en Azure SQL Database

Azure-opslag

Wijs de rol Storage Blob Data Owner toe voor toegang tot het opslagaccount.

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

De beheerde identiteit heeft twee machtigingen nodig: db_owner op uw toepassingsdatabase (om taakhubschema's te maken en te beheren) en dbmanager op de master database (om bewerkingen op databaseniveau toe te staan tijdens het opstarten).

1. Begin met het instellen van uw ontwikkelaarsidentiteit als de beheerder van de database.

   De toegewezen gebruiker vertegenwoordigt jouw identiteit, dus wijzig naar jouw e-mail:

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

   Toegewezen gebruiker instellen als beheerder van de Azure SQL-database:

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

2. Maak verbinding met de SQL-database die u eerder hebt gemaakt met behulp van hulpprogramma's zoals SQL Management Server Studio of Visual Studio Code. U kunt ook de volgende SQLCMD-opdracht uitvoeren om verbinding te maken:

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

   Geef uw identiteit als db_owner toegang door de volgende query op de database uit te voeren. Dit IDENTITY_OBJECT_ID is de PrincipalId van de stap waarin de identiteit wordt gecreëerd.

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

3. Maak verbinding met de master database en verleen uw identiteit dbmanager toegang.

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

Vereiste app-instellingen instellen

U moet de volgende app-instellingen toevoegen aan uw app:

• AzureWebJobsStorage__accountName: Azure Storage-accountnaam
• AzureWebJobsStorage__clientId: ClientId van de beheerde identiteit
• AzureWebJobsStorage__credential: Referentietype, dat een managedidentity is
• SQLDB_Connection: SQL-database verbindingsreeks

Als u een door de gebruiker toegewezen beheerde identiteit gebruikt om te verifiëren bij de SQL-database, moet de verbindingsreeks er als volgt uitzien:

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';"

Voor Flex Consumption-apps gebruikt u een verbindingsreeks om u voorlopig te verifiëren. U vindt deze door naar de SQL-databaseresource in Azure Portal te gaan, naar het tabblad Instellingen te gaan en vervolgens op Verbindingsreeksen te klikken:

De verbindingsreeks moet deze indeling hebben:

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

Voer de volgende opdracht uit om de instellingen in te stellen:

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

Verwijder de bestaande AzureWebJobsStorage instelling:

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

Het lokale project implementeren in Azure en testen

Implementeer ten slotte in de hoofdmap van het project uw app in Azure door het volgende uit te voeren:

func azure functionapp publish $functionApp

Nadat de implementatie is voltooid, voert u het volgende uit om de HTTP-trigger-URL op te halen:

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

Test net als tijdens de lokale ontwikkeling met een HTTP-testhulpprogramma.

U kunt ook controleren of de MSSQL-back-end correct is geconfigureerd door een query uit te voeren op de database voor taakhubgegevens.

U kunt bijvoorbeeld query's uitvoeren op uw orkestratie-instanties in het overzichtsvenster van uw SQL-database. Selecteer Power Query-editor, verifieer en voer de volgende query uit:

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

Nadat u een eenvoudige orchestrator hebt uitgevoerd, ziet u ten minste één resultaat, zoals wordt weergegeven in dit voorbeeld:

Volgende stappen 

• Host een Durable Functions-app met de MSSQL-backend in Azure Container Apps
• Architectuur en configuratie van MSSQL-opslagprovider
• Durable Functions-patronen en -concepten
• Diagnostische gegevens en bewaking
• Over de opslagprovider voor Durable Task Scheduler