共用方式為


使用 Core Tools 在本機開發 Azure Functions

Azure Functions Core Tools 可讓您在本機電腦上開發及測試函式。 當您準備好時,也可以使用 Core Tools 將程式碼專案部署至 Azure,並使用應用程式設定。

您正在檢視本文的 C# 版本。 請務必在文章頂端選取您慣用的 Functions 程式設計語言。

如果您想要立即開始使用,請完成 Core Tools 快速入門文章

您正在檢視本文的 Java 版本。 請務必在文章頂端選取您慣用的 Functions 程式設計語言。

如果您想要立即開始使用,請完成 Core Tools 快速入門文章

您正在檢視本文的 JavaScript 版本。 請務必在文章頂端選取您慣用的 Functions 程式設計語言。

如果您想要立即開始使用,請完成 Core Tools 快速入門文章

您正在檢視本文的 PowerShell 版本。 請務必在文章頂端選取您慣用的 Functions 程式設計語言。

如果您想要立即開始使用,請完成 Core Tools 快速入門文章

您正在檢視本文的 Python 版本。 請務必在文章頂端選取您慣用的 Functions 程式設計語言。

如果您想要立即開始使用,請完成 Core Tools 快速入門文章

您正在檢視本文的 TypeScript 版本。 請務必在文章頂端選取您慣用的 Functions 程式設計語言。

如果您想要立即開始使用,請完成 Core Tools 快速入門文章

安裝 Azure Functions Core Tools

安裝 Core Tools 的建議方式取決於本機開發電腦的作業系統。

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

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

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

如需版本相關問題的說明,請參閱 Core Tools 版本

建立本機專案

重要

若為 Python,您必須在虛擬環境中執行 Core Tools 命令。 如需詳細資訊,請參閱快速入門:從命令列在 Azure 中建立 Python 函式

在終端機視窗中或從命令提示字元執行下列命令,以在 MyProjFolder 資料夾中建立專案:

func init MyProjFolder --worker-runtime dotnet-isolated 

根據預設,此命令會建立一個專案,這個專案會在目前的 .NET Core 長期支援 (LTS) 版本上,使用 Functions 主機執行內含式。 您可以使用 --target-framework 選項,以特定的 .NET 支援版本為目標,包括 .NET Framework。 如需詳細資訊,請參閱 func init 參考。

如需這兩個 .NET 處理序模型的比較,請參閱處理序模式比較一文

Java 會使用 Maven 原型來建立本機專案,以及您的第一個由 HTTP 觸發的函式。 請不要使用 func initfunc new,而是改為遵循命令列快速入門中的步驟。

func init MyProjFolder --worker-runtime javascript --model V4

此命令會建立使用所需程式設計模型版本的 JavaScript 專案。

func init MyProjFolder --worker-runtime typescript --model V4

此命令會建立使用所需程式設計模型版本的 TypeScript 專案。

func init MyProjFolder --worker-runtime powershell
func init MyProjFolder --worker-runtime python --model V2

此命令會建立使用所需程式設計模型版本的 Python 專案。

當您在沒有使用 --worker-runtime 選項的情況下執行 func init 時,系統會提示您選擇專案語言。 若要深入了解 func init 命令的可用選項,請參閱 func init 參考。

建立函式

若要將函式新增至專案,請使用 --template 選項執行 func new 命令來選取觸發程序範本。 下列範例會建立名為 MyHttpTrigger 的 HTTP 觸發程序:

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

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

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

下列考量適用於新增函式的情況:

  • 當您在沒有使用 --template 選項的情況下執行 func new 時,系統會提示您選擇範本。

  • 使用 func templates list 命令,以針對您的語言查看可用範本的完整清單。

  • 當您新增會連線至某個服務的觸發程序時,您也需要將會參考連接字串或受控識別的應用程式設定新增至 local.settings.json 檔案。 以這種方式使用應用程式設定可讓您不必在程式碼中內嵌認證。 如需詳細資訊,請參閱在本機使用應用程式設定

  • Core Tools 也會將特定繫結延伸模組的參考新增至 C# 專案。

