共用方式為

快速入門：建立使用 MSSQL 記憶體提供者的 Durable Functions 應用程式

使用 Durable Functions (Azure Functions 的功能)，在無伺服器環境中撰寫具狀態函式。 Durable Functions 會管理您應用程式中的狀態、檢查點和重新啟動。

Durable Functions 支援數個 儲存提供者，也稱為 後端，用於儲存協調流程和實體運行時間狀態。 在本快速入門中，您會使用 Visual Studio Code 建立 Durable Functions 應用程式，以使用 Microsoft SQL Server （MSSQL） 儲存提供者。

本快速入門將建立一個 .NET（隔離模型）應用程式，作為示範系統之用。 本文中提供的內容會以類似的方式套用至其他語言。

注意

  • MSSQL 後端的設計訴求是最大化應用程式的可移植性及控制您的資料。 其會使用 Microsoft SQL Server 保存所有工作中樞資料，以便使用者享有現代化企業級資料庫管理系統 (DBMS) 基礎結構的優點。 若要深入了解何時應使用 MSSQL 儲存體提供者，請參閱儲存體提供者概觀。

  • 目前不支援跨儲存體提供者移轉工作中樞資料。 在具有現有執行階段資料的函數應用程式切換至 MSSQL 後端之後，其會以全新的空白工作中樞開始。 同樣地，如果您切換至不同的儲存體提供者，則無法保留使用 MSSQL 建立的工作中樞內容。

必要條件

若要完成本快速入門，您需要：

建立 Azure Functions 專案

在 Visual Studio Code 中，建立 本機 Azure Functions 專案。

  1. 在 [檢視] 功能表上，選取 [命令選擇區] (或選取 Ctrl+Shift+P)。

  2. 在提示 (>) 中，輸入然後選取 [Azure Functions：建立新專案]。

    螢幕擷取畫面顯示建立 Functions 專案的命令。

  3. 選取瀏覽。 在 [選取資料夾] 對話框中，移至要用於您專案的資料夾，然後選擇 [選取]。

  4. 在提示中，選取或輸入下列值：

    提示 行動 說明
    為您的函數應用程式專案選取語言 選擇 .NET 建立本機 C# Functions 專案
    選取 .NET 執行階段 選取 [.NET 8.0 隔離式方案]。 建立函式專案，使其可支援在隔離式背景工作處理序和 Azure Functions 執行階段 4.0 中執行的 .NET 8。
    為專案的第一個函式選取範本 選取 [Durable Functions 協調流程]。 建立 Durable Functions 協調流程。
    選擇耐久儲存體類型 選取 [MSSQL]。 選取 MSSQL 記憶體提供者。
    提供函式名稱 輸入 [HelloOrchestration]。 協調流程函式的名稱。
    提供命名空間 輸入 [Company.Function]。 所產生類別的命名空間。
    選取您開啟專案的方式 選取 [在目前視窗中開啟]。 在您選取的資料夾中開啟 Visual Studio Code。

如果需要建立專案，Visual Studio Code 就會安裝 Azure Functions Core Tools。 其也會在資料夾中建立函式應用程式專案。 此專案包含 host.json 和 local.settings.json 組態檔。

另一個檔案 (HelloOrchestration.cs) 包含 Durable Functions 應用程式的基本建置組塊：

方法 說明
HelloOrchestration 定義 Durable Functions 應用程式協調流程。 在此情況下，協調流程會啟動、建立清單，然後將三個函式呼叫的結果新增至清單。 完成三個函式呼叫後，它會傳回清單。
SayHello 傳回您好的簡單函數應用程式。 此函式包含要進行協調的商務邏輯。
HelloOrchestration_HttpStart HTTP 觸發的函式，該函式會啟動協調流程執行個體並傳回檢查狀態回應。

如需這些函式的詳細資訊，請參閱 Durable Functions 類型和功能。

設定您的資料庫

注意

如果您已有與 MSSQL 相容的資料庫，則可以跳過本節，並跳過下一節有關設定 Docker 型本機資料庫的部分。

因為 MSSQL 後端是專為可移植性所設計，因此您有數個選項可設定備份資料庫。 例如，您可以設定內部部署 SQL Server 執行個體、使用 Azure SQL Database 完全受控執行個體，或使用任何其他與 SQL Server 相容的裝載選項。

