使用 Azure Functions Core Tools

Azure Functions Core Tools 可讓您使用命令提示字元或終端機,在本機電腦上開發及測試函式。 您的本機函式可以連線到即時 Azure 服務,而且您可以在本機電腦上使用完整的 Functions 執行階段進行您的函式偵錯。 您甚至可以將函式應用程式部署至您的 Azure 訂用帳戶。

注意

請勿在相同函式應用程式中混用本機開發與入口網站開發。 當您從本機專案建立及發佈函式時,將無法在入口網站中維護或修改專案程式碼。

在本機電腦上開發函式,並使用 Core Tools 發佈至 Azure,請遵循下列基本步驟:

先決條件

Core Tools 的特定必要條件取決於您打算使用的功能:

發佈:Core Tools 目前依賴 Azure CLIAzure PowerShell 向 Azure 帳戶進行驗證。 這表示您必須安裝其中一個工具,才能從 Azure Functions Core Tools 發佈至 Azure

安裝延伸模組:若要使用 Core Tools 手動安裝延伸模組,您必須安裝 .NET Core 3.1 SDK。 Core Tools 會使用 .NET Core SDK 從 NuGet 安裝延伸模組。 您不需要懂 .NET 就能使用Azure Functions 延伸模組。

Core Tools 版本

Azure Functions Core Tools 有四個版本。 您使用的版本取決於本機開發環境、選擇的語言,以及所需的支援層級。

在下方選擇版本索引標籤,以了解每個特定版本,並取得詳細的安裝指示:

支援 Azure Functions 執行階段 4.x 版。 此版本支援 Windows、macOS 和 Linux,並使用平台特定的套件管理員或 npm 進行安裝。 這是建議的 Azure Functions 執行階段和 Core Tools 版本。

任一電腦上只能安裝一個 Core Tools 版本。 除非另外註明,否則本文中的範例適用於 3.x 版。

安裝 Azure Functions Core Tools

Azure Functions Core Tools 包含相同的執行階段版本,以支援您可在本機開發電腦上執行的 Azure Functions 執行階段。 它也提供命令來建立函式、連線到 Azure,以及部署函式專案。

從 2.x 版開始,Core Tools 在 WindowsmacOSLinux 上執行。

下列步驟使用 Windows 安裝程式 (MSI) 來安裝 Core Tools v4.x。 如需其他套件型安裝程式的詳細資訊,請參閱 Core Tools 讀我檔案

根據您的 Windows 版本,下載並執行 Core Tools 安裝程式:

變更 Core Tools 版本

變更為不同版本的 Core Tools 時,您應該使用與原始安裝相同的套件管理員,以改用不同的套件版本。 例如,假設您已使用 npm 安裝 Core Tools 2.x 版,則應該使用下列命令來升級至 3.x 版:

npm install -g azure-functions-core-tools@3 --unsafe-perm true

如果您使用 Windows 安裝程式 (MSI) 在 Windows 上安裝 Core Tools,則應該先從 [新增移除程式] 解除安裝舊版本,再安裝不同的版本。

建立本機的 Functions 專案

不論何種語言,Azure Functions 專案目錄都包含下列檔案和資料夾:

檔案名稱 描述
host.json 若要深入了解,請參閱 host.json 參考
local.settings.json Core Tools 在本機執行時使用的設定,包括應用程式設定。 若要深入了解,請參閱本機設定
.gitignore 防止 local.settings.json 檔案意外發佈至 Git 存放庫。 若要深入了解,請參閱本機設定
.vscode\extensions.json 在 Visual Studio Code 中開啟專案資料夾時使用的設定檔案。

若要深入了解 Azure Functions 專案資料夾,請參閱 Azure Functions 開發人員指南

在終端機視窗或命令提示字元中,執行下列命令來建立專案和本機 Git 存放庫:

func init MyFunctionProj

此範例在新的 MyFunctionProj 資料夾中建立 Azure Functions 專案。 將會提示您選擇專案的預設語言。

