在本地对 Azure Functions 进行编码和测试

  • 项目

尽管你可以在 Azure 门户中开发和测试 Azure Functions，但许多开发人员更偏爱本地开发体验。 使用 Functions 时，可更轻松地使用你喜欢的代码编辑器和开发工具在本地计算机上开发和测试函数。 本地函数可以连接到实时 Azure 服务，你可以在本地计算机上使用完整的 Functions 运行时调试函数。

本文提供针对你的首选语言的特定开发环境的链接。 它还将提供一些关于本地开发的共享指南，如使用 local.settings.json 文件。

本地开发环境

在本地计算机开发函数的方式取决于语言和工具偏好。 下表中的环境支持本地开发：

环境 语言 说明
Visual Studio Code C#（进程内）
C# (独立工作进程)
JavaScript
PowerShell
Python		 适用于 VS Code 的 Azure Functions 扩展在 VS Code 中添加了 Functions 支持。 需要 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 开始，Azure Functions 工具包含在 Visual Studio 的 Azure 开发工作负荷中。 可以编译类库中的函数，并将 .dll 文件发布到 Azure。 包含用于本地测试的 Core Tools。 有关详细信息，请参阅使用 Visual Studio 开发 Azure Functions。
Maven（不同的） Java Maven 原型支持 Core Tools 以实现 Java 函数的开发。 版本 2.x 支持 Linux、macOS 和 Windows 上的开发。 有关详细信息，请参阅使用 Java 和 Maven 创建第一个函数。 还支持使用 Eclipse 和 IntelliJ IDEA 进行开发。

注意

不要将本地开发和门户开发混合在同一函数应用中。 从本地项目创建和发布函数时，无法维护或修改门户中的项目代码。

其中每个本地开发环境允许创建函数应用项目，并使用预定义的函数模板创建新函数。 每个环境使用 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 中打开项目文件夹时使用的设置文件。

项目中的其他文件取决于语言和具体函数。 有关详细信息，请参阅相应语言的开发人员指南。

本地设置文件

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。 当本地计算机上的 local.settings.json 文件中包含机密（如服务连接字符串）时，可能需要对其进行加密。 主机在运行时会自动对设置解密。 在尝试读取本地加密设置之前，请使用 func settings decrypt 命令。
Values 在本地运行项目时所使用的一系列应用程序设置。 这些键值 (string-string) 对与 Azure 的函数应用中的应用程序设置相对应，例如 AzureWebJobsStorage。 许多触发器和绑定都有一个引用连接字符串应用设置的属性，例如 Connection的 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 节获取连接字符串的框架使用，例如ConnectionStrings。 此对象中的连接字符串添加到提供者类型为 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 运行时的目标语言。 对于 Functions 运行时版本 2.x 及更高版本来说是必需的。 此设置是 Core Tools 为你的项目生成的。 要了解详细信息，请查看 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。

本地存储仿真器

在本地开发期间，当使用 Azure 存储绑定（队列存储、Blob 存储和表存储）测试函数时，你可以使用本地 Azurite 仿真器，而无需连接到远程存储服务。 Azurite 与 Visual Studio Code 和 Visual Studio 集成，你还可以使用 npm 从命令提示符运行它。 有关详细信息，请参阅使用 Azurite 模拟器进行本地 Azure 存储开发。

local.settings.json 文件的 Values 集合中的以下设置告知本地 Functions 主机使用 Azurite 建立默认 AzureWebJobsStorage 连接：

"AzureWebJobsStorage": "UseDevelopmentStorage=true"

通过此设置值，使用 AzureWebJobsStorage 作为其连接的任何 Azure 存储触发器或绑定在本地运行时都会连接到 Azurite。 在本地执行期间使用存储仿真时，请牢记以下注意事项：

  • 必须安装并运行 Azurite。
  • 在发布到 Azure 之前，应使用与 Azure 服务的实际存储连接进行测试。
  • 发布项目时，请勿将 AzureWebJobsStorage 设置发布为 UseDevelopmentStorage=true。 在 Azure 中，AzureWebJobsStorage 设置必须始终是函数应用使用的存储帐户的连接字符串。 有关详细信息，请参阅 AzureWebJobsStorage。

后续步骤