您也可以在本機 Windows 電腦上使用 SQL Server Express 進行本機的離線開發，或使用在 Docker 容器中執行的 SQL Server Docker 映像。

本快速入門專注於使用 SQL Server Docker 映像。

設定您的本機 Docker 型 SQL Server 執行個體

使用下列 PowerShell 命令在 Docker 上設定本機 SQL Server 資料庫。 您可以在 Windows、macOS 或 Linux 上安裝 PowerShell。

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

您現在應該有在 Docker 上執行的本機 SQL Server，並在連接埠 1443上接聽 。 如果埠 1443 與其他服務衝突，請在將變數 $port 變更為不同的值之後，重新執行這些命令。

若要驗證資料庫安裝，請查詢新的 SQL 資料庫：

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

如果資料庫設定順利完成，您資料庫的名稱 (例如，DurableDB) 會出現在命令列輸出中：

name

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

tempdb

model

msdb

DurableDB

注意

若要停止和刪除執行中的容器，您可以分別使用 docker stop <containerName> 和 docker rm <containerName>。 您可以使用這些命令來重新建立容器，並在您完成本快速入門之後停止該容器。 如需更多協助，請執行 docker --help。

故障排除

如果您在執行 以docker exec資料庫時遇到「精靈的錯誤回應：OCI 運行時間 exec 失敗」，則資料夾/opt/mssql-tools/bin/sqlcmd可能不存在。 開啟 Docker Desktop，選取您的 SQL Server Docker 容器，選取 [檔案]，然後流覽 mssql-tools 資料夾。 檢查此資料夾是否有其他名稱，例如 /opt/mssql-tools18/bin/sqlcmd。 請據以更新命令。

在 ODBC Driver 18 for SQL Server 中，[加密連線] 選項預設會設定為 true。 如果您在執行 執行資料庫作業時遇到 docker exec，請附加 -C，這相當於 ADO.net 選項TRUSTSERVERCERTIFICATE = true。

將 SQL 連接字串新增至 local.settings.json

MSSQL 後端需要連接字串才能存取您的資料庫。 如何取得連接字串主要取決於您的特定 MSSQL 伺服器提供者。

如果您使用上述 Docker 命令，而未變更任何參數，則您的連接字串為：

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

在 local.settings.json中，將 Docker 型 SQL Server 實體的連接字串指派給 SQLDB_Connection。 當您選擇 MSSQL 作為 Durable Functions 應用程式的後端時，Visual Studio Code 會新增此變數：

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

在本機進行測試

在應用程式的根資料夾中開啟終端機視窗，然後執行 azurite start。 Azurite 是執行任何函式應用程式所需的 Azure 記憶體模擬器。

在應用程式的根資料夾中開啟另一個終端機視窗，然後執行 func host start來啟動函式應用程式。

  1. 在終端機視窗中，複製 HTTP 觸發函式的 URL 端點。

    Azure 本機輸出視窗的螢幕擷取畫面。

  2. 使用 HTTP 測試工具將 HTTP POST 要求傳送至 URL 端點。

    回應是 HTTP 函式的初始結果。 它可讓您知道 Durable Functions 協調流程已成功啟動。 它還沒顯示協調流程的最終結果。 回應包含一些實用的 URL。

  3. 複製 statusQueryGetUri 的 URL 值，並將其貼在瀏覽器的網址列中，然後執行要求。 或者，您也可以繼續使用 HTTP 測試工具來發出 GET 要求。

    此要求會查詢協調流程執行個體的狀態。 您應該會看到執行個體已完成，而且它包含 Durable Functions 應用程式的輸出或結果，如下列範例所示：

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

在 Azure 中執行您的應用程式

若要在 Azure 中執行您的應用程式，您必須建立各種資源。 為了方便稍後清除，請在相同的資源群組中建立所有資源。

建立 Azure SQL 資料庫

注意

如果您已有一個 Azure SQL 資料庫，或另一個您想要使用的可公開存取 SQL Server，則可以移至下一節。