專案初始化時有下列考量:

  • 如果您在命令中未提供 --worker-runtime 選項,則會提示您選擇語言。 如需詳細資訊,請參閱 func init 參考

  • 如果未提供專案名稱,則會初始化目前的資料夾。

  • 如果您打算將專案發佈至自訂 Linux 容器,請使用 --docker 選項,確保為您的專案產生 Dockerfile。 若要深入了解,請參閱使用自訂映像在 Linux 上建立函式

某些語言可能有其他考量:

  • Core Tools 可讓您為 .NET 執行時間建立函式應用程式專案,作為 同進程隔離的背景工作進程 C# 類別庫專案, (.csproj) 。 這些專案可與 Visual Studio 或Visual Studio Code搭配使用,會在偵錯期間和發佈至 Azure 時進行編譯。

  • 如果要在本機使用 C# 指令碼 (.csx) 檔案,請使用 --csx 參數。 當您在 Azure 入口網站 中建立函式,以及使用 1.x 版 Core Tools 時,這些是您取得的相同檔案。 若要深入了解,請參閱 func init 參考

註冊延伸模組

從執行階段 2.x 版開始,Azure Functions 觸發程序和繫結實作為 .NET 延伸模組 (NuGet) 套件。 在已編譯的 C# 專案中,只需要針對您使用的特定觸發程序和繫結,參考 NuGet 延伸模組套件。 HTTP 繫結和計時器觸發程序不需要延伸模組。

為了改善非 C# 專案的開發體驗,Azure Functions 可讓您在 host.json 專案檔中參考已建立版本的延伸模組套件組合。 延伸模組套件組合提供所有延伸模組給您的應用程式使用,還避免延伸模組之間發生套件相容性問題。 透過延伸模組套件組合,您也不需要安裝 .NET Core 3.1 SDK 和處理 extensions.csproj 檔案。

如果函式專案不是 C# 編譯的專案或 C# 指令碼,則建議使用延伸模組套件組合。 針對這些專案,初始化期間會在 host.json 檔案中產生延伸模組套件組合設定。 如果未啟用套件組合,您必須更新專案的 host.json 檔案。

安裝繫結擴充功能最簡單的方式是啟用擴充功能套件組合。 當您啟用套件組合時,系統會自動安裝一組預先定義的擴充功能套件。

若要啟用擴充功能套件組合,請開啟 host.json 檔案,並更新其內容以符合下列程式碼:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[2.*, 3.0.0)"
    }
}

若要深入了解,請參閱註冊 Azure Functions 繫結延伸模組

在非 .NET 專案中,有時無法使用延伸模組套件組合,例如您需要以套件組合中沒有的特定延伸模組版本為目標。 在這些罕見情況下,您可以使用 Core Tools 在本機安裝專案所需的特定延伸模組套件。 若要深入了解,請參閱安裝延伸模組

本機設定

在 Azure 中的函數應用程式中執行時,函式所需的設定安全地儲存在應用程式設定中。 在本機開發期間,這些設定改為新增至 local.settings.json 檔案中的 Values 物件。 local.settings.json 檔案也儲存本機開發工具使用的設定。

因為 local.settings.json 可能包含秘密,例如連接字串,請勿儲存在遠端存放庫。 若要深入了解本機設定,請參閱本機設定檔案

根據預設,在專案發佈至 Azure 時,這些設定將不會自動移轉。 在發佈時使用 --publish-local-settings 選項,以確保這些設定會新增至 Azure 中的函數應用程式。 絕不會發佈 ConnectionStrings 區段中的值。

這些函數應用程式設定值在您的程式碼中也可以做為環境變數加以讀取。 如需詳細資訊,請參閱這些特定語言參考主題的「環境變數」章節:

如果未設定 AzureWebJobsStorage 有效的儲存體連接字串,且未使用本機儲存體模擬器,則會顯示下列錯誤訊息:

在 local.settings.json 中遺失 AzureWebJobsStorage 的值。 這對 HTTP 以外的所有觸發程序是必要的。 您可以執行 'func azure functionapp fetch-app-settings <functionAppName>',或指定 local.settings.json 中的連接字串。

