使用 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 有四个版本。 使用的版本取决于本地开发环境、所选的语言以及所需的支持级别。

选择以下版本选项卡来了解每个特定版本和详细的安装说明:

支持 4.x 版的 Functions 运行时。 此版本支持 Windows、macOS 和 Linux,并使用特定于平台的包管理器或 npm 进行安装。 这是建议的 Functions 运行时和 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 项目

不管语言如何,Functions 项目目录都包含以下文件和文件夹:

文件名 说明
host.json 有关详细信息,请参阅 host.json 参考
local.settings.json Core Tools 在本地运行时使用的设置,包括应用设置。 有关详细信息,请参阅本地设置
.gitignore 防止意外将 local.settings.json 文件发布到 Git 存储库。 有关详细信息,请参阅本地设置
.vscode\extensions.json 在 Visual Studio Code 中打开项目文件夹时使用的设置文件。

若要详细了解 Functions 项目文件夹,请参阅 Azure Functions 开发人员指南

在终端窗口中或者在命令提示符下,运行以下命令创建项目和本地 Git 存储库:

func init MyFunctionProj

此示例在新的 MyFunctionProj 文件夹中创建一个 Functions 项目。 系统会提示你为项目选择默认语言。

以下注意事项适用于项目初始化:

  • 如果未在命令中提供 --worker-runtime 选项,则系统会提示你选择语言。 有关详细信息,请参阅 func init 参考

  • 如果未提供项目名称,则会初始化当前文件夹。

  • 如果你打算将项目发布到自定义 Linux 容器,请使用 --docker 选项来确保为项目生成 Dockerfile。 有关详细信息,请参阅在 Linux 上使用自定义映像创建函数

对于某些语言,可能还要注意其他一些事项:

  • 默认情况下,Core Tools 2.x 及更高版本会为 .NET 运行时创建函数应用项目作为 C# 类项目 (.csproj)。 版本 3.x 还支持创建可在 .NET 5.0 上的隔离进程中运行的函数。 在调试期间以及发布到 Azure 时,将会编译这些可在 Visual Studio 或 Visual Studio Code 中使用的 C# 项目。

  • 如果要在本地处理 C# 脚本 (.csx) 文件,请使用 --csx 参数。 在 Azure 门户中创建函数时以及在使用 Core Tools 版本 1.x 时,也会获得这些文件。 有关详细信息,请参阅 func init 参考

注册扩展

从运行时版本 2.x 开始,Functions 触发器和绑定作为 .NET 扩展 (NuGet) 包实现。 对于已编译的 C# 项目,只需引用所用的特定触发器和绑定的 NuGet 扩展包即可。 HTTP 绑定和计时器触发器不需要扩展。

为了改进非 C# 项目的开发体验,Functions 允许在 host.json 项目文件中引用版本受控的扩展捆绑包。 扩展捆绑包使得所有扩展可供应用使用,并消除了扩展之间出现包兼容性问题的可能性。 扩展捆绑包还消除了安装 .NET Core 3.1 SDK 以及处理 extensions.csproj 文件的要求。

对于除 C# 已编译项目和 C# 脚本以外的其他 Functions 项目,建议使用扩展捆绑包。 对于这些项目,在初始化期间将在 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 中指定连接字符串。

获取存储连接字符串

即使在使用 Azure 存储模拟器进行开发时,也可能需要在本地使用实际的存储连接来运行。 假设已创建了存储帐户,则可以通过多种方式之一获取有效的存储连接字符串:

  1. Azure 门户中,搜索并选择“存储帐户”。

    Select Storage accounts from Azure portal

  2. 选择你的存储帐户,在“设置”中选择“访问密钥”,然后复制其中一个连接字符串值。

    Copy connection string from Azure portal

创建函数

若要在现有项目中创建函数,请运行以下命令:

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 "Queue Trigger" --name MyQueueTrigger

有关详细信息,请参阅 func new 命令

在本地运行函数

若要运行 Functions 项目,请从项目的根目录运行 Functions 主机。 主机会为项目中的所有函数启用触发器。 start 命令因项目语言而异。

func start

注意

Functions 运行时的 1.x 版改为需要 func host start。 有关详细信息,请参阅 Azure Functions Core Tools 参考

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 绑定一文。

将测试数据传递给函数

若要在本地测试函数,请启动 Functions 主机,并在本地服务器上使用 HTTP 请求调用终结点。 你调用的终结点要取决于函数的类型。

注意

本主题中的示例使用 cURL 工具从终端或命令提示符发送 HTTP 请求。 你可以使用所选的工具将 HTTP 请求发送到本地服务器。 默认情况下,cURL 工具在基于 Linux 的系统和 Windows 10 内部版本 17063 及更高版本上可用。 在较旧的 Windows 上,必须先下载并安装 cURL 工具

有关测试函数的更多常规信息,请参阅在 Azure Functions 中测试代码的策略

HTTP 和 webhook 触发的函数

调用以下终结点,以在本地运行 HTTP 和 webhook 触发的函数:

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

请确保使用相同的服务器名称和 Functions 主机正在侦听的端口。 在启动 Function 主机时所生成的输出中可以看到该信息。 可以使用触发器所支持的任何 HTTP 方法来调用此 URL。

以下 cURL 命令使用查询字符串中传递的 name 参数从 GET 请求触发 MyHttpTrigger quickstart 函数。

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

下面的示例是在请求主体中传递 name 的 POST 请求中调用的相同函数:

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 示例是指向 QueueTriggerJS 函数的 POST。 在这种情况下,输入是一个字符串,等同于期望在队列中找到的消息。

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 群集

Functions 还允许将 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 Core Tools 开发、测试和发布 Azure Functions Microsoft 学习模块 Azure Functions Core Tools 是开源工具,托管在 GitHub 上
若要提交 bug 或功能请求,请打开 GitHub 问题