通过

应用程序清单

  • 项目

应用程序清单描述了应用程序所需的资源，也称为“应用程序功能”。 每个应用程序都具有应用程序清单。

应用程序必须通过在应用程序清单的“功能”部分中列出每个所需资源来选择使用功能；默认情况下不启用任何功能。 如果应用程序请求未列出的功能，则请求将失败。 如果应用程序清单文件包含错误，则尝试旁加载应用程序将失败。 每个应用程序的清单必须以 app_manifest.json 的形式存储在电脑上应用程序文件夹的根目录中。

创建应用程序时，Azure Sphere 模板会自动创建默认应用程序清单。 必须编辑默认清单才能列出应用程序所需的功能。 每个 Azure Sphere 示例都还包括一个应用程序清单。 如果你的应用程序基于示例，可能还需要编辑清单。

不同的 Azure Sphere 设备可能以不同的方式公开芯片的功能。 因此，在清单中用于标识特定功能的值（例如，GPIO 引脚）可能会因你开发的硬件而异。 管理目标硬件依赖项提供了关于高级应用程序的硬件目标的详细信息。 在高级应用程序的应用程序清单中，使用Microsoft Azure Sphere SDK 安装目录的 HardwareDefinitions 文件夹中的 JSON 文件中定义的常量。 安装目录的确切位置在 Windows 和 Linux 上将有所不同。 在支持实时的应用程序 (RTApp) 中，使用应用程序清单的内容中列出的原始值。

任何应用程序被旁加载或部署到设备时，Azure Sphere 运行时都将读取应用程序清单以确定应用程序可以使用的功能。 尝试访问清单中未列出的资源将导致 API 错误，例如EPERM（权限被拒绝）。 在设备上，一个应用程序只能使用一项资源。 如果安装的应用程序请求的资源已被使用，则请求尝试会失败。

应用程序清单的内容

应用程序清单包含以下各项：

名称 说明
SchemaVersion 正在使用的应用程序清单架构的版本。 目前必须为 1。 必需。
Name 应用程序的名称。 在项目创建时，此值设置为项目的名称。 名称可以是任何长度，但只有前 31 个字符存储在映像包中;因此，名称在有关映像包的查询中显示为截断。 必需。
ComponentId 组件的 ID。 当你生成应用程序时，Visual Studio 会创建此 ID。 如果不使用 Visual Studio，请参阅 “生成组件 ID ”，了解有关创建 ID 的信息。 必需。
EntryPoint 可执行文件的名称以及应用程序构建时创建的应用程序文件系统映像中的相对路径。 Visual Studio 当前使用 /bin/app 来获取此值。 必需。
CmdArgs 在启动时要传递给应用程序的参数。 将每个参数括在双引号中，并用逗号分隔参数。 可选。
TargetBetaApis 指定应用程序需要 Beta API，并确定使用的 Beta API 集。 如果使用 Beta API 生成应用程序，则生成过程中会自动添加此字段。 可选。 有关详细信息，请参阅使用 Beta 功能。
ApplicationType 应用程序类型。 可选。 仅在构建 gdbserver 的替换时才设置为“调试程序”。
Capabilities 指定应用程序资源要求的键/值对列表。 必需。
MallocVersion 一个整数，指定 malloc 的版本，其中 1=standard 和 2=mallocng，这是 MUSL 版本大于 1.2.1 的增强型 malloc。 建议对所有新应用开发使用版本 2。

功能部分支持以下内容：

注意

高级应用程序可以使用硬件定义文件中的功能值，也可以使用原始值。 但是，不能在同一功能中混合使用这两种值类型。 RTApps 只能对功能使用原始值。