取得您的儲存體連接字串

即使使用 Azurite 儲存體模擬器 進行開發,您可能想要使用實際的儲存體連線在本機執行。 假設您已建立儲存體帳戶,有幾種方式可讓您取得有效的儲存體連接字串:

  1. Azure 入口網站,搜尋並選取儲存體帳戶

    從 Azure 入口網站選取 [儲存體帳戶]。

  2. 選取您的儲存體帳戶,並在 [設定] 中選取 [存取金鑰],然後複製其中一個 [連接字串] 值。

    從 Azure 入口網站複製連接字串

建立函式

若要在現有專案中建立函式,請執行下列命令:

func new

在 3.x/2.x 版中,執行 func new 時會提示您根據函數應用程式的預設語言來選擇範本。 接著會提示您選擇函式的名稱。 在 1.x 版中,也會提示您選擇語言。

您也可以在 func new 命令中指定函式名稱和範本。 下列範例使用 --template 選項來建立名為 MyHttpTrigger 的 HTTP 觸發程序:

func new --template "Http Trigger" --name MyHttpTrigger

此範例建立名為 MyQueueTrigger 的佇列儲存體觸發程序:

func new --template "Azure Queue Storage Trigger" --name MyQueueTrigger

若要深入了解,請參閱 func new 命令

在本機執行函式

若要執行 Azure Functions 專案,請從專案的根目錄執行 Azure Functions 主機。 此主機對專案中的所有函式啟用觸發程序。 視您的專案語言而定,start 命令會有所不同。

func start

注意

Azure Functions 執行階段 1.x 版需要 func host start。 若要深入了解,請參閱 Azure Functions Core Tools 參考

Azure Functions 主機啟動時會輸出 HTTP 觸發函式的 URL,如下列範例所示:

Found the following functions:
Host.Functions.MyHttpTrigger

Job host started
Http Function MyHttpTrigger: http://localhost:7071/api/MyHttpTrigger

重要

在本機執行時,不會強制授權 HTTP 端點。 這表示所有的本機 HTTP 要求會作為 authLevel = "anonymous" 處理。 如需詳細資訊,請參閱 HTTP 繫結文章

將測試資料傳遞至函式

若要在本機測試您的函式,您要使用 HTTP 要求在本機伺服器上啟動 Functions 主機並呼叫端點。 您呼叫的端點取決於函式的類型。

注意

本主題中的範例使用 cURL 工具,從終端機或命令提示字元傳送 HTTP 要求。 您可以使用您選擇的工具,將 HTTP 要求傳送至本機伺服器。 在以 Linux 為基礎的系統及 Windows 10 組建 17063 和更新版本上,預設有 cURL 工具可用。 在舊版 Windows 上,您必須先下載並安裝 cURL 工具

如需測試函式的更多一般資訊,請參閱在 Azure Functions 中測試程式碼的策略

HTTP 和 Webhook 觸發的函式

您要呼叫下列端點,以在本機執行 HTTP 和 Webhook 觸發的函式:

http://localhost:{port}/api/{function_name}

請務必使用 Functions 主機接聽的相同伺服器名稱和連接埠。 啟動 Function 主機時,您會在產生的輸出中看到下列內容。 您可以使用觸發程序支援的任何 HTTP 方法呼叫此 URL。

下列 cURL 命令從 GET 要求在查詢字串中傳遞 name 參數,觸發 MyHttpTrigger 快速入門函式。

curl --get http://localhost:7071/api/MyHttpTrigger?name=Azure%20Rocks

下列範例與從 POST 要求在要求本文中傳遞 name 所呼叫的函式相同:

curl --request POST http://localhost:7071/api/MyHttpTrigger --data '{"name":"Azure Rocks"}'

您可以從瀏覽器在查詢字串中傳遞資料來進行 GET 要求。 至於其他所有 HTTP 方法,您必須使用 cURL、Fiddler、Postman 或支援 POST 要求的類似 HTTP 測試工具。

