1# aa工具 2 3 4Ability assistant（Ability助手，简称为aa），是用于启动应用和启动测试用例的工具，为开发者提供基本的应用调试和测试能力，例如启动应用组件、强制停止进程、打印应用组件相关信息等。 5 6> **说明：** 7> 8> 在使用本工具前，开发者需要先获取<!--Del-->[<!--DelEnd-->hdc工具<!--Del-->](../../device-dev/subsystems/subsys-toolchain-hdc-guide.md)<!--DelEnd-->，执行hdc shell。 9 10 11## help 12 用于显示aa相关的帮助信息。 13 14 **返回值**： 15 16 返回对应的帮助信息。 17 18 **使用方法**： 19 20 21 ```bash 22 aa help 23 ``` 24 25 26## start 27 用于启动一个应用组件，目标组件可以是FA模型的PageAbility和ServiceAbility组件，也可以是Stage模型的UIAbility和ServiceExtensionAbility组件，且目标组件相应配置文件中的exported标签不能配置为false。 28 29 | 参数 | 参数说明 | 30 | -------- |-------------------| 31 | -h/--help | 帮助信息。 | 32 | -d | 可选参数，deviceId。 | 33 | -a | 可选参数，abilityName。 | 34 | -b | 可选参数，bundleName。 | 35 | -m | 可选参数，moduleName。 | 36 | -U | 可选参数，URI。 | 37 | -A | 可选参数，action。 | 38 | -e | 可选参数，entity。 | 39 | -t | 可选参数，type。 | 40 | -S | 可选参数，调试时是否进入应用沙箱。携带该参数代表进入，不携带代表不进入。 | 41 | --pi | 可选参数，整型类型键值对。 | 42 | --pb | 可选参数，布尔类型键值对。 | 43 | --ps | 可选参数，字符串类型键值对。 | 44 | --psn | 可选参数，空字符串关键字。 | 45 | --wl | 可选参数，windowLeft，窗口左边距，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 46 | --wt | 可选参数，windowTop，窗口上边距，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 47 | --wh | 可选参数，windowHeight，窗口高度，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 48 | --ww | 可选参数，windowWidth，窗口宽度，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 49 | -D | 可选参数，调试模式。 | 50 | -p | 可选参数，调优命令。命令由调用方自定义。 | 51 52 **返回值**： 53 54 当启动成功时，返回"start ability successfully."；当启动失败时，返回"error: failed to start ability."，同时会包含相应的失败信息。 55 56 **使用方法**： 57 58 59 ```bash 60 # 显示启动Ability 61 aa start [-d <deviceId>] [-a <abilityName> -b <bundleName>] [-m <moduleName>] [-D] [-S] [--pi <key> <integer-value>] [--pb <key> <bool-value: true/false/t/f大小写不敏感] [--ps <key> <value>] [--psn <key>] [--wl <windowLeft>] [--wt <windowTop>] [--wh <windowHeight>] [--ww <windowWidth>] [-p <perf-cmd>] 62 63 # 隐式启动Ability。如果命令中的参数都不填，会导致启动失败。 64 aa start [-d <deviceId>] [-U <URI>] [-t <type>] [-A <action>] [-e <entity>] [-D] [--pi <key> <integer-value>] [--pb <key> <bool-value: true/false/t/f大小写不敏感] [--ps <key> <value>] [--psn <key>] [--wl <windowLeft>] [--wt <windowTop>] [--wh <windowHeight>] [--ww <windowWidth>] [-p <perf-cmd>] 65 ``` 66 67 **示例**： 68 69以隐式启动Ability为例。 70 > **说明：** 71 > 72 > 本例中仅介绍了部分字段的使用。关于Ability匹配的详细规则参考[显式Want与隐式Want匹配规则](../application-models/explicit-implicit-want-mappings.md)。 73 74 75 - **目标应用**：修改module.json5配置，为目标Ability配置uris。 76 77 ```json 78 { 79 "name": "TargetAbility", 80 ...... 81 "exported": true, 82 "skills": [ 83 { 84 "actions":[ 85 "ohos.want.action.viewData" 86 ], 87 "uris":[ 88 { 89 "scheme": "myscheme", 90 "host": "www.test.com", 91 "port": "8080", 92 "path": "path", 93 } 94 ] 95 } 96 ] 97 } 98 ``` 99 100 101 - **拉起方应用**: 隐式启动Ability。 102 103 - 如果需要拉起应用的页面，可以使用-U命令，示例如下： 104 105 ```bash 106 aa start -U myscheme://www.test.com:8080/path 107 ``` 108 109 - 在上述基础上，如果需要携带参数，可以使用如下命令： 110 111 ```bash 112 aa start -U myscheme://www.test.com:8080/path --pi paramNumber 1 --pb paramBoolean true --ps paramString teststring --psn paramNullString 113 ``` 114 115 UIAbility获取传入参数示例如下： 116 117 ```ts 118 import UIAbility from '@ohos.app.ability.UIAbility'; 119 import hilog from '@ohos.hilog'; 120 import Want from '@ohos.app.ability.Want'; 121 122 export default class TargetAbility extends UIAbility { 123 onCreate(want:Want, launchParam) { 124 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 125 let paramNumber = want.parameters.paramNumber 126 let paramBoolean = want.parameters.paramBoolean 127 let paramString = want.parameters.paramString 128 let paramNullString = want.parameters.paramNullString 129 } 130 } 131 ``` 132 133 - 如果需要拉起浏览器并跳转指定页面，可以使用-A -U命令，示例如下： 134 135 本例中以`https://www.example.com`为例，请根据实际情况替换为真实的网址。 136 137 ```bash 138 aa start -A ohos.want.action.viewData -U https://www.example.com 139 ``` 140 141 142## stop-service 143 用于停止ServiceAbility。 144 145 | 参数 | 参数说明 | 146 | -------- | -------- | 147 | -h/--help | 帮助信息。 | 148 | -d | 可选参数，deviceId。 | 149 | -a | 必选参数，abilityName。 | 150 | -b | 必选参数，bundleName。 | 151 | -m | 可选参数，moduleName。 | 152 153 **返回值**： 154 155 当成功停止ServiceAbility时，返回"stop service ability successfully."；当停止失败时，返回"error: failed to stop service ability."。 156 157 **使用方法**： 158 159 160 ```bash 161 aa stop-service [-d <deviceId>] -a <abilityName> -b <bundleName> [-m <moduleName>] 162 ``` 163 164## dump<sup>(deprecated)</sup> 165 > **说明：** 166 > 167 > aa dump命令从API version 7开始支持，从API version 9废弃，替换命令为[hidumper](../dfx/hidumper.md) -s AbilityManagerService。 168 169 用于打印应用组件的相关信息。 170 | 参数 | 二级参数 | 参数说明 | 171 | -------- | -------- | -------- | 172 | -h/--help | - | 帮助信息。 | 173 | -a/--all | - | 打印所有mission内的应用组件信息。 | 174 | -l/--mission-list | type（缺省打印全部） | 服务侧为了方便管理任务链，内部维护了4种类型的任务链。<br/>可取值：<br/>- NORMAL：正常启动的任务链(比如A拉起B拉起C, 则对应的任务链是A->B->C)<br/>- DEFAULT_STANDARD：已经被破坏的任务链中的任务, 启动模式为`multiton`的任务被放到该任务链中, 这里面的任务之间没有关联关系<br/>- DEFAULT_SINGLE：已经被破坏的任务链中的任务, 启动模式为`singleton`的任务被放到该任务链中, 这里面的任务之间没有关联关系<br/>- LAUNCHER：launcher的任务链 | 175 | -e/--extension | elementName | 打印扩展组件信息。 | 176 | -u/--userId | UserId | 打印指定UserId的栈信息，需要和其他参数组合使用，例如aa dump -a -u 100、aa dump -d -u 100。 | 177 | -d/--data | - | 打印DataAbility相关信息。 | 178 | -i/--ability | AbilityRecord ID | 打印指定应用组件详细信息。 | 179 | -c/--client | - | 打印应用组件详细信息，需要和其他参数组合使用，例如aa dump -a -c、aa dump -i 21 -c。 | 180 | -p/--pending | - | 打印pendingWant信息，需要和其他参数组合使用，例如aa dump -a -p。 | 181 | -r/--process | - | 打印应用进程信息，需要和其他参数组合使用，例如aa dump -a -r。 | 182 183 **使用方法**： 184 185 186 ```bash 187 aa dump -a 188 ``` 189 190  191 192 193 ```bash 194 aa dump -l 195 ``` 196 197  198 199 200 ```bash 201 aa dump -i 12 202 ``` 203 204  205 206## force-stop 207 通过bundleName强制停止一个进程。 208 209 **返回值**： 210 211 当成功强制停止该进程时，返回"force stop process successfully."；当强制停止失败时，返回"error: failed to force stop process."。 212 213 **使用方法**： 214 215 216 ```bash 217 aa force-stop <bundleName> 218 ``` 219 220## test 221 222 根据所携带的参数启动测试框架。 223 224 > **说明**： 225 > 226 > 关于class、level、size、testType等参数的详细说明请参见<!--RP2-->[aa test命令执行配置参数](../application-test/arkxtest-guidelines.md#cmd执行)<!--RP2End-->。 227 228 | 参数 | 参数说明 | 229 | -------- | -------- | 230 | -h/--help | 帮助信息。 | 231 | -b | 必选参数，bundleName。 | 232 | -s unittest | 必选参数，testRunner。 | 233 | -p | 可选参数，testRunner的packageName。<br>**说明**：该可选参数仅可在FA模型下使用。 | 234 | -m | 可选参数，testRunner的moduleName。<br>**说明**：该可选参数仅可在Stage模型下使用。 | 235 | -s class | 可选参数，指定要执行的测试套或测试用例。 | 236 | -s level | 可选参数，指定要执行用例的用例级别。 | 237 | -s size | 可选参数，指定要执行用例的用例规模。 | 238 | -s testType | 可选参数，指定要执行用例的用例类型。 | 239 | -s timeout | 可选参数，测试用例执行的超时时间（单位ms），默认为5000。 | 240 | -s \<any-key> | 可选参数，任意键值对。 | 241 | -w | 可选参数，指定测试运行时间（单位ms）。 | 242 | -D | 可选参数，调试模式。 | 243 244 **返回值**： 245 246 当成功启动测试框架时，返回"user test started."；当启动失败时，返回"error: failed to start user test."和对应的错误信息。 247 248 **使用方法**： 249 250 ```bash 251 aa test -b <bundleName> [-m <module-name>] [-p <package-name>] [-s class <test-class>] [-s level <test-level>] [-s size <test-size>] [-s testType <test-testType>] [-s timeout <test-timeout>] [-s <any-key> <any-value>] [-w <wait-time>] -s unittest <testRunner> 252 ``` 253 254## attach 255 通过bundleName使指定应用进入调试模式。 256 257 | 参数 | 参数说明 | 258 | -------- |-------------------| 259 | -h/--help | 帮助信息。 | 260 | -b | 必选参数，bundleName。 | 261 262 263 **返回值**： 264 265 当应用成功进入调试模式时，返回"attach app debug successfully."；当给定参数不合法时，返回"fail: unknown option."并打印帮助信息。 266 267 **使用方法**： 268 269 270 ```bash 271 aa attach -b <bundleName> 272 ``` 273 274## detach 275 通过bundleName使指定应用退出调试模式。 276 277 | 参数 | 参数说明 | 278 | -------- |-------------------| 279 | -h/--help | 帮助信息。 | 280 | -b | 必选参数，bundleName。 | 281 282 283 **返回值**： 284 285 当应用成功退出调试模式时，返回"detach app debug successfully."；当给定参数不合法时，返回"fail: unknown option."并打印帮助信息。 286 287 **使用方法**： 288 289 290 ```bash 291 aa detach -b <bundleName> 292 ``` 293 294## appdebug 295 用于设置、取消设置应用等待调试状态，以及获取处于等待调试状态的应用包名和持久化信息。等待调试状态只对debug类型应用生效。appdebug的设置命令只对单个应用生效，当重复设置时，应用包名与持久化状态会替换成最新设置内容。 296 297 | 参数 | 二级参数 | 参数说明 | 298 | -------- | -------- | -------- | 299 | -h/--help | - | 帮助信息。 | 300 | -b/--bundlename | bundleName | 为指定应用设置等待调试状态。设置时，不会进行包名合法化的校验。 | 301 | -p/--persist | - | 可选参数；持久化标志位，加入该参数，代表持续设置应用为等待调试状态，无论重启设备、重装应用都可以持续生效；不加入该参数，代表等待调试状态仅可以在重启设备前生效一次。需要和-b参数组合使用，例如：aa appdebug -b <bundleName> -p。 | 302 | -c/--cancel | - | 取消等待调试状态。 | 303 | -g/--get | - | 获取等待调试状态的应用包名和持久化信息。 | 304 305 **返回值**： 306 307 当执行成功时，返回"app debug successfully."；当执行失败时，返回"error: failed to app debug."；当失败原因为非开发者模式时，返回"error: not developer mode."。 308 309 **使用方法**： 310 311 ```bash 312 # 显示帮助信息 313 aa appdebug -h 314 315 # 为指定应用设置等待调试状态 316 aa appdebug -b <bundleName> [-p] 317 318 # 取消等待调试状态 319 aa appdebug -c 320 321 # 获取等待调试状态的应用包名和持久化信息 322 aa appdebug -g 323 # 获取信息例： bundle name : com.example.publishsystem, persist : false 324 ``` 325 326## process 327 对应用进行调试或调优，IDE用该命令集成调试和调优工具。 328 329 | 参数 | 参数说明 | 330 | -------- | -------- | 331 | -h/--help | 帮助信息。 | 332 | -b | 必选参数，bundleName。 | 333 | -a | 必选参数，abilityName。 | 334 | -m | 可选参数，moduleName。 | 335 | -p | 可选参数，调优命令，与-D必须二选一。命令由调用方自定义。 | 336 | -D | 可选参数，调试命令，与-p必须二选一。命令由调用方自定义。 | 337 | -S | 可选参数，进入应用沙箱。 | 338 339 **返回值**： 340 341 当执行成功时，返回"start native process successfully."；当执行失败时，返回"error: failed to start native process."；当给定参数不合法时，返回"error: option requires a value."并打印帮助信息。 342 343 **使用方法**： 344 345 ```bash 346 # 显示帮助信息 347 aa process -h 348 349 # 调试应用 350 aa process -b <bundleName> -a <abilityName> [-m <moduleName>] [-D <debug-cmd>] [-S] 351 352 # 调优应用 353 aa process -b <bundleName> -a <abilityName> [-m <moduleName>] [-p <perf-cmd>] [-S] 354 ``` 355
