使用 Azure Functions Core Tools

使用 Azure Functions Core Tools 可以在本地计算机上通过命令提示符或终端开发和测试函数。 本地函数可以连接到实时 Azure 服务,你可以在本地计算机上使用完整的 Functions 运行时调试函数。 甚至可以将函数应用部署到 Azure 订阅。

Important

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

Core Tools 版本

Azure Functions Core Tools 有两个版本。 使用的版本取决于本地开发环境、所选的语言以及所需的支持级别:

  • 1.x 版:支持 1.x 版运行时。 此 Tools 版本仅在 Windows 计算机上受支持,需从 npm 包安装。 借助此版本,可以使用不受官方支持的试验性语言创建函数。 有关详细信息,请参阅 Azure Functions 中支持的语言

  • 2.x 版:支持 2.x 版运行时。 此版本支持 WindowsmacOSLinux。 使用特定于平台的包管理器或 npm 进行安装。

除非另有说明,否则本文中的示例适用于版本 2.x。

安装 Azure Functions Core Tools

Azure Functions Core Tools 包含同一运行时的另一版本,该版本为本地开发计算机上可运行的 Azure Functions 运行时提供支持。 它还提供用于创建函数、连接到 Azure 和部署函数项目的命令。

2.x 版

2.x 版工具使用构建在 .NET Core 之上的 Azure Functions 运行时 2.x。 .NET Core 2.x 支持的所有平台(包括 WindowsmacOSLinux)都支持此版本。 必须先安装 .NET Core 2.x SDK。

Windows

以下步骤使用 npm 在 Windows 上安装 Core Tools。 也可使用 Chocolatey。 有关详细信息,请参阅 Core Tools 自述文件

  1. 安装用于 Windows 的 .NET Core 2.x SDK

  2. 安装 Node.js,其中包括 npm。 对于 2.x 版工具,仅支持 Node.js 8.5 和更高版本。

  3. 安装 Core Tools 包:

    npm install -g azure-functions-core-tools
    

带 Homebrew 的 MacOS

以下步骤使用 Homebrew 在 macOS 上安装 Core Tools。

  1. 安装用于 macOS 的 .NET Core 2.x SDK

  2. 安装 Homebrew(如果尚未安装)。

  3. 安装 Core Tools 包:

    brew tap azure/functions
    brew install azure-functions-core-tools
    

带 APT 的 Linux (Ubuntu/Debian)

以下步骤使用 APT 在 Ubuntu/Debian Linux 发行版上安装 Core Tools。 有关其他 Linux 发行版,请参阅 Core Tools 自述文件

  1. 安装用于 Linux 的 .NET Core 2.x SDK

  2. 将 Microsoft 产品密钥注册为受信任的密钥:

    curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
    sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg
    
  3. 验证你的 Ubuntu 服务器正在运行下表中的合适版本之一。 若要添加 apt 源,请运行:

    sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-ubuntu-$(lsb_release -cs)-prod $(lsb_release -cs) main" > /etc/apt/sources.list.d/dotnetdev.list'
    sudo apt-get update
    
    Linux 分发版 版本
    Ubuntu 18.10 cosmic
    Ubuntu 18.04 bionic
    Ubuntu 17.04 zesty
    Ubuntu 16.04/Linux Mint 18 xenial
  4. 安装 Core Tools 包:

    sudo apt-get install azure-functions-core-tools
    

创建本地 Functions 项目

Functions 项目目录包含文件 host.jsonlocal.settings.json 以及若干个子文件夹,这些子文件夹包含各个函数的代码。 此目录相当于 Azure 中的一个函数应用。 若要详细了解 Functions 文件夹的结构,请参阅 Azure Functions 开发人员指南

版本 2.x 要求在初始化项目时为项目选择默认语言,添加的所有函数使用默认语言模板。 在版本 1.x 中,每次创建函数时都要指定语言。

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

func init MyFunctionProj

提供项目名称后,系统就会创建并初始化使用该名称的新文件夹, 否则会初始化当前文件夹。
在版本 2.x 中运行命令时,必须为项目选择一个运行时。 如果你打算开发 JavaScript 函数,请选择“节点”:

