Azure Functions 2.x 及更高版本的 host.json 参考
host.json 元数据文件包含影响函数应用实例中所有函数的配置选项。 本文列出了从 Azure Functions 运行时 2.x 版开始可用的设置。
注意
本文适用于 Azure Functions 2.x 及更高版本。 有关 Functions 1.x 中 host.json 的参考，请参阅 Azure Functions 1.x 的 host.json 参考。
其他函数应用程序配置选项根据函数应用的运行位置进行管理：
- 部署到 Azure：在应用程序设置中
- 在本地计算机上：在 local.settings.json 文件中。
host.json 中与绑定相关的配置将同样地应用于函数应用中的每个函数。
还可以使用应用程序设置来按环境覆盖或应用设置。
示例 host.json 文件
以下版本 2.x+ 的示例 host.json 文件指定了所有可能的选项（不包括仅供内部使用的任何选项）。
{
"version": "2.0",
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
},
"concurrency": {
"dynamicConcurrencyEnabled": true,
"snapshotPersistenceEnabled": true
},
"extensions": {
"blobs": {},
"cosmosDb": {},
"durableTask": {},
"eventHubs": {},
"http": {},
"queues": {},
"sendGrid": {},
"serviceBus": {}
},
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.0.0, 5.0.0)"
},
"functions": [ "QueueProcessor", "GitHubWebHook" ],
"functionTimeout": "00:05:00",
"healthMonitor": {
"enabled": true,
"healthCheckInterval": "00:00:10",
"healthCheckWindow": "00:02:00",
"healthCheckThreshold": 6,
"counterThreshold": 0.80
},
"logging": {
"fileLoggingMode": "debugOnly",
"logLevel": {
"Function.MyFunction": "Information",
"default": "None"
},
"applicationInsights": {
"samplingSettings": {
"isEnabled": true,
"maxTelemetryItemsPerSecond" : 20,
"evaluationInterval": "01:00:00",
"initialSamplingPercentage": 100.0,
"samplingPercentageIncreaseTimeout" : "00:00:01",
"samplingPercentageDecreaseTimeout" : "00:00:01",
"minSamplingPercentage": 0.1,
"maxSamplingPercentage": 100.0,
"movingAverageRatio": 1.0,
"excludedTypes" : "Dependency;Event",
"includedTypes" : "PageView;Trace"
},
"dependencyTrackingOptions": {
"enableSqlCommandTextInstrumentation": true
},
"enableLiveMetrics": true,
"enableDependencyTracking": true,
"enablePerformanceCountersCollection": true,
"httpAutoCollectionOptions": {
"enableHttpTriggerExtendedInfoCollection": true,
"enableW3CDistributedTracing": true,
"enableResponseHeaderInjection": true
},
"snapshotConfiguration": {
"agentEndpoint": null,
"captureSnapshotMemoryWeight": 0.5,
"failedRequestLimit": 3,
"handleUntrackedExceptions": true,
"isEnabled": true,
"isEnabledInDeveloperMode": false,
"isEnabledWhenProfiling": true,
"isExceptionSnappointsEnabled": false,
"isLowPrioritySnapshotUploader": true,
"maximumCollectionPlanSize": 50,
"maximumSnapshotsRequired": 3,
"problemCounterResetInterval": "24:00:00",
"provideAnonymousTelemetry": true,
"reconnectInterval": "00:15:00",
"shadowCopyFolder": null,
"shareUploaderProcess": true,
"snapshotInLowPriorityThread": true,
"snapshotsPerDayLimit": 30,
"snapshotsPerTenMinutesLimit": 1,
"tempFolder": null,
"thresholdForSnapshotting": 1,
"uploaderProxy": null
}
}
},
"managedDependency": {
"enabled": true
},
"singleton": {
"lockPeriod": "00:00:15",
"listenerLockPeriod": "00:01:00",
"listenerLockRecoveryPollingInterval": "00:01:00",
"lockAcquisitionTimeout": "00:01:00",
"lockAcquisitionPollingInterval": "00:00:03"
},
"watchDirectories": [ "Shared", "Test" ],
"watchFiles": [ "myFile.txt" ]
}
本文的以下各部分解释了每个顶级属性。 除非另有说明，否则其中的所有属性都是可选的。
aggregator
指定在计算 Application Insights 的指标时要聚合多少个函数调用。
{
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| batchSize | 1000 | 要聚合的最大请求数。 |
| flushTimeout | 00:00:30 | 要聚合的最大时间段。 |
达到两个限制中的第一个限制时，会聚合函数调用。
applicationInsights
此设置是日志记录的子项。
Application Insights 的控制选项，包括采样选项。
若要了解完整的 JSON 结构，请参阅前面的示例 host.json 文件。
注意
日志采样可能会导致一些执行不会显示在 Application Insights 监视器边栏选项卡中。 若要避免日志采样，请将 excludedTypes: "Request" 添加到 samplingSettings 值。
| 属性 | 默认 | 说明 |
|---|---|---|
| samplingSettings | 不适用 | 请参阅 applicationInsights.samplingSettings。 |
| dependencyTrackingOptions | 不适用 | 请参阅 applicationInsights.dependencyTrackingOptions。 |
| enableLiveMetrics | true | 启用实时指标收集。 |
| enableDependencyTracking | true | 自定义依赖项跟踪。 |
| enablePerformanceCountersCollection | true | 启用 Kudu 性能计数器收集。 |
| liveMetricsInitializationDelay | 00:00:15 | 仅限内部使用。 |
| httpAutoCollectionOptions | 不适用 | 请参阅 applicationInsights.httpAutoCollectionOptions。 |
| snapshotConfiguration | 不适用 | 请参阅 applicationInsights.snapshotConfiguration。 |
applicationInsights.samplingSettings
有关这些设置的详细信息，请参阅 Application Insights 中的采样。
| 属性 | 默认 | 说明 |
|---|---|---|
| isEnabled | true | 启用或禁用采样。 |
| maxTelemetryItemsPerSecond | 20 | 每个服务器主机上每秒记录的遥测项的目标数目。 如果应用在多个主机上运行，请将此值降低至总体目标流量率的范围内。 |
| evaluationInterval | 01:00:00 | 会重新评估当前遥测速率的间隔。 评估以移动平均线形式进行执行。 可能想要缩短此间隔（如果遥测很容易就激增）。 |
| initialSamplingPercentage | 100.0 | 采样过程开始时应用的初始采样百分比，以动态改变百分比。 不要在调试时减小值。 |
| samplingPercentageIncreaseTimeout | 00:00:01 | 采样百分比值更改时，此属性确定多久之后允许 Application Insights 再次提升采样百分比以捕获更多数据。 |
| samplingPercentageDecreaseTimeout | 00:00:01 | 采样百分比值更改时，此属性确定多久之后允许 Application Insights 再次降低采样百分比以捕获更少数据。 |
| minSamplingPercentage | 0.1 | 随着采样百分比变化，此属性确定允许的最小采样百分比。 |
| maxSamplingPercentage | 100.0 | 随着采样百分比变化，此属性确定允许的最大采样百分比。 |
| movingAverageRatio | 1.0 | 在移动平均线的计算中，权重分配给最新的值。 使用等于或小于 1 的值。 较小的值会使算法不易受突然的更改影响。 |
| excludedTypes | null | 不要采样的分号分隔类型列表。 承认的类型为：Dependency、Event、Exception、PageView、Request 和 Trace。 指定类型的所有实例都会传输；对未指定的类型进行采样。 |
| includedTypes | null | 要采样的分号分隔类型列表；空列表暗示所有类型。 excludedTypes 中列出的类型替代此处列出的类型。 承认的类型为：Dependency、Event、Exception、PageView、Request 和 Trace。 指定类型的实例都会采样；未指定或未暗示的类型将进行传输而不采样。 |
applicationInsights.httpAutoCollectionOptions
| 属性 | 默认 | 说明 |
|---|---|---|
| enableHttpTriggerExtendedInfoCollection | true | 启用或禁用 HTTP 触发器的扩展 HTTP 请求信息：传入请求关联标头、多检测密钥支持、HTTP 方法、路径及响应。 |
| enableW3CDistributedTracing | true | 启用或禁用对 W3C 分布式跟踪协议的支持（并开启旧版关联架构）。 如果 enableHttpTriggerExtendedInfoCollection 为 true，则默认启用。 如果 enableHttpTriggerExtendedInfoCollection 为 false，则此标志仅适用于传出请求，而不适用于传入请求。 |
| enableResponseHeaderInjection | true | 启用或禁用将多组件关联标头注入响应。 启用注入将在使用多个检测密钥时允许 Application Insights 构造应用程序映射。 如果 enableHttpTriggerExtendedInfoCollection 为 true，则默认启用。 如果 enableHttpTriggerExtendedInfoCollection 为 false，则此设置不适用。 |
applicationInsights.dependencyTrackingOptions
| 属性 | 默认 | 说明 |
|---|---|---|
| enableSqlCommandTextInstrumentation | false | 启用收集 SQL 查询全文的功能，默认情况下禁用该功能。 若要详细了解如何收集 SQL 查询文本，请参阅使用高级 SQL 跟踪获取完整的 SQL 查询。 |
applicationInsights.snapshotConfiguration
有关快照的详细信息，请参阅 .NET 应用中发生异常时调试快照和排查启用 Application Insights Snapshot Debugger 或查看快照时遇到的问题。
| 属性 | 默认 | 说明 |
|---|---|---|
| agentEndpoint | null | 用于连接到 Application Insights Snapshot Debugger 服务的终结点。 如果为 null，则使用默认终结点。 |
| captureSnapshotMemoryWeight | 0.5 | 检查是否有足够内存来拍摄快照时，为当前进程内存大小指定的权重。 预期值为大于 0 的正确分数 (0 < CaptureSnapshotMemoryWeight < 1)。 |
| failedRequestLimit | 3 | 禁用遥测处理器之前请求快照的失败请求数限制。 |
| handleUntrackedExceptions | true | 启用或禁用不由 Application Insights 遥测跟踪的异常跟踪。 |
| isEnabled | true | 启用或禁用快照收集 |
| isEnabledInDeveloperMode | false | 启用或禁用在开发人员模式下启用快照收集。 |
| isEnabledWhenProfiling | true | 启用或禁用快照创建，即使 Application Insights Profiler 正在收集详细的分析会话。 |
| isExceptionSnappointsEnabled | false | 启用或禁用异常筛选。 |
| isLowPrioritySnapshotUploader | true | 确定是否使用低于正常优先级运行 SnapshotUploader 进程。 |
| maximumCollectionPlanSize | 50 | 在任何时候可以跟踪的最大问题数，范围为 1 到 9999。 |
| maximumSnapshotsRequired | 3 | 为单个问题收集的最大快照数，范围为 1 到 999。 应用程序中可将问题视为单个 throw 语句。 为问题收集的快照数达到此值后，将不再为该问题收集更多的快照直到重置问题计数器（请参阅 problemCounterResetInterval）并再次达到 thresholdForSnapshotting 限制。 |
| problemCounterResetInterval | 24:00:00 | 重置问题计数器的频率，范围为一分钟到七天。 达到此间隔时间后，所有问题计数都将重置为零。 已达到拍摄快照的阈值但尚未在 maximumSnapshotsRequired 中生成快照数的现有问题仍处于活动状态。 |
| provideAnonymousTelemetry | true | 确定是否将匿名使用情况和错误的遥测数据发送给 Microsoft。 如果与 Microsoft 联系以通过 Snapshot Debugger 帮助解决问题，则可以使用此遥测数据。 它还用于监视使用模式。 |
| reconnectInterval | 00:15:00 | 重新连接到 Snapshot Debugger 终结点的频率。 允许的范围是一分钟到一天。 |
| shadowCopyFolder | null | 指定用于影子副本二进制文件的文件夹。 如未设置，则按顺序尝试下列环境变量指定的文件夹：Fabric_Folder_App_Temp、LOCALAPPDATA、APPDATA、TEMP。 |
| shareUploaderProcess | true | 如果为 true，则只有一个 SnapshotUploader 实例将为共享 InstrumentationKey 的多个应用收集和上传快照。 如果设为 false，则 SnapshotUploader 对于每个 (ProcessName, InstrumentationKey) 元组都是唯一的。 |
| snapshotInLowPriorityThread | true | 确定是否在低 IO 优先级线程中处理快照。 创建快照是一个快速操作，但为了将快照上传到 Snapshot Debugger 服务，必须首先将其以小型转储的形式写入磁盘。 这在 SnapshotUploader 进程中发生。 如果将此值设为 true，则使用低优先级 IO 来写入小型转储，这不会与应用程序争用资源。 如果将此值设为 false，会加速创建小型转储，同时降低应用程序的运行速度。 |
| snapshotsPerDayLimit | 30 | 一天（24 小时）中允许的最大快照数。 此限制还强制用于 Application Insights 服务端。 上传速率限制为每个应用程序（即每个检测密钥）每天 50 个。 此值有助于阻止创建在上传过程中最终会遭到拒绝的其他快照。 如果此值为零则完全删除限制，不建议这样做。 |
| snapshotsPerTenMinutesLimit | 1 | 10 分钟内允许的最大快照数。 尽管此值没有上限，但由于它可能影响应用程序性能，因此在生产工作负荷中增加它时应谨慎。 创建快照会很快，但创建快照的小型转储并将其上传到 Snapshot Debugger 服务则慢得多，它将与应用程序争用资源（CPU 和 I/O）。 |
| tempFolder | null | 指定用于写入小型转储并上传日志文件的文件夹。 如未设置，则使用 %TEMP%\Dumps。 |
| thresholdForSnapshotting | 1 | Application Insights 请求快照之前需要查看异常的次数。 |
| uploaderProxy | null | 替代 Snapshot Uploader 进程中使用的代理服务器。 如果应用程序通过代理服务器连接到 Internet，则可能需要使用此设置。 Snapshot Collector 在应用程序的进程内运行，并使用相同的代理设置。 但是，Snapshot Uploader 作为单独的进程运行，并且你可能需要手动配置代理服务器。 如果此值为 null，Snapshot Collector 将尝试通过检查 System.Net.WebRequest.DefaultWebProxy 并将值传递到 Snapshot Uploader 来自动检测代理的地址。 如果此值不为 null，则不会使用自动检测，并且将在 Snapshot Uploader 中使用此处指定的代理服务器。 |
Blob
可在存储 Blob 触发器和绑定中查找配置设置。
控制台
此设置是日志记录的子项。 它在未处于调试模式时控制控制台日志记录。
{
"logging": {
...
"console": {
"isEnabled": false,
"DisableColors": true
},
...
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| DisableColors | false | 在 Linux 上禁用容器日志的日志格式设置。 如果在 Linux 上运行时希望在容器日志中看到不需要的 ANSI 控制字符，则设置为 true。 |
| isEnabled | false | 启用或禁用控制台日志记录。 |
Azure Cosmos DB
可在 Azure Cosmos DB 触发器和绑定中查找配置设置。
customHandler
自定义处理程序的配置设置。 有关详细信息，请参阅 Azure Functions 自定义处理程序。
"customHandler": {
"description": {
"defaultExecutablePath": "server",
"workingDirectory": "handler",
"arguments": [ "--port", "%FUNCTIONS_CUSTOMHANDLER_PORT%" ]
},
"enableForwardingHttpRequest": false
}
| 属性 | 默认 | 说明 |
|---|---|---|
| defaultExecutablePath | 不适用 | 要作为自定义处理程序进程启动的可执行文件。 在使用自定义处理程序时，它是必需设置，其值与函数应用根有关。 |
| workingDirectory | 函数应用根 | 要在其中启动自定义处理程序进程的工作目录。 它是一个可选设置，其值与函数应用根有关。 |
| 参数 | 不适用 | 要传递给自定义处理程序进程的命令行参数的数组。 |
| enableForwardingHttpRequest | false | 如果设置，则仅包含 HTTP 触发器和 HTTP 输出的所有函数都将转发原始 HTTP 请求而不是自定义处理程序请求负载。 |
durableTask
可在 Durable Functions 的绑定中查找配置设置。
concurrency
为函数应用中的特定绑定启用动态并发。 有关详细信息，请参阅动态并发。
{
"concurrency": {
"dynamicConcurrencyEnabled": true,
"snapshotPersistenceEnabled": true
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| dynamicConcurrencyEnabled | false | 为此功能（默认处于关闭状态）支持的所有触发器启用动态并发行为。 |
| snapshotPersistenceEnabled | true | 获知的并发值会定期保存到存储中，因此新实例将从这些值而不是从 1 开始，并且必须重新获知并发值。 |
eventHub
可在事件中心触发器和绑定中查找配置设置。
扩展
返回包含所有特定于绑定的设置的对象的属性，例如 http 和 eventHub。
extensionBundle
使用扩展捆绑可将一组兼容的 Functions 绑定扩展添加到函数应用。 若要了解详细信息，请参阅用于本地开发的扩展捆绑。
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[3.3.0, 4.0.0)"
}
}
extensionBundle 中提供了以下属性：
| properties | 说明 |
|---|---|
| id | Azure Functions 扩展捆绑的命名空间。 |
| 版本 | 要安装的捆绑包的版本。 Functions 运行时始终选取由版本范围或间隔定义的可允许最高版本。 上述版本值允许从 3.3.0 到（但不包括）4.0.0 的所有捆绑包版本。 有关详细信息，请参阅用于指定版本范围的间隔表示法。 |
注意
3.x 版扩展捆绑包目前不包含表存储绑定。 目前，如果应用需要表存储，则需继续使用 2.x 版。
functions
作业主机运行的函数列表。 空数组表示运行所有函数。 仅供在本地运行时使用。 在 Azure 的函数应用中，应改为按照如何在 Azure Functions 中禁用函数中的步骤禁用特定函数，而不是使用此设置。
{
"functions": [ "QueueProcessor", "GitHubWebHook" ]
}
functionTimeout
指示所有函数执行的超时持续时间。 它采用 timespan 字符串格式。
| 计划类型 | 默认值（分钟） | 最大值（分钟） |
|---|---|---|
| 消耗 | 5 | 10 |
| 高级1 | 30 | -1（无限制）2 |
| 专用（应用服务） | 30 | -1（无限制）2 |
1 高级计划执行只能保证 60 分钟，但技术上不限时长。
2 值为 -1 表示无限制执行，但建议保留固定上限。
{
"functionTimeout": "00:05:00"
}
healthMonitor
主机运行状况监视器的配置设置。
{
"healthMonitor": {
"enabled": true,
"healthCheckInterval": "00:00:10",
"healthCheckWindow": "00:02:00",
"healthCheckThreshold": 6,
"counterThreshold": 0.80
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| enabled | 是 | 指定是否已启用该功能。 |
| healthCheckInterval | 10 秒 | 定期后台运行状况检查之间的时间间隔。 |
| healthCheckWindow | 2 分钟 | 与 healthCheckThreshold 设置结合使用的滑动时间窗口。 |
| healthCheckThreshold | 6 | 在启动主机回收之前，运行状况检查可以失败的最大次数。 |
| counterThreshold | 0.80 | 性能计数器将被视为不正常的阈值。 |
http
可在 http 触发器和绑定中查找配置设置。
日志记录
控制函数应用（包括 Application Insights）的日志记录行为。
"logging": {
"fileLoggingMode": "debugOnly",
"logLevel": {
"Function.MyFunction": "Information",
"default": "None"
},
"console": {
...
},
"applicationInsights": {
...
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| fileLoggingMode | debugOnly | 确定在 Azure 中运行时的文件日志记录行为。 选项包括 never、always 和 debugOnly。 在本地运行时不使用此设置。 如果可能，在 Azure 中调试函数时应使用 Application Insights。 使用 always 会对应用的冷启动行为和数据吞吐量产生负面影响。 使用 Azure 门户进行调试时，默认 debugOnly 设置会生成日志文件。 |
| logLevel | 不适用 | 一个对象，它定义了用于筛选应用中的函数的日志类别。 此设置允许你筛选特定函数的日志记录。 有关详细信息，请参阅配置日志级别。 |
| 控制台 | 不适用 | 控制台日志记录设置。 |
| applicationInsights | 不适用 | applicationInsights 设置。 |
managedDependency
托管依赖项是一项功能，目前仅支持基于 PowerShell 的函数。 它使依赖项可以由服务自动管理。 enabled 属性设置为 true 时，requirements.psd1 文件会被处理。 发布任何次要版本时会更新依赖项。 有关详细信息，请参阅 PowerShell 文章中的托管依赖项。
{
"managedDependency": {
"enabled": true
}
}
queues
可在存储队列触发器和绑定中查找设置。
SendGrid
可在 SendGrid 触发器和绑定中查找配置设置。
serviceBus
可在服务总线触发器和绑定中查找配置设置。
singleton
单一实例锁行为的配置设置。 有关详细信息，请参阅有关单一实例支持的 GitHub 问题。
{
"singleton": {
"lockPeriod": "00:00:15",
"listenerLockPeriod": "00:01:00",
"listenerLockRecoveryPollingInterval": "00:01:00",
"lockAcquisitionTimeout": "00:01:00",
"lockAcquisitionPollingInterval": "00:00:03"
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| lockPeriod | 00:00:15 | 占用函数级锁的时间段。 锁自动续订。 |
| listenerLockPeriod | 00:01:00 | 占用侦听器锁的时间段。 |
| listenerLockRecoveryPollingInterval | 00:01:00 | 在启动时无法获取侦听器锁的情况下，用于恢复侦听器锁的时间间隔。 |
| lockAcquisitionTimeout | 00:01:00 | 运行时尝试获取锁的最长时间。 |
| lockAcquisitionPollingInterval | 不适用 | 尝试获取锁的间隔时间。 |
版本
此值指示 host.json 的架构版本。 面向 v2 运行时或更高版本的函数应用需要版本字符串 "version": "2.0"。 v2 和 v3 之间没有 host.json 架构更改。
watchDirectories
应该监视其更改情况的一组共享代码目录。 确保当这些目录中的代码发生更改时，函数会拾取这些更改。
{
"watchDirectories": [ "Shared" ]
}
watchFiles
一个或多个文件名称的数组，系统会监视这些文件，查看是否存在需要重启应用的更改。 这样就可以保证，当这些文件中的代码发生更改时，函数会拾取更新。
{
"watchFiles": [ "myFile.txt" ]
}
重写 host.json 值
某些情况下，可能希望为特定环境配置或修改 host.json 文件中的特定设置，而无需更改 host.json 文件本身。 可以通过创建等效值作为应用程序设置来重写特定的 host.json 值。 当运行时查找 AzureFunctionsJobHost__path__to__setting 格式的应用程序设置时，它将重写 JSON 中位于 path.to.setting 的等效 host.json 设置。 当表示为应用程序设置时，用于指示 JSON 层次结构的点 (.) 将替换为双下划线 (__)。
假设当 Application insights 在本地运行时想要禁用 Application insights 采样。 如果更改了本地 host.json 文件以禁用 Application Insights，则在部署过程中可能将此更改推送到生产应用。 执行此操作更为安全的方法是创建应用程序设置作为 local.settings.json 文件中的 "AzureFunctionsJobHost__logging__applicationInsights__samplingSettings__isEnabled":"false"。 可以在以下 local.settings.json 文件中查看此内容，但这不会发布：
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "{storage-account-connection-string}",
"FUNCTIONS_WORKER_RUNTIME": "{language-runtime}",
"AzureFunctionsJobHost__logging__applicationInsights__samplingSettings__isEnabled":"false"
}
}
使用环境变量替代 host.json 设置的操作遵循 ASP.NET Core 命名约定。 当元素结构包含数组时，应将数字数组索引视为此路径中的附加元素名称。 有关详细信息，请参阅环境变量的命名。