避免針對生產案例啟用 [允許 Azure 服務和資源存取此 [SQL] 伺服器 設定。 實際應用程式應該實作更安全的方法，例如更強大的防火牆限制或虛擬網路設定。

在 Azure 入口網站中，您可以建立 Azure SQL 資料庫。 創建過程中：

  • 啟用 Azure 服務與資源來存取此伺服器（在 [網路] 下）
  • 將 [資料庫順序 ] 的值 （ 在 [其他設定] 下設定為 Latin1_General_100_BIN2_UTF8。

建立 Azure Functions 應用程式和支持資源

  1. 開啟終端機視窗並登入 Azure：

    az login

  2. 在與 SQL 資料庫相同的資源群組和區域中建立下列資源：

    • 一般用途的記憶體帳戶，用來儲存重要的應用程式數據，例如應用程式程序代碼本身。 記憶體帳戶名稱必須包含三到 24 個字元的數位和小寫字母。
    • 進階函式應用程式方案
    • 函式應用程式
    # 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

建立 Azure 受控識別

受控識別可藉由排除來自您應用程式的秘密，例如連接字串中的認證，讓您的應用程式更安全。 您可以選擇 系統指派和使用者指派的受控識別。 本快速入門示範如何設定使用者指派的受控識別，這是建議的選項，因為它未繫結至應用程式生命週期。

下列命令會建立身分識別資源，並將它指派給應用程式：

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

授與 Azure 記憶體和 Azure SQL Database 的存取權

Azure 儲存服務

指派身分識別 儲存 Blob 資料擁有者 角色，以存取儲存帳戶。

# 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 資料庫

注意

在 Flex Consumption 計費方案中裝載 Durable Functions 應用程式時，不支援使用受控識別向 Azure SQL 資料庫進行驗證。 如果您的應用程式裝載於 Flex Consumption 方案中，請跳至 [設定應用程式設定 ] 區段。

  1. 首先，將開發人員身分識別設定為資料庫的系統管理員。

    被指派者是您的身分識別，因此請變更為電子郵件：

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

    將被指派者設定為 Azure SQL 資料庫的管理員：

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

  2. 聯機到先前使用 Azure Data Studio 或 SQL Management Server Studio 等工具建立的 SQL 資料庫。 或者，您可以執行下列 SQLCMD 命令來連線：

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

    對資料庫執行下列查詢 ，以授與 身分識別db_owner存取權。 IDENTITY_OBJECT_ID是身分識別建立步驟中的 PrincipalId。

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

  3. 連接到 master 資料庫，並授予您的身分識別 dbmanager 存取權：

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

設定必要的應用程式設定

您必須將下列應用程式設定新增至您的應用程式：

  • AzureWebJobsStorage__accountName：Azure 記憶體帳戶名稱
  • AzureWebJobsStorage__clientId：受控身分識別的 ClientId
  • AzureWebJobsStorage__credential：認證類型，這是 managedidentity
  • SQLDB_Connection：SQL 資料庫連接字串

如果您使用使用者指派的受控識別向 SQL 資料庫進行驗證，連接字串看起來應該如下所示：

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

針對 Flex Consumption 應用程式，請使用連接字串立即進行驗證。 您可以移至 Azure 入口網站上的 SQL 資料庫資源，瀏覽至 設定 索引標籤，然後點擊 連接字串 來找到它。

顯示資料庫連接字串的螢幕快照。

連接字串應該具有下列格式：

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

執行下列命令來設定設定：

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

刪除現有的 AzureWebJobsStorage 設定：

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

將本地開發的專案部署到 Azure 進行測試

最後，在您的根項目資料夾中，執行下列命令，將您的應用程式部署至 Azure：

func azure functionapp publish $functionApp

部署完成之後，請執行下列命令以取得 HTTP 觸發程式 URL：

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

就像使用 HTTP 測試工具在 本機開發 期間所做的一樣進行測試。

您也可以藉由查詢資料庫來查詢工作中樞數據，來驗證 MSSQL 後端是否已正確設定。

例如，您可以在 SQL 資料庫的 [概觀] 窗格上查詢協調流程執行個體。 選取 [查詢編輯器]、驗證，然後執行下列查詢：

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

在執行簡單的協調器之後，您應該會看到至少一個結果，如下列範例所示：

螢幕擷取畫面顯示 SQL 查詢的 Azure SQL 查詢編輯器結果。

後續步驟