名称 描述
Adc 应用程序使用的模拟到数字转换（ADC）控制器。 此功能保留整个 ADC 控制器（其中包含 8 个引脚块），而不仅是块中的引脚 0。
在高级应用程序中，指定在硬件定义头文件中声明的外设名称。
在 RTApp 中，指定在硬件定义 JSON 文件中声明的 AppManifestValue。
硬件定义示例："Adc": [ "$MT3620_RDB_ADC_CONTROLLER0" ]
原始值示例："Adc": [ "ADC-CONTROLLER-0" ]
API 参考：Applibs adc.h
概念：在 Azure Sphere 上使用 ADC
AllowedApplicationConnections 允许应用程序连接到的应用程序组件 ID 的列表。
示例："AllowedApplicationConnections": [ "005180BC-402F-4CB3-A662-72937DBCDE47" ]
API 参考：Applibs application.h
概念：与高级应用程序通信
AllowedConnections 允许应用程序连接的 DNS 主机名或 IP 地址 (IPv4) 的列表。 如果应用程序使用 Azure IoT 中心，则列表必须包含该中心的 IP 地址或 DNS 主机名，通常为 hub-name.azure-devices.net。 不接受在名称和 IP 地址中使用端口号和通配符。
示例："AllowedConnections" : [ "my-hub.example.net", "global.azure-devices-provisioning.net" ]
AllowedTcpServerPorts 允许传入 TCP 流量的端口列表。 最多可以包含 10 个端口，每个端口必须单独列出。 支持的端口为 1024 到 65535。 可为 TCP 和 UDP 指定相同的端口。 但是，如果为设备上的多个应用指定同一端口，则无法加载要运行的第二个应用。
示例："AllowedTcpServerPorts": [ 1024, 65535 ]
AllowedUdpServerPorts 允许传入 UDP 流量的端口列表。 最多可以包含 10 个端口，每个端口必须单独列出。 支持的端口为 1024 到 65535。 可为 TCP 和 UDP 指定相同的端口。 但是，如果为设备上的多个应用指定同一端口，则无法加载要运行的第二个应用。
示例："AllowedUdpServerPorts": [ 1024, 50000 ]
CertStore 一个布尔值，指示高级应用是否有权使用 CertStore API 管理证书：true 以启用 API;否则为 false。
示例："CertStore" : true
DeviceAuthentication 一个字符串，指定用于设备身份验证的 Azure Sphere 租户的 UUID。
示例："DeviceAuthentication": "77304f1f-9530-4157-8598-30bc1f3d66f0"
DhcpService 一个布尔值，指示应用程序是否有权配置 DHCP 服务：如果应用程序具有功能，则为 true;否则为 false。
示例："DhcpService" : true
API 参考：Applibs networking.h
概念：使用网络服务
EnterpriseWifiConfig 一个布尔值，指示高级应用程序是否有权创建 EAP-TLS 网络并将证书与该网络相关联：如果应用程序具有功能，则为 true;否则为 false。
示例："EnterpriseWifiConfig" : true
ExternalInterrupt RTApp 使用的外部中断的列表。 此功能不适用于高级别应用程序。
示例："ExternalInterrupt": [ "EINT4", "EINT12" ]
GPIO 应用程序使用的 GPIO 的列表。
在高级应用程序中，指定在硬件定义头文件中声明的 GPIO 名称（例如，$MT3620_RDB_LED1_RED）。
在 RTApp 中，指定与硬件定义 JSON 文件中的 GPIO 编号对应的整数。 例如，指定 8 表示 GPIO 8。
硬件定义示例："Gpio": [ "$MT3620_RDB_HEADER1_PIN6_GPIO", "$MT3620_RDB_LED1_RED", "$MT3620_RDB_BUTTON_A" ]
原始值示例："Gpio": [ 8, 12 ]
API 参考：Applibs gpio.h
概念：在 Azure Sphere 上使用 GPIO
HardwareAddressConfig 一个布尔值，指示应用程序是否有权配置网络接口的硬件地址：如果应用程序具有功能，则为 true;否则为 false。
示例："HardwareAddressConfig" : true
API 参考：Applibs networking.h
概念：使用网络服务
HeapMemStats 一个布尔值，指示是否启用堆内存分配跟踪：如果应用程序具有功能，则为 true;否则为 false。
示例："HeapMemStats": true
概念：高级应用程序中的内存使用
I2cMaster 应用程序使用的 I2C 主接口列表。
在高级应用程序中，指定在硬件定义头文件中声明的外设名称。
在 RTApp 中，指定在硬件定义 JSON 文件中声明的 AppManifestValue。
硬件定义示例："I2cMaster": [ "$MT3620_RDB_HEADER2_ISU0_I2C", "$MT3620_RDB_HEADER4_ISU1_I2C" ]
原始值示例："I2cMaster": [ "ISU0", "ISU1" ]
API 参考：Applibs i2c.h
概念：将 I2C 与 Azure Sphere 配合使用
I2sSubordinate RTApp 使用的芯片间传递音讯 (I2S) 从属接口。 此功能不适用于高级别应用程序。 原始值示例： “I2sSubordinate”： [ “I2S0”， “I2S1” ]
MutableStorage 允许应用程序使用持久性存储的可变存储设置。
示例："MutableStorage" : { "SizeKB": 64, }
API 参考：Applibs storage.h
概念：在 Azure Sphere 上使用存储
NetworkConfig 一个布尔值，指示应用程序是否有权配置网络接口：如果应用程序具有功能，则为 true;否则为 false。
示例："NetworkConfig" : true
API 参考：Applibs networking.h
概念：使用网络服务
PowerControls 一个字符串数组，表示用于控制设备电源状态的精细功能。 支持的值只有 ForcePowerDown 和 ForceReboot。
警告： 由于 ForcePowerDown 和 ForceReboot 允许应用程序立即终止所有应用程序，因此 必须确保 设备仍能够接收操作系统和应用程序更新。 有关详细信息和指南，请参阅强制掉电和更新。
示例："PowerControls": ["ForcePowerDown", "ForceReboot"]
API 参考：Applibs powermanagement.h
概念：管理 Azure Sphere 设备的停电状态
Pwm 应用程序使用的脉冲宽度调节器（PWM）。
在高级应用程序中，指定在硬件定义头文件中声明的外设名称。
在 RTApp 中，指定在硬件定义 JSON 文件中声明的 AppManifestValue。
硬件定义示例："Pwm": [ "$MT3620_RDB_LED_PWM_CONTROLLER2" ]
原始值示例："Pwm": [ "PWM-CONTROLLER-0" ]
API 参考：Applibs pwm.h
概念：在高级应用程序中使用 PVM
ReadNetworkProxyConfig 一个布尔值，指示应用程序是否有权检索代理配置：如果应用程序具有功能，则为 true;否则为 false。
示例："ReadNetworkProxyConfig": true
API 参考：Applibs networking.h
概念：连接到 Web 服务
SntpService 一个布尔值，指示应用程序是否有权配置 SNTP 服务：如果应用程序具有功能，则为 true;否则为 false。
示例："SntpService" : true
API 参考：Applibs networking.h
概念：SNTP 服务器
SoftwareUpdateDeferral 一个布尔值，指示应用程序是否有权在有限时间内延迟软件更新：如果应用程序具有功能，则为 true;否则为 false。
示例："SoftwareUpdateDeferral" : true
API 参考：Applibs eventloop。h
概念：延迟设备更新
SpiMaster 应用程序使用的 SPI 主接口列表。
在高级应用程序中，指定在硬件定义头文件中声明的外设名称。
在 RTApp 中，指定在硬件定义 JSON 文件中声明的 AppManifestValue。
硬件定义示例："SpiMaster": [ "$MT3620_RDB_HEADER2_ISU0_SPI", "$MT3620_RDB_HEADER4_ISU1_SPI" ]
原始值示例："SpiMaster": [ "ISU0", "ISU1" ]
API 参考：Applibs spi.h
概念：将 SPI 与 Azure Sphere 配合使用
SystemEventNotifications 一个布尔值，指示应用程序是否有权接收系统事件通知：如果应用程序具有功能，则为 true;否则为 false。
示例："SystemEventNotifications" : true
API 参考：Applibs sysevent.h
概念：延迟设备更新
SystemTime 一个布尔值，指示应用程序是否有权配置系统时间：如果应用程序具有功能，则为 true;否则为 false。
示例："SystemTime" : true
API 参考：Applibs rtc.h
概念：管理 Azure Sphere 上的系统时间和 RTC
TimeSyncConfig 一个布尔值，指示应用程序是否有权配置时间同步服务：如果应用程序具有功能，则为 true;否则为 false。
示例："TimeSyncConfig" : true
UART 应用程序使用的 UART 外设列表。 此功能无法在 MT3620 开发板上启用专用 UART。 有关专用 UART 的信息，请参阅 生成支持实时的应用程序。
在高级应用程序中，指定在硬件定义头文件中声明的外设名称。
在 RTApp 中，指定在硬件定义 JSON 文件中声明的 AppManifestValue。
硬件定义示例："Uart": [ "$MT3620_RDB_HEADER2_ISU0_UART", "$MT3620_RDB_HEADER4_ISU1_UART" ]
原始值示例："Uart": [ "ISU0", "ISU1" ]
API 参考：Applibs uart.h
概念：在 Azure Sphere 上使用 UART
WifiConfig 一个布尔值，指示应用程序是否有权使用 WifiConfig API 更改 Wi-Fi 配置：如果应用程序具有功能，则为 true;否则为 false。
示例："WifiConfig" : true
API 参考：Applibs wificonfig.h
概念：配置网络

MutableStorage 节支持以下值：

名称 描述
SizeKB 用于指定可变存储大小（以千位字节为单位）的整数。 最大值为 64。 值为 0 等同于不具有可变存储能力。

示例

下面显示了面向 MT3620 RDB 硬件的高级应用程序的示例 app_manifest.json 文件：

{
    "SchemaVersion": 1,
    "Name": "MyTestApp",
    "ComponentId": "072c9364-61d4-4303-86e0-b0f883c7ada2",
    "EntryPoint": "/bin/app",
    "CmdArgs": ["-m", "262144", "-t", "1"],
    "Capabilities": {
        "AllowedConnections" : [
            "my-hub.example.net",
            "contoso.azure-devices.net",
            "global.azure-devices-provisioning.net" ],
        "AllowedTcpServerPorts": [ 1024, 65535 ],
        "AllowedUdpServerPorts": [ 1024, 50000 ],
        "DeviceAuthentication": "77304f1f-9530-4157-8598-30bc1f3d66f0",
        "Gpio": [ "$MT3620_RDB_HEADER1_PIN6_GPIO", "$MT3620_RDB_LED1_RED", "$MT3620_RDB_BUTTON_A" ],
        "HardwareAddressConfig": true,
        "I2cMaster": [ "ISU2" ],
        "MutableStorage" : {
            "SizeKB": 64,
        },
        "SpiMaster": [ "ISU1" ],
        "SystemTime" : true,
        "Uart": [ "ISU0" ],
        "WifiConfig" : true
    },
    "ApplicationType": "Default",
    "MallocVersion": 2
}

MyTestApp 的示例 app_manifest.json 文件的用途如下：

  • 将四个命令行参数传递给应用。
  • 仅允许与 DNS 主机 my-hub.example.net、contoso.azure-devices.net 和 global.azure-devices-provisioning.net 建立连接。
  • 允许端口 1024 和 65535 上的 TCP 传入流量。
  • 允许端口 1024 和 50000 上的 UDP 传入流量。
  • 指定用于设备身份验证的 Azure Sphere（旧版）租户 UUID，并允许连接到设备预配服务。
  • 指定使用三个 GPIO。
  • 允许应用程序配置网络接口的硬件地址。
  • 指定使用一个 UART 外围设备。
  • 启用具有 64 KB 存储空间的可变存储。
  • 使应用能够使用 WifiConfig API 更改 Wi-Fi 配置。
  • 指定使用一个 SPI 主接口。
  • 指定使用一个 I2C 主接口。
  • 使应用能够使用 RTC API 配置系统时间。
  • 为应用开发启用 mallocng。