撰寫 Azure Functions 並在本機進行測試
雖然您能夠在 Azure 入口網站中開發及測試 Azure Functions,但許多開發人員仍偏好本機開發體驗。 使用 Functions 時,您將可更輕鬆地使用慣用的程式碼編輯器和開發工具,在本機電腦上建立及測試函式。 您的本機函式可以連線到即時 Azure 服務,且您可以使用完整的 Functions 執行階段在本機電腦上進行偵錯。
本文針對您慣用的語言提供特定開發環境的連結。 此外也提供本機開發的一些通用指引,例如使用 local.settings.json 檔案。
本機開發環境
您在本機電腦上開發函式的方式取決於您的語言和工具喜好設定。 下表中的環境支援本機開發:
Environment | 語言 | 描述 |
---|---|---|
Visual Studio Code | C# (內含式) C# (隔離背景工作處理序) JavaScript PowerShell Python |
適用於 VS Code 的 Azure Functions 擴充功能將 Functions 支援新增至 VS Code。 需要 Core Tools。 使用 2.x 版 Core Tools 時,支援在 Linux、macOS 和 Windows 上進行開發。 若要深入了解,請參閱使用 Visual Studio Code 建立第一個函式。 |
命令提示字元或終端機 | C# (內含式) C# (隔離背景工作處理序) JavaScript PowerShell Python |
Azure Functions Core Tools 提供核心執行階段和範本來建立函式,以便進行本機開發。 2.x 版支援在 Linux、macOS 和 Windows 上進行開發。 所有環境都依賴 Core Tools 執行本機 Functions 執行階段。 |
Visual Studio | C# (內含式) C# (隔離背景工作處理序) |
自 Visual Studio 2019 開始,Visual Studio 的 Azure 開發工作負載中包含 Azure Functions 工具。 讓您編譯類別庫中的函式,並將 .dll 發佈至 Azure。 包括用於本機測試的 Core Tools。 若要深入了解,請參閱使用 Visual Studio 開發 Azure Functions。 |
Maven (各種) | Java | Maven 原型支援 Core Tools 以進行 Java 函式開發。 2.x 版支援在 Linux、macOS 和 Windows 上進行開發。 若要深入了解,請參閱使用 Java 和 Maven 建立您的第一個函式。 此外也支援使用 Eclipse 和 IntelliJ IDEA 進行開發。 |
注意
由於 Azure 入口網站中編輯函式程式碼的限制,您應該在本機開發函式,並將程式碼專案發佈至 Azure 中的函數應用程式。 如需詳細資訊,請參閱 Azure 入口網站中的開發限制
每個本機開發環境都可讓您建立函式應用程式專案,並使用預先定義的函式範本來建立新的函式。 每個環境都會使用 Core Tool,以便您在自己的電腦上針對實際的 Functions 執行階段進行您的函式測試和偵錯,就如同處理任何其他應用程式一樣。 您也可以從上述任何環境將您的函式應用程式專案發佈至 Azure。
本機專案檔
不論何種語言,Azure Functions 專案目錄都在專案根資料夾中包含下列檔案:
檔案名稱 | 描述 |
---|---|
host.json | 若要深入了解,請參閱 host.json 參考。 |
local.settings.json | Core Tools 在本機執行時使用的設定,包括應用程式設定。 若要深入了解,請參閱本機設定檔案。 |
gitignore。 | 防止 local.settings.json 檔案意外發佈至 Git 存放庫。 若要深入了解,請參閱本機設定檔案。 |
.vscode\extensions.json | 在 Visual Studio Code 中開啟專案資料夾時使用的設定檔案。 |
專案中的其他檔案取決於您的語言和特定函式。 如需詳細資訊,請參閱以您的語言撰寫的開發人員指南。
本機設定檔
local.settings.json 檔案會儲存本機開發工具所使用的應用程式設定和設定。 只有當您在本機執行專案時,才會使用 local.settings.json 檔案中的設定。 當您將專案發佈至 Azure 時,請務必同時將任何必要的設定新增至函數應用程式的應用程式設定。
重要
因為 local.settings.json 可能包含秘密,例如連接字串,請勿儲存在遠端存放庫。 支援 Functions 的工具,可用來同步處理 local.settings.json 檔案中的設定與專案部署所在之函式應用程式中的應用程式設定。
本機設定檔案具有以下結構:
{
"IsEncrypted": false,
"Values": {
"FUNCTIONS_WORKER_RUNTIME": "<language worker>",
"AzureWebJobsStorage": "<connection-string>",
"MyBindingConnection": "<binding-connection-string>",
"AzureWebJobs.HttpExample.Disabled": "true"
},
"Host": {
"LocalHttpPort": 7071,
"CORS": "*",
"CORSCredentials": false
},
"ConnectionStrings": {
"SQLConnectionString": "<sqlclient-connection-string>"
}
}
當您在本機執行專案時,支援下列設定:
設定 | 描述 |
---|---|
IsEncrypted |
當此設定設為 true 時,所有的值都會以本機電腦金鑰加密。 需搭配 func settings 命令使用。 預設值為 false 。 當本機電腦中包含秘密 (例如服務連接字串) 時,您可能想要對其進行加密。 主機會在執行時自動解密設定。 請先使用 func settings decrypt 命令,然後再嘗試讀取本機加密的設定。 |
Values |
專案在本機執行時所使用的應用程式設定集合。 這些索引鍵/值 (字串-字串) 組會對應至 Azure 中函式應用程式的應用程式設定,例如 AzureWebJobsStorage 。 許多觸發程序和繫結都有參考連結字串應用程式設定的屬性,例如 Blob 儲存體觸發程序的 Connection 屬性。 對於這類屬性,您需要在 Values 陣列中定義的應用程式設定。 如需常用的設定清單,請參閱後續表格。 值必須是字串,而不是 JSON 物件或陣列。 設定名稱不可包含雙底線 ( __ ),且不應包含冒號 (: )。 執行階段會保留雙底線字元,並且會保留冒號以支援相依性插入。 |
Host |
當您在本機執行專案時,本節中的設定會自訂 Functions 主機程序。 這些設定與 host.json 設定不同,也適用於您在 Azure 中執行專案時。 |
LocalHttpPort |
設定於執行本機 Functions 主機 (func host start 和 func run ) 時所使用的預設連接埠。 --port 命令列選項的優先順序高於此設定。 例如,在 Visual Studio IDE 中執行時,您可以瀏覽至 [專案屬性 -> 偵錯] 視窗,並在 host start --port <your-port-number> 命令中明確指定可在 [應用程式引數] 欄位中提供的連接埠號碼,以變更連接埠號碼。 |
CORS |
定義針對跨來源資源共享 (CORS) 所允許的來源。 來源是以不含空格的逗號分隔清單提供。 支援萬用字元值 (*),允許來自任何來源的要求。 |
CORSCredentials |
若設定為 true ,則允許 withCredentials 要求。 |
ConnectionStrings |
集合。 請勿將此集合用於您函式繫結所使用的連接字串。 此集合僅供架構使用,其通常會從組態檔的 ConnectionStrings 區段取得連接字串,例如 Entity Framework。 此物件中的連接字串會新增至具有 System.Data.SqlClient 提供者類型的環境。 此集合中的項目不會發佈至具備其他應用程式設定的 Azure。 您必須明確地將這些值新增到函式應用程式設定的 Connection strings 集合。 如果要在函式程式碼中建立 SqlConnection ,則應將連接字串值連同您的其他連線一起儲存在入口網站的 [應用程式設定] 中。 |
在本機執行時,下列應用程式設定可以包含在 Values
陣列中:
設定 | 值 | 描述 |
---|---|---|
AzureWebJobsStorage |
儲存體帳戶連接字串,或UseDevelopmentStorage=true |
包含 Azure 儲存體帳戶的連接字串。 使用 HTTP 以外的觸發程式時為必要項。 如需詳細資訊,請參閱 AzureWebJobsStorage 參考。當您在本機安裝 Azurite 模擬器,並將 AzureWebJobsStorage 設定為 UseDevelopmentStorage=true 時,Core Tools 會使用該模擬器。 如需詳細資訊,請參閱本機儲存體模擬器。 |
AzureWebJobs.<FUNCTION_NAME>.Disabled |
true |false |
若要在本機執行時停用函式,請將 "AzureWebJobs.<FUNCTION_NAME>.Disabled": "true" 新增至集合,其中 <FUNCTION_NAME> 是函式的名稱。 若要深入了解,請參閱如何停用 Azure Functions 中的函式。 |
FUNCTIONS_WORKER_RUNTIME |
dotnet dotnet-isolated node java powershell python |
表示 Functions 執行階段的目標語言。 在 2.x 版和更高版本的 Functions 執行階段中為必要項。 這項設定是由核心工具會為您的專案所產生。 若要深入了解,請參閱 FUNCTIONS_WORKER_RUNTIME 參考。 |
FUNCTIONS_WORKER_RUNTIME_VERSION |
~7 |
指出在本機執行時應使用 PowerShell 7。 如果未設定,則會使用 PowerShell Core 6。 只有在本機執行時,才會使用此設定。 在 Azure 中執行時,PowerShell 執行階段版本是由 powerShellVersion 網站組態設定所決定 (可在入口網站中設定)。 |
同步處理設定
當您在本機開發函式時,您部署程式碼的函數應用程式應用程式設定中,也必須出現應用程式所需的任何本機設定。 您可能也需要從函數應用程式將目前的設定下載到本機專案。 雖然您可以在 Azure 入口網站中手動設定應用程式設定,但下列工具也可讓您將應用程式設定與專案中的本機設定進行同步處理:
觸發和繫結
在本機開發函式時,您必須考慮觸發程序和繫結行為。 針對 HTTP 觸發程序,您可以使用 http://localhost/
,在本機電腦上簡單地呼叫 HTTP 端點。 針對非 HTTP 觸發的函式,有數個選項可在本機執行:
- 在本機開發期間測試繫結最簡單的方式是使用以即時 Azure 服務為目標的連接字串。 您可以在 local.settings.json 檔案的
Values
陣列中新增適當的連接字串設定,以將即時服務設為目標。 當您這樣做時,測試期間的本機執行就會影響即時服務資料。 因此,請考慮在開發和測試期間設定使用不同的服務,然後在生產期間切換至差異服務。 - 針對儲存體型觸發程序,您可使用本機儲存體模擬器。
- 您可使用特殊的系統管理員端點,手動執行非 HTTP 觸發程序函式。 如需詳細資訊,請參閱手動執行非 HTTP 觸發的函式。
在本機測試期間,您必須在本機執行 Core Tools (func.exe) 所提供的主機。 如需詳細資訊,請參閱 Azure Functions Core Tools。
HTTP 測試工具
在開發期間,當您支援 HTTP GET 方法時,很容易從網頁瀏覽器呼叫任何函式端點。 不過,對於支援 POST 或 PUT 等承載的其他 HTTP 方法,您必須使用 HTTP 測試工具來建立這些 HTTP 要求,並將其傳送至函式端點。
警告
針對要求必須包含敏感數據的案例,請務必使用可保護您的數據的工具,並降低向公用公開任何敏感數據的風險。 您應該保護的敏感數據可能包括:認證、秘密、存取令牌、API 密鑰、地理位置數據,甚至是個人標識資訊(PII)。
您可以選擇離線或本機運作的 HTTP 測試工具,來保護您的資料,不會將資料同步處理至雲端,而且不需要您登入線上帳戶。 某些工具也可以藉由實作特定的安全性功能,保護您的數據免於意外暴露。
避免使用集中儲存 HTTP 要求歷程記錄的工具(包括敏感性資訊)、不要遵循最佳安全性做法,或不尊重數據隱私權考慮。
請考慮使用下列其中一個工具來安全地將 HTTP 要求傳送至您的函式端點:
- Visual Studio Code 搭配 Visual Studio Marketplace 的擴充功能,例如 REST 用戶端
- PowerShell Invoke-RestMethod
- Microsoft Edge - 網路主控台工具
- Bruno
- curl
本機儲存體模擬器
在本機開發期間,您可以在使用 Azure 儲存體繫結 (佇列儲存體、Blob 儲存體和表格儲存體) 測試函式時,使用本機 Azurite 模擬器,而不必連線到遠端儲存體服務。 Azurite 會與 Visual Studio Code 和 Visual Studio 整合,您也可以使用 npm,從命令提示字元加以執行。 如需詳細資訊,請參閱使用 Azurite 模擬器進行本機 Azure 儲存體開發。
local.settings.json 檔案 Values
集合中的下列設定會告知本機 Functions 主機,針對預設 AzureWebJobsStorage
連線使用 Azurite:
"AzureWebJobsStorage": "UseDevelopmentStorage=true"
採用此設定值,任何使用 AzureWebJobsStorage
來做為其連線的 Azure 儲存體觸發程序或繫結,都會在本機執行時連線到 Azurite。 在本機執行期間使用儲存體模擬時,請記住這些考量:
- 您必須安裝並執行 Azurite。
- 在發佈至 Azure 之前,您應該先測試與 Azure 服務的實際儲存體連線。
- 當您發佈專案時,請勿以
UseDevelopmentStorage=true
形式發佈AzureWebJobsStorage
設定。 在 Azure 中,AzureWebJobsStorage
設定一律是函式應用程式所使用的儲存體帳戶連接字串。 如需詳細資訊,請參閱AzureWebJobsStorage
。
下一步
- 若要深入了解如何使用 Visual Studio 在本機開發已編譯的 C# 函式 (包含內含式和隔離背景工作處理序),請參閱使用 Visual Studio 開發 Azure Functions。
- 若要深入了解如何在 Mac、Linux 或 Windows 電腦上使用 VS Code 進行函式的本機開發,請參閱您慣用語言的 Visual Studio Code 入門文章:
- 若要深入了解如何從命令提示字元或終端機開發函式,請參閱使用 Azure Functions Core Tools。