若要深入了解 func new 命令的可用選項,請參閱 func new 參考。

將繫結新增至函式

Functions 會提供一組服務特定的輸入和輸出繫結,這些繫結可讓函式更輕鬆地連線到其他 Azure 服務,而不必使用服務特定的用戶端 SDK。 如需詳細資訊,請參閱 Azure Functions 觸發程序和繫結概念

若要將輸入或輸出繫結新增至現有函式,您必須手動更新函式定義。

下列範例顯示在將佇列儲存體輸出繫結新增至由 HTTP 觸發的函式之後的函式定義:

因為由 HTTP 觸發的函式也會傳回 HTTP 回應,因此函式會傳回 MultiResponse 物件,此物件會同時代表 HTTP 輸出和佇列輸出。

[Function("HttpExample")]
public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequest req,
    FunctionContext executionContext)
{

這個範例是包含輸出繫結的 MultiResponse 物件的定義:

public class MultiResponse
{
    [QueueOutput("outqueue",Connection = "AzureWebJobsStorage")]
    public string[] Messages { get; set; }
    public IActionResult HttpResponse { get; set; }
}

將該範例套用至您自己的專案時,視乎於您是否使用 ASP.NET Core 整合而定,您可能需要將 HttpRequest 變更為 HttpRequestData,以及將 IActionResult 變更為 HttpResponseData

訊息會在函式完成時傳送至佇列。 輸出繫結的定義方式取決於流程模型。 如需詳細資訊,包括您可以參考的範例繫結程式碼之連結,請參閱 將繫結新增至函式

@FunctionName("HttpExample")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) 
        HttpRequestMessage<Optional<String>> request, 
        @QueueOutput(name = "msg", queueName = "outqueue", 
        connection = "AzureWebJobsStorage") OutputBinding<String> msg, 
        final ExecutionContext context) {

如需詳細資訊,包括您可以參考的範例繫結程式碼之連結,請參閱 將繫結新增至函式

尚未提供 Node.js 模型 v4 的範例繫結。

輸出繫結的定義方式取決於 Node.js 模型的版本。 如需詳細資訊,包括您可以參考的範例繫結程式碼之連結,請參閱 將繫結新增至函式

$outputMsg = $name
Push-OutputBinding -name msg -Value $outputMsg

如需詳細資訊,包括您可以參考的範例繫結程式碼之連結,請參閱 將繫結新增至函式

@app.route(route="HttpExample")
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
def HttpExample(req: func.HttpRequest, msg: func.Out [func.QueueMessage]) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

輸出繫結的定義方式取決於您 Python 模型的版本。 如需詳細資訊,包括您可以參考的範例繫結程式碼之連結,請參閱 將繫結新增至函式

尚未提供 Node.js 模型 v4 的範例繫結。

輸出繫結的定義方式取決於 Node.js 模型的版本。 如需詳細資訊,包括您可以參考的範例繫結程式碼連結,請參閱將繫結新增至函式

下列考量適用於將繫結新增至函式的情況:

  • 對於使用 function.json 組態檔來定義函式的語言,Visual Studio Code 可簡化將繫結新增至現有函式定義的程序。 如需詳細資訊,請參閱使用繫結將函式連線到 Azure 服務
  • 當您新增會連線至某個服務的繫結時,您也必須將會參考連接字串或受控識別的應用程式設定新增至 local.settings.json 檔案。 如需詳細資訊,請參閱在本機使用應用程式設定
  • 當您新增支援的繫結時,若應用程式使用延伸模組套件組合,則延伸模組應該已安裝好。 如需詳細資訊,請參閱延伸模組套件組合
  • 當您新增需要新繫結延伸模組的繫結時,您也必須在 C# 專案中新增該特定繫結延伸模組的參考。

如需詳細資訊,包括您可以參考的範例繫結程式碼連結,請參閱將繫結新增至函式

如需詳細資訊,包括您可以參考的範例繫結程式碼連結,請參閱將繫結新增至函式

如需詳細資訊,包括您可以參考的範例繫結程式碼連結,請參閱將繫結新增至函式

如需詳細資訊,包括您可以參考的範例繫結程式碼連結,請參閱將繫結新增至函式

如需詳細資訊,包括您可以參考的範例繫結程式碼連結,請參閱將繫結新增至函式

如需詳細資訊,包括您可以參考的範例繫結程式碼連結,請參閱將繫結新增至函式

啟動 Functions 執行階段

您必須先從專案的根目錄啟動 Functions 主機,才能執行或偵錯專案中的函式。 此主機對專案中的所有函式啟用觸發程序。 請使用此命令啟動本機執行階段:

mvn clean package 
mvn azure-functions:run
func start
npm install
npm start     

此命令必須在虛擬環境中執行

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" 處理。 如需詳細資訊,請參閱授權層級。 您可以使用 --enableAuth 選項,以在本機執行時要求授權。 如需詳細資訊,請參閱 func start

  • 在本機執行需要存取 Azure 儲存體服務 (佇列儲存體、Blob 儲存體和表格儲存體) 的函式時,您可以使用本機 Azurite 模擬器,而不必連線到 Azure 中的這些服務。 使用本機模擬時,請務必先啟動 Azurite,再啟動本機主機 (func.exe)。 如需詳細資訊,請參閱本機儲存體模擬

  • 您可以使用本機 Azurite 模擬來符合 Python v2 背景工作角色的儲存體需求。
  • 您可以在本機觸發非 HTTP 函式,而不必連線到即時服務。 如需詳細資訊,請參閱執行本機函式

  • 當您在 local.settings.json 檔案中包含 Application Insights 連線資訊時,本機的記錄資料會寫入到特定的 Application Insights 執行個體。 若要將本機遙測資料與生產資料分開存放,請考慮使用個別的 Application Insights 執行個體來進行開發和測試。

  • 使用 Core Tools 1.x 版時,請改用 func host start 命令來啟動本機執行階段。

執行本機函式

在本機 Functions 主機 (func.exe) 執行時,您現在可以觸發個別函式以執行和偵錯函式程式碼。 個別函式的執行方式取決於其觸發程序類型。

注意

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

透過將 HTTP 要求傳送至本機端點和連接埠即可啟動 HTTP 觸發程序,如 func.exe 輸出所示,其具有如下的一般格式:

http://localhost:<PORT>/api/<FUNCTION_NAME>

在此 URL 範本中,<FUNCTION_NAME> 是函式或路由的名稱,<PORT> 則是 func.exe 所接聽的本機連接埠。

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

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

下列範例與從 POST 要求在要求本文中傳遞 name 所呼叫的函式相同 (針對 Bash 殼層和 Windows 命令列所顯示):

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

下列考量適用於在本機呼叫 HTTP 端點的情況:

  • 您可以從瀏覽器在查詢字串中傳遞資料來進行 GET 要求。 對於所有其他 HTTP 方法,您必須使用同時確保資料安全的 HTTP 測試工具。 如需詳細資訊,請參閱 HTTP 測試工具

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

發佈至 Azure

Azure Functions Core Tools 支援三種部署:

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

您必須在本機安裝 Azure CLIAzure PowerShell,才能從 Core Tools 發佈至 Azure。 根據預設,Core Tools 會使用這些工具向 Azure 帳戶進行驗證。

如果您沒有安裝這些工具,則必須改為取得有效的存取權杖以在部署期間使用。 您可以在部署命令中使用 --access-token 選項來出示存取權杖。

部署專案檔

若要將本機程式碼發佈至 Azure 中的函式應用程式,請使用 func azure functionapp publish 命令,如下列範例所示:

func azure functionapp publish <FunctionAppName>

此命令會將專案檔以 .zip 部署套件的形式,從目前的目錄發佈至 <FunctionAppName>。 如果專案需要編譯,則會在部署期間從遠端完成。

Java 會使用 Maven 將本機專案發佈至 Azure,而不是使用 Core Tools。 請使用下列 Maven 命令將專案發佈至 Azure:

mvn azure-functions:deploy

當您執行此命令時,系統會在初始部署期間,根據 pom.xml 檔案中的設定來建立 Azure 資源。 如需詳細資訊,請參閱將函式專案部署至 Azure

這種部署有下列考量:

部署容器

Core Tools 可讓您將容器化的函式應用程式部署至受控 Azure 容器應用程式環境和您所管理的 Kubernetes 叢集。

請使用下列 func azurecontainerapps deploy 命令將現有的容器映像部署至容器應用程式環境:

func azurecontainerapps deploy --name <APP_NAME> --environment <ENVIRONMENT_NAME> --storage-account <STORAGE_CONNECTION> --resource-group <RESOURCE_GROUP> --image-name <IMAGE_NAME> [--registry-password] [--registry-server] [--registry-username]

當您部署至 Azure 容器應用程式環境時,會適用下列考量:

  • 環境和儲存體帳戶必須已經存在。 所部署的函式應用程式會使用您提供的儲存體帳戶連接字串。

  • 在部署至容器應用程式時,不需要建立個別的函式應用程式資源。

  • 儲存體連接字串和其他服務認證是重要的秘密。 請務必使用 func azurecontainerapps deploy 安全地儲存任何指令檔,不要將其儲存在任何可公開存取的原始檔控制系統中。 您可以加密 local.settings.json 檔案,以增加安全性。

如需詳細資訊,請參閱 Azure Functions 的 Azure 容器應用程式裝載

在本機使用應用程式設定

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

專案 local.settings.json 檔案中 Values 集合中的項目,是用來反映在 Azure 中鏡像函式應用程式應用程式設定中的項目。

下列考量適用於使用本機設定檔案的情況:

  • 因為 local.settings.json 可能包含秘密,例如連接字串,請勿儲存在遠端存放庫。 Core Tools 可協助您加密此本機設定檔案,以提升安全性。 如需詳細資訊,請參閱本機設定檔。 您也可以加密 local.settings.json 檔案,以增加安全性。

  • 根據預設,在專案發佈至 Azure 時,本機設定不會自動移轉。 在發佈專案檔時使用 --publish-local-settings 選項,以確保這些設定會新增至 Azure 中的函式應用程式。 絕不會發佈 ConnectionStrings 區段中的值。 您也可以隨時從 local.settings.json 檔案上傳設定

  • 您可以從您在 Azure 中的函式應用程式下載設定,並以此覆寫您 local.settings.json 檔案中的設定。 如需詳細資訊,請參閱下載應用程式設定

  • 這些函數應用程式設定值在您的程式碼中也可以做為環境變數加以讀取。 如需詳細資訊,請參閱環境變數
  • 這些函數應用程式設定值在您的程式碼中也可以做為環境變數加以讀取。 如需詳細資訊,請參閱環境變數
  • 這些函數應用程式設定值在您的程式碼中也可以做為環境變數加以讀取。 如需詳細資訊,請參閱環境變數
  • 這些函數應用程式設定值在您的程式碼中也可以做為環境變數加以讀取。 如需詳細資訊,請參閱環境變數
  • 這些函數應用程式設定值在您的程式碼中也可以做為環境變數加以讀取。 如需詳細資訊,請參閱環境變數

下載應用程式設定

從專案根目錄中,使用下列命令從 Azure 中的 myfunctionapp12345 應用程式下載所有應用程式設定:

func azure functionapp fetch-app-settings myfunctionapp12345

此命令會以來自 Azure 的值覆寫 local.settings.json 檔案中的任何現有設定。 如果還沒有,則會在集合中新增新的項目。 如需詳細資訊,請參閱 func azure functionapp fetch-app-settings 命令。

下載儲存體連接字串

Core Tools 也可讓您輕鬆地取得您有權存取之任何儲存體帳戶的連接字串。 從專案根目錄中,使用下列命令從名為 mystorage12345 的儲存體帳戶中下載連接字串。

func azure storage fetch-connection-string mystorage12345

此命令會將名為 mystorage12345_STORAGE 的設定新增至 local.settings.json 檔案,其中包含 mystorage12345 帳戶的連接字串。 如需詳細資訊,請參閱 func azure storage fetch-connection-string 命令。

若要提升開發期間的安全性,請考慮加密 local.settings.json 檔案

將本機設定上傳至 Azure

當您在不使用 --publish-local-settings 選項的情況下將專案檔發佈至 Azure 時,函式應用程式中不會設定 local.settings.json 檔案中的設定。 您一律可以使用 --publish-settings-only 選項重新執行 func azure functionapp publish,只上傳設定而不重新發佈專案檔。

下列範例只會將 local.settings.json 檔案中 Values 集合內的設定上傳至 Azure 中名為 myfunctionapp12345 的函式應用程式:

func azure functionapp publish myfunctionapp12345 --publish-settings-only

加密本機設定檔案

為了提升本機設定中連接字串和其他重要資料的安全性,Core Tools 可讓您加密 local.settings.json 檔案。 當此檔案加密時,執行階段會在需要時自動將設定解密,就和 Azure 中的應用程式設定的情況一樣。 您也可以將本機加密的檔案解密,以使用設定。

請使用下列命令來加密專案的本機設定檔:

func settings encrypt

請使用下列命令來解密已加密的本機設定,以便使用該設定:

func settings decrypt

設定檔案加密和解密時,檔案的 IsEncrypted 設定會隨之更新。

設定繫結延伸模組

Functions 觸發程序和繫結會實作為 .NET 延伸模組 (NuGet) 套件。 若要能夠使用特定的繫結延伸模組,就必須將該延伸模組安裝在專案中。

本節不適用於 Functions 執行階段 1.x 版。 在 1.x 版中,核心產品延伸模組中已包含支援的繫結。

若為 C# 類別庫專案,請為函式所需的繫結延伸模組新增特定 NuGet 套件的參考。 C# 指令碼 (.csx) 專案必須使用延伸模組套件組合

Functions 會提供延伸模組套件組合,以讓您輕鬆地在專案中使用繫結延伸模組。 會在 host.json 檔案中設定版本和進行定義的延伸模組套件組合,會為應用程式安裝一組完整的相容繫結延伸模組套件。 您的 host.json 應該已啟用延伸模組套件組合。 如果基於某些原因,您需要在 host.json 檔案中新增或更新延伸模組套件組合,請參閱延伸模組套件組合

如果您必須使用繫結延伸模組,或使用不受支援的套件組合中的延伸模組版本,則必須手動安裝延伸模組。 針對這類罕見案例,請參閱 func extensions install 命令。

Core Tools 版本

Azure Functions Core Tools 的主要版本會連結到 Azure Functions 執行階段的特定主要版本。 例如,Core Tools 4.x 版支援 Functions 執行階段 4.x 版。 此版本是 Functions 執行階段和 Core Tools 的建議主要版本。 您可以在 Azure Functions Core Tools 存放庫中確定最新版的 Core Tools。

請執行下列命令來確定目前的 Core Tools 安裝版本:

func --version

除非另外註明,否則本文中的範例適用於 4.x 版。

下列考量適用於 Core Tools 安裝:

  • 任一電腦上只能安裝一個 Core Tools 版本。

  • 在升級至最新版的 Core Tools 時,請使用您用於原始安裝的相同方法來進行升級。 例如,如果您之前是在 Windows 上使用 MSI,則請先解除安裝目前的 MSI,再安裝最新的 MSI。 或者,如果您之前使用的是 npm,則請重新執行 npm install command

  • Core Tools 2.x 和 3.x 版是搭配 Functions 執行階段 2.x 和 3.x 版使用的,這些版本已終止支援。 如需詳細資訊,請參閱 Azure Functions 執行階段版本概觀

  • 使用仍受支援的 Functions 執行階段 1.x 版時,則需要 Core Tools 1.x 版。 此 Core Tools 版本只能在 Windows 本機電腦上執行。 如果您目前在 1.x 版上執行,請考慮立即將應用程式移轉至 4.x 版

下一步

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