非 HTTP 觸發函式

針對 HTTP 和事件方格觸發程序以外的所有函式,您可以呼叫名為「管理端點」的特殊端點,在本機使用 REST 來測試函式。 在本機伺服器上使用 HTTP POST 要求來呼叫此端點會觸發函式。

若要在本機測試事件方格觸發的函式,請參閱使用檢視器 Web 應用程式進行本機測試

您可以在 POST 要求本文中選擇性地傳遞測試資料到執行程序。 這項功能類似於 Azure 入口網站中的 [測試] 索引標籤。

您可以呼叫下列系統管理員端點來觸發非 HTTP 函式:

http://localhost:{port}/admin/functions/{function_name}

若要將測試資料傳遞至函式的管理員端點,您必須在 POST 要求訊息的本文中提供資料。 訊息本文必須具備下列 JSON 格式:

{
    "input": "<trigger_input>"
}

<trigger_input> 值包含函式預期格式的資料。 下列 cURL 範例是 POST 到 QueueTriggerJS 函式。 在此情況下,輸入是一個相當於在佇列中預期找到的訊息字串。

curl --request POST -H "Content-Type:application/json" --data '{"input":"sample queue data"}' http://localhost:7071/admin/functions/QueueTrigger

當您在 Azure 中的函數應用程式上呼叫管理員端點時,您必須提供存取金鑰。 若要深入了解,請參閱函式存取金鑰

發佈至 Azure

Azure Functions Core Tools 支援兩種部署:

部署類型 Command 描述
專案檔 func azure functionapp publish 使用 zip 部署,直接將函式專案檔部署至函數應用程式。
Kubernetes 叢集 func kubernetes deploy 將 Linux 函數應用程式當作自訂 Docker 容器來部署至 Kubernetes 叢集。

發佈之前

重要

您必須在本機安裝 Azure CLIAzure PowerShell,才能從 Core Tools 發佈至 Azure。

專案資料夾可能包含不應該發佈的語言特定檔案和目錄。 排除的項目列在專案根資料夾的 .funcignore 檔案中。

您必須已在 Azure 訂用帳戶中建立函數應用程式,準備在其中部署您的程式碼。 應建置需要編譯的專案,以便部署二進位檔。

若要了解如何使用 Azure CLI 或 Azure PowerShell,從命令提示字元或終端機視窗建立函數應用程式,請參閱建立無伺服器也可執行的函數應用程式

重要

當您在 Azure 入口網站中建立函數應用程式時,預設使用 3.x 版的函式執行階段。 若要讓函式應用程式使用 1.x 版的執行階段,請依照在 1.x 版上執行中的指示操作。 若函式應用程式具有現有的函式,您就無法變更其執行階段版本。

部署專案檔

若要將您的本機程式碼發佈至 Azure 中的函式應用程式,請使用 publish 命令:

func azure functionapp publish <FunctionAppName>

這種部署有下列考量:

  • 發佈會覆寫函數應用程式中現有的檔案。

  • 使用 --publish-local-settings 選項,以根據 local.settings.json 檔案中的值,在函數應用程式中自動建立應用程式設定。

  • 在編譯的專案上會執行遠端組建。 這可透過 --no-build 選項來控制。

  • 部署的專案可從部署套件執行。 若要停用此建議的部署模式,請使用--nozip 選項

  • JAVA 使用 Maven 將本機專案發佈至 Azure。 請改用下列命令來發佈至 Azure:mvn azure-functions:deploy。 初始部署期間會建立 Azure 資源。

  • 如果您嘗試發佈至訂用帳戶中不存在的 <FunctionAppName>,則會發生錯誤。

Kubernetes 叢集

Azure Functions 也可讓您將 Azure Functions 專案定義為在 Docker 容器中執行。 使用 func init--docker 選項,針對您的特定語言產生 Dockerfile。 建立要部署的容器時會用到此檔案。 若要了解如何在沒有 Kubernetes 的情況下將自訂容器發佈至 Azure,請參閱使用自訂容器在 Linux 上建立函式

Core Tools 可將專案當作自訂容器映像來部署至 Kubernetes 叢集。

下列命令使用 Dockerfile 來產生容器,並部署至 Kubernetes 叢集。

func kubernetes deploy --name <DEPLOYMENT_NAME> --registry <REGISTRY_USERNAME> 

若要深入了解,請參閱將函數應用程式部署至 Kubernetes

安裝擴充功能

如果您無法使用延伸模組套件組合,那麼您可以在本機使用 Azure Functions Core Tools 來安裝專案所需的特定延伸模組套件。

重要

您無法在已啟用延伸模組套件組合的函式應用程式中明確安裝延伸模組。 首先,請先移除 host.json 中的 extensionBundle 區段,再明確地安裝延伸模組。

下列項目描述了您可能需要手動安裝延伸模組的某些原因:

  • 您必須存取套件組合中沒有的特定延伸模組版本。
  • 您必須存取套件組合中沒有的自訂延伸模組。
  • 您必須存取單一套件組合中沒有的特定延伸模組組合。

當您明確安裝延伸模組時,名為 extensions.csproj 的 .NET 專案檔會新增至您專案的根目錄。 此檔案會定義函式所需的 NuGet 套件集合。 雖然您可以使用此檔案中的 NuGet 套件參考,但 Core Tools 可讓您安裝延伸模組,而不需要手動編輯此 C# 專案檔。

有數種方式來使用 Core Tools 在您的本機專案中安裝必要的延伸模組。

安裝所有延伸模組

使用下列命令,以此自動新增本機專案中繫結所使用的所有延伸模組套件:

func extensions install

此命令會讀取 function.json 檔案,查看您需要哪些套件,加以安裝,然後重建擴充專案 (extensions.csproj)。 它會在目前版本中新增任何新繫結,但不會更新現有的繫結。 在安裝新的繫結時,使用 --force 選項將現有繫結更新為最新版本。 若要深入了解,請參閱 func extensions install 命令

如果您的函式應用程式使用 Core Tools 無法辨識的繫結或 NuGet 套件,那麼您必須手動安裝特定的延伸模組。

安裝特定延伸模組

使用下列命令在特定版本安裝特定延伸模組套件,在此案例中為儲存體延伸模組:

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 5.0.0

您可以使用此命令來安裝任何相容的 NuGet 套件。 若要深入了解,請參閱 func extensions install 命令

監視函式

建議與 Azure Application Insights 整合,以監視函式的執行情形。 您也可以將執行記錄串流至本機電腦。 若要深入了解,請參閱監視 Azure Functions

Application Insights 整合

在 Azure 中建立函數應用程式時,應該啟用 Application Insights 整合。 如果函數應用程式因故未連線至 Application Insights 執行個體,在 Azure 入口網站中執行此整合很簡單。 若要深入了解,請參閱啟用 Application Insights 整合

啟用串流記錄

您可以在本機電腦上的命令列工作階段中,檢視函式產生的記錄檔串流。

內建記錄資料流

使用 func azure functionapp logstream 命令,以開始接收 Azure 中執行的特定函數應用程式的串流記錄,如下列範例所示:

func azure functionapp logstream <FunctionAppName>

注意

在 Core Tools 中,尚未針對取用方案中在 Linux 上執行的函式應用程式啟用內建記錄串流。 針對這些主控方案,您必須改為使用即時計量資料流,以近乎即時的方式檢視記錄。

即時計量串流

您可藉由包含 --browser 選項,在新的瀏覽器視窗中檢視函式應用程式的即時計量資料流,如下列範例所示:

func azure functionapp logstream <FunctionAppName> --browser

函數應用程式需要啟用 Application Insights 整合,才會有這種串流記錄。

後續步驟

了解如何使用 Azure Functions 核心工具來開發、測試及發佈 Azure 函數。 Azure Functions Core Tools 是開放原始碼且裝載於 GitHub 上。 若要提出錯誤或功能要求,請開啟 GitHub 問題