Select a worker runtime:
dotnet
node

使用向上/向下箭头键选择语言,然后按 Enter。 JavaScript 项目的输出如以下示例所示:

Select a worker runtime: node
Writing .gitignore
Writing host.json
Writing local.settings.json
Writing C:\myfunctions\myMyFunctionProj\.vscode\extensions.json
Initialized empty Git repository in C:/myfunctions/myMyFunctionProj/.git/

func init 支持以下选项。除非另有说明,否则这些选项仅限版本 2.x:

选项 说明
--csx 初始化 C# 脚本 (.csx) 项目。 必须在后续命令中指定 --csx
--docker 使用基于所选 --worker-runtime 的基础映像创建容器的 Dockerfile。 如果打算发布到自定义 Linux 容器,请使用此选项。
--force 即使项目中存在现有的文件,也要初始化该项目。 此设置会覆盖同名的现有文件。 项目文件夹中的其他文件不受影响。
--no-source-control -n 阻止版本 1.x 中默认创建 Git 存储库的行为。 在版本 2.x 中,默认不会创建 git 存储库。
--source-control 控制是否创建 git 存储库。 默认不会创建存储库。 如果为 true,则会创建存储库。
--worker-runtime 设置项目的语言运行时。 支持的值为 dotnetnode (JavaScript)、javapython。 如果未设置,则初始化期间系统会提示你选择运行时。

Important

默认情况下,Core Tools 版本 2.x 会为 .NET 运行时创建函数应用项目作为 C# 类项目 (.csproj)。 这些 C# 项目可以与 Visual Studio 或 Visual Studio Code 结合使用,在测试期间以及发布到 Azure 时进行编译。 如果希望创建并使用在版本 1.x 和门户中创建的相同 C# 脚本 (.csx) 文件,则在创建和部署函数时必须包含 --csx 参数。

注册扩展

在版本 2.x 的 Azure Functions 运行时中,必须显式注册在函数应用中使用的绑定扩展(绑定类型)。

在本地开发函数时,可以使用 Azure Functions Core Tools 从终端或从命令提示符安装所需的扩展。

更新 function.json 文件以包含函数所需的所有绑定后,请在项目文件夹中运行以下命令。

func extensions install

该命令读取 function.json 文件以了解所需的程序包,安装这些包并重新生成扩展项目。 它在当前版本中添加任何新绑定,但不更新现有绑定。 使用 --force 选项可在安装新版本时将现有绑定更新为最新版本。

如要安装特定版本的包或要在编辑 function.json 文件之前安装包,请对包名称使用 func extensions install 命令,如下例所示:

func extensions install --package Microsoft.Azure.WebJobs.ServiceBus --version <target_version>

<target_version> 替换为特定包版本,例如 3.0.0-beta5。 在 NuGet.org 上的单个包页上列出了有效版本。

有关详细信息,请参阅 Azure Functions 触发器和绑定概念

本地设置文件

