你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

使用 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 

默认情况下,此命令会创建一个项目,该项目在当前长期支持 (LTS) 版本的 .NET Core 上通过 Functons 主机在进程内运行。 可以使用 --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; }
}

向你自己的项目应用该示例时,可能需要将 HttpRequest 更改为 HttpRequestData,将 IActionResult 更改为 HttpResponseData,具体取决于你是否使用 ASP.NET Core 集成

函数完成后,这些消息被发送到队列。 定义输出绑定的方式取决于你的流程模型。 有关详细信息,包括你可以参考的示例绑定代码的链接,请参阅向函数添加绑定

@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" 处理。 有关详细信息,请参阅 HTTP 绑定一文。 在本地运行时,可以使用 --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 请求发送到本地服务器。 默认情况下,cURL 工具在基于 Linux 的系统和 Windows 10 内部版本 17063 及更高版本上可用。 在较旧的 Windows 上,必须先下载并安装 cURL 工具

HTTP 触发器是通过向本地终结点和端口发送 HTTP 请求来启动的,如 func.exe 输出中所示,该输出采用以下常规格式:

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

在此 URL 模板中,<FUNCTION_NAME> 是函数或路由的名称,<PORT> 是 func.exe 侦听的本地端口。

例如,此 cURL 命令通过在查询字符串中传递 name 参数的 GET 请求触发了 MyHttpTrigger quickstart 函数:

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

此示例展示的函数与通过在请求正文中传递 name 的 POST 请求调用的函数是同一个,显示了 Bash shell 和 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 方法,必须使用 cURL、Fiddler、Postman 或类似的支持 POST 请求的 HTTP 测试工具。

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

发布到 Azure

Azure Functions Core Tools 支持三种类型的部署:

部署类型 命令 说明
项目文件 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 publish 命令,如下例所示:

func azure functionapp publish <FunctionAppName>

此命令会将当前目录中的项目文件作为 .zip 部署包发布到 <FunctionAppName>。 如果项目需要编译,则会在部署期间远程完成编译。

Java 使用 Maven 将本地项目发布到 Azure 而不是 Core Tools。 使用以下 Maven 命令将项目发布到 Azure:

mvn azure-functions:deploy

运行此命令时,Azure 资源会根据 pom.xml 文件中的设置在初始部署期间创建。 有关详细信息,请参阅将函数项目部署到 Azure

以下注意事项适用于这种部署:

  • 发布将覆盖远程函数应用部署中的现有文件。

  • 必须事先在 Azure 订阅中创建函数应用。 Core Tools 会将项目代码部署到此函数应用资源。 若要了解如何使用 Azure CLI 或 Azure PowerShell 从命令提示符或终端窗口创建函数应用,请参阅为无服务器执行创建函数应用。 还可以在 Azure 门户中创建这些资源。 如果尝试发布到订阅中不存在的 <FunctionAppName>,则会收到错误。

  • 项目文件夹可能包含不应该发布的特定于语言的文件和目录。 排除的项在根项目文件夹的 .funcignore 文件中列出。

  • 默认情况下,项目在部署后将从部署包运行。 若要禁用这种建议的部署模式,请使用 --nozip 选项

  • 将对已编译的项目执行远程生成。 可以使用 --no-build 选项来控制此操作。

  • 使用 --publish-local-settings 选项可以根据 local.settings.json 文件中的值自动在函数应用中创建应用设置。

  • 若要发布到函数应用中的特定命名槽,请使用 --slot 选项

部署容器

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 时,应使用与原始安装相同的方法来执行升级。 例如,如果在 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

使用 Visual Studio Code 时,可以将 Rosetta 与内置终端集成。 有关详细信息,请参阅在 Visual Studio Code 中启用仿真

后续步骤

了解如何使用 Azure Functions 核心工具开发、测试和发布 Azure Functions。 Azure Functions Core Tools 是开源工具且托管在 GitHub 上。 若要提交 bug 或功能请求,请打开 GitHub 问题