文件 local.settings.json 存储 Azure Functions Core Tools 的应用设置、连接字符串和设置。 只有在本地运行时,Functions工具才使用 local.settings.json 文件中的设置。 默认情况下,将项目发布到 Azure 时,这些设置不会自动迁移。 发布时使用 --publish-local-settings 开关确保已将这些设置添加到 Azure 中的函数应用。 请注意,ConnectionStrings 中的值永远不会发布。 该文件的结构如下:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "<language worker>",
    "AzureWebJobsStorage": "<connection-string>",
    "AzureWebJobsDashboard": "<connection-string>",
    "MyBindingConnection": "<binding-connection-string>"
  },
  "Host": {
    "LocalHttpPort": 7071,
    "CORS": "*"
  },
  "ConnectionStrings": {
    "SQLConnectionString": "<sqlclient-connection-string>"
  }
}
设置 说明
IsEncrypted 设置为 true 时,使用本地计算机密钥加密所有值。 与 func settings 命令配合使用。 默认值为 false
Values 在本地运行时使用的应用程序设置和连接字符串的集合。 这些值对应于 Azure 中你的函数应用中的应用设置,例如 AzureWebJobsStorage。 许多触发器和绑定都有一个引用连接字符串应用设置的属性,例如 Blob 存储触发器Connection。 对于此类属性,你需要一个在 Values 数组中定义的应用程序设置。
对于 HTTP 之外的触发器,AzureWebJobsStorage 是一个必需的应用设置。
2.x 版的 Functions 运行时需要 FUNCTIONS_WORKER_RUNTIME 设置,该设置是由 Core Tools 为项目生成的。
在本地安装 Azure 存储模拟器后,可以将 AzureWebJobsStorage 设置为 UseDevelopmentStorage=true,以便 Core Tools 使用此模拟器。 这在开发期间非常有用,但是在部署之前,应当使用实际的存储连接进行测试。
Host 在本地运行时,本部分中的设置会自定义 Functions 主机进程。
LocalHttpPort 设置运行本地 Functions 主机时使用的默认端口(func host startfunc run)。 --port 命令行选项优先于此值。
CORS 定义跨域资源共享 (CORS)可以使用的来源。 以逗号分隔的列表提供来源,其中不含空格。 支持通配符值 (*),它允许使用任何来源的请求。
ConnectionStrings 不要将此集合用于函数绑定使用的连接字符串。 此集合仅供通常从配置文件的 ConnectionStrings 节获取连接字符串的框架使用,例如实体框架。 此对象中的连接字符串添加到提供者类型为 System.Data.SqlClient 的环境中。 此集合中的项不使用其他应用设置发布到 Azure 中。 必须将这些值显式添加到函数应用设置的 Connection strings 集合中。 如果要在函数代码中创建 SqlConnection,则应将连接字符串值与其他连接一起存储在门户的“应用程序设置”中。

还可以在代码中将函数应用设置值读取为环境变量。 有关详细信息,请参阅以下特定于语言的参考主题的“环境变量”部分:

如果没有为 AzureWebJobsStorage 设置有效的存储连接字符串并且没有使用模拟器,则会显示以下错误消息:

local.settings.json 中的 AzureWebJobsStorage 缺少值。 该值对除 HTTP 以外的所有触发器都是必需的。 可运行“func azure functionapp fetch-app-settings <functionAppName>”或在 local.settings.json 中指定连接字符串。

获取存储连接字符串

即使在使用存储仿真器进行开发时,你也可能希望使用实际的存储连接进行测试。 假设已创建了存储帐户,则可以通过下列方式之一获取有效的存储连接字符串:

  • 通过 Azure 门户。 导航到你的存储帐户,在“设置”中选择“访问密钥”,然后复制其中一个连接字符串值。

    从 Azure 门户复制连接字符串

  • 使用 Azure 存储资源管理器连接到你的 Azure 帐户。 在“资源管理器”中,展开你的订阅,选择你的存储帐户,然后复制主或辅助连接字符串。

    从存储资源管理器复制连接字符串

  • 使用核心工具通过下列命令之一从 Azure 下载连接字符串:

    • 从现有函数应用下载所有设置:

      func azure functionapp fetch-app-settings <FunctionAppName>
      
    • 获取特定存储帐户的连接字符串。

      func azure storage fetch-connection-string <StorageAccountName>
      

      如果你尚未登录到 Azure,系统会要求登录。

创建函数

若要创建函数,请运行以下命令:

func new

在版本 2.x 中运行 func new 时,系统会提示你选择采用函数应用默认语言的模板,另外还会提示你选择函数的名称。 在版本 1.x 中,系统还会提示你选择语言。

Select a language: Select a template:
Blob trigger
Cosmos DB trigger
HTTP trigger
Queue trigger
SendGrid
Service Bus Queue trigger
Service Bus Topic trigger
Timer trigger

函数代码在具有所提供的函数名称的子文件夹中生成,如以下队列触发器输出中所示:

Select a language: Select a template: Queue trigger
Function name: [QueueTriggerJS] MyQueueTrigger
Writing C:\myfunctions\myMyFunctionProj\MyQueueTrigger\index.js
Writing C:\myfunctions\myMyFunctionProj\MyQueueTrigger\readme.md
Writing C:\myfunctions\myMyFunctionProj\MyQueueTrigger\sample.dat
Writing C:\myfunctions\myMyFunctionProj\MyQueueTrigger\function.json

也可以在命令中使用以下参数指定这些选项:

参数 说明
--csx (版本 2.x)生成版本 1.x 和门户所用的相同 C# 脚本 (.csx) 模板。
--language -l C#、F# 或 JavaScript 等模板编程语言。 此选项在版本 1.x 中是必需的。 在版本 2.x 中,请不要使用此选项或选择与辅助角色运行时匹配的语言。
--name -n 函数名称。
--template -t 使用 func templates list 命令查看每种受支持语言的可用模板的完整列表。

例如,若要在单个命令中创建 JavaScript HTTP 触发器,请运行:

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

若要在单个命令中创建队列触发的函数,请运行:

func new --template "Queue Trigger" --name QueueTriggerJS

在本地运行函数

若要运行 Functions 项目,请运行 Functions 主机。 主机为项目中的所有函数启用触发器:

func host start

host 命令仅在版本 1.x 中为必需命令。

func host start 支持以下选项:

选项 说明
--no-build 在运行之前请勿生成当前项目。 仅限于 dotnet 项目。 默认设置为 false。 仅限 2.x 版。
--cert 包含私钥的 .pfx 文件的路径。 只能与 --useHttps 配合使用。 仅限 2.x 版。
--cors-credentials 允许跨域经身份验证的请求(例如 cookies 和身份验证标头),仅限版本 2.x。
--cors 以逗号分隔的 CORS 来源列表,其中不包含空格。
--language-worker 用于配置语言辅助角色的参数。 仅限 2.x 版。
--nodeDebugPort -n 节点调试程序要使用的端口。 默认值:launch.json 中的值或 5858。 仅限 1.x 版。
--password 密码或包含 .pfx 文件密码的文件。 只能与 --cert 配合使用。 仅限 2.x 版。
--port -p 要侦听的本地端口。 默认值:7071。
--pause-on-error 退出进程前,暂停增加其他输入。 仅当从集成开发环境 (IDE) 启动 Core Tools 时才使用。
--script-root --prefix 用于指定要运行或部署的函数应用的根目录路径。 此选项用于可在子文件夹中生成项目文件的已编译项目。 例如,生成 C# 类库项目时,将在某个根子文件夹中生成 host.json、local.settings.json 和 function.json 文件,其路径类似于 MyProject/bin/Debug/netstandard2.0。 在这种情况下,请将前缀设置为 --script-root MyProject/bin/Debug/netstandard2.0。 这是在 Azure 中运行的函数应用的根目录。
--timeout -t Functions 主机启动的超时时间(以秒为单位)。 默认值:20 秒。
--useHttps 绑定到 https://localhost:{port} ,而不是绑定到 http://localhost:{port} 。 默认情况下,此选项会在计算机上创建可信证书。

对于 C# 类库项目 (.csproj),必须包括 --build 选项才能生成库 .dll。

Functions 主机启动时,会输出 HTTP 触发的函数的 URL:

Found the following functions:
Host.Functions.MyHttpTrigger

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

Important

在本地运行时,不会对 HTTP 终结点强制执行身份验证。 这意味着所有本地 HTTP 请求都将作为 authLevel = "anonymous" 处理。 有关详细信息,请参阅 HTTP 绑定一文。

将测试数据传递给函数

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

Note

本主题中的示例使用 cURL 工具从终端或命令提示符发送 HTTP 请求。 你可以使用所选的工具将 HTTP 请求发送到本地服务器。 默认情况下,在基于 Linux 的系统上提供 cURL 工具。 在 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 或类似的 HTTP 测试工具。

非 HTTP 触发的函数

对于 HTTP 触发器和 webhook 以外的所有类型函数,你可以通过调用管理终结点在本地测试函数。 在本地服务器上通过 HTTP POST 请求调用此终结点会触发该函数。 可以选择通过 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/QueueTriggerJS

在版本 1.x 中使用 func run 命令

Important

该工具的 2.x 版本不支持 func run 命令。 有关详细信息,请参阅主题如何指向 Azure Functions 运行时版本

也可以使用 func run <FunctionName> 直接调用函数并为函数提供输入数据。 此命令类似于在 Azure 门户中使用“测试”选项卡运行函数。

func run 支持以下选项:

选项 说明
--content -c 内联内容。
--debug -d 运行函数前,将调试程序附加到主机进程。
--timeout -t 本地 Functions 主机准备就绪前的等待时间(以秒为单位)。
--file -f 要用作内容的文件名。
--no-interactive 不提示输入。 适用于自动化方案。

例如,若要调用 HTTP 触发的函数并传递内容正文,请运行以下命令:

func run MyHttpTrigger -c '{\"name\": \"Azure\"}'

发布到 Azure

Core Tools 支持两种类型的部署:将函数项目文件直接部署到函数应用,以及部署自定义 Linux 容器(仅在版本 2.x 中受支持)。 必须事先在 Azure 订阅中创建函数应用

在版本 2.x 中,发布之前必须在项目中注册扩展。 应该生成需要编译的项目,以便部署二进制文件。

项目文件部署

最常见的部署方法涉及使用 Core Tools 打包函数应用项目、二进制文件和依赖项并将该包部署到函数应用。 可以选择直接从部署包运行函数

若要将 Functions 项目发布到 Azure 中的函数应用,使用 publish 命令:

func azure functionapp publish <FunctionAppName>

此命令发布到 Azure 中的现有函数应用。 如果订阅中不存在 <FunctionAppName>,会发生错误。

publish 命令上传 Functions 项目目录的内容。 如果在本地删除文件,publish 命令不会将文件从 Azure 中删除。 可以使用 Azure 门户中的 Kudu 工具删除 Azure 中的文件。

Important

在 Azure 门户中创建函数应用时,该应用默认使用 2.x 版函数运行时。 若要让函数应用使用 1.x 版运行时,请遵照在版本 1.x 上运行中的说明操作。 无法为包含现有函数的函数应用更改运行时版本。

以下项目发布选项同时适用于 1.x 和 2.x 版本:

选项 说明
--publish-local-settings -i 将 local.settings.json 中的设置发布到 Azure,如果该设置已存在,则提示进行覆盖。 如果在使用存储仿真器,则将应用设置更改为实际的存储连接
--overwrite-settings -y 使用 --publish-local-settings -i 时隐藏覆盖应用设置的提示。

以下项目发布选项仅在版本 2.x 中受支持:

选项 说明
--publish-settings-only -o 仅发布设置,并跳过内容。 默认为提示。
--list-ignored-files 基于 .funcignore 文件显示发布期间忽略的文件列表。
--list-included-files 基于 .funcignore 文件显示发布的文件列表。
--nozip 关闭默认的 Run-From-Zip 模式。
--build-native-deps 发布 python 函数应用时跳过生成 .wheels 文件夹。
--additional-packages 构建本机依赖项时要安装的包列表。 例如:python3-dev libevent-dev
--force 在某些情况下会忽略预发布验证。
--csx 发布 C# 脚本 (.csx) 项目。
--no-build 跳过 dotnet 函数的生成。
--dotnet-cli-params 发布编译的 C# (.csproj) 函数时,Core Tools 将调用“dotnet build --output bin/publish”。 传递到此选项的任何参数将追加到命令行。

自定义容器部署

Functions 允许在自定义 Linux 容器中部署函数项目。 Core Tools 版本 2.x 支持部署自定义容器。 自定义容器必须有一个 Dockerfile。 在 func init 中使用 --dockerfile 选项。

func deploy

可使用以下自定义容器部署选项:

选项 说明
--registry 当前用户登录到的 Docker 注册表的名称。
--platform 函数应用的托管平台。 有效选项为 kubernetes
--name 函数应用名称。
--max (可选)设置要部署到的最大函数应用实例数。
--min (可选)设置要部署到的最小函数应用实例数。
--config 设置可选的部署配置文件。

后续步骤

Azure Functions Core Tools 是开源工具且托管在 GitHub 上
若要提交 bug 或功能请求,请打开 GitHub 问题