# 元服务启动入口

**Q：使用IDE调试元服务，可以正常打开，划掉元服务，找不到再次打开元服务的入口？**

**A**：启动元服务可以通过服务卡片、负一屏以及hdc命令行三种方案：
> 说明
>
> 背景知识：服务卡片是系统一种呈现信息和交互操作的载体，在应用或元服务中提取关键信息和核心操作，以卡片的形式展示在桌面上，用户通过与服务卡片交互即可实现服务直达，减少交互层级，提升用户体验，参见[服务卡片开发](https://developer.huawei.com/consumer/cn/doc/atomic-guides/atomic-widget-development)；aa工具（Ability assistant，Ability助手）是用于启动应用和启动测试用例的工具，为开发者提供基本的应用调试和测试能力，参见[aa工具](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/aa-tool)。

为什么划掉元服务后桌面上找不到入口：元服务的图标不允许添加至桌面，它只能以服务卡片的形式加桌，或出现在负一屏的"最近""我的服务"中。因此划掉（从后台任务列表移除）后，桌面上没有可直接点击的图标，需通过以下任一方式重新进入。

方案一：服务卡片：

* 真机：如果已经开发了服务卡片，则可以通过在桌面上双指捏合，进入桌面的编辑模式，点击底部的"卡片"。在卡片添加页面，选择要添加到桌面的元服务卡片，点击"添加到桌面"，完成卡片添加，点击卡片进入元服务。
* 模拟器：操作步骤同上，其中"进入桌面的编辑模式"用「按住 Ctrl（Mac 为 Command）并滚动鼠标滚轮」模拟双指捏合，其余步骤与真机一致。

方案二：负一屏：

* 真机：1）在负一屏中点击搜索，如果打开过元服务，在"最近"或"我的服务"找到对应的元服务图标，点击图标可以进入元服务。2）已经开发了元服务卡片，则可以点击负一屏中的"卡片"右侧的"+"，找到自己的元服务，添加卡片到负一屏，点击卡片进入元服务。
* 模拟器：操作步骤同真机第 2）条：点击负一屏中的"卡片"右侧的"+"，找到自己的元服务，添加卡片到负一屏，点击卡片进入元服务。

方案三：hdc命令：

* 真机/模拟器：通过aa工具（Ability assistant，Ability助手）启动元服务。其中bundleName（应用包名）可以在元服务工程目录下的AppScope/app.json5文件中找到；下方命令中的EntryAbility为**示例值**，请替换为目标元服务实际的入口Ability名称（见其entry模块的module.json5）。
* 前置条件：目标Ability在其module.json5中的exported字段必须为true，否则aa命令无法拉起（报10103001）；若该Ability不在entry模块中，还需用-m指定模块名。

  ```bash
  # 基本用法（EntryAbility 为示例值，请替换为实际入口 Ability 名）
  hdc shell aa start -a EntryAbility -b {bundleName}
  # 若目标 Ability 不在 entry 模块中，需用 -m 指定模块名
  hdc shell aa start -a EntryAbility -b {bundleName} -m {moduleName}
  ```

验证是否安装成功：执行 hdc shell bm dump -a，若 {bundleName} 不在输出列表中，说明应用未安装成功。

**Q：通过aa工具启动元服务/应用报错"error: failed to start ability. error: resolve ability err."，如何解决？**

**A**：该报错表示 aa 工具未能解析出要启动的 Ability（对应错误码 10104001，The specified ability does not exist.）。按以下步骤排查：

1. 检查当前设备上元服务/应用是否安装成功：执行 hdc shell bm dump -a，若 bundleName 不在输出列表中，说明未安装成功。
2. 检查 aa 命令中的包名与 Ability 名是否正确：-b（bundleName）与 -a（abilityName）都要与目标应用一致，-a 不能固定写 EntryAbility。
3. 多 HAP 应用，还需确认该 Ability 所属的 HAP 已安装：执行 hdc shell bm dump -n {bundleName}，查看输出中是否包含对应模块与 Ability。
4. 确认目标 Ability 在 module.json5 中的 exported 为 true，否则无法被 aa 命令拉起（对应错误码 10103001）。

**Q：在终端使用hdc install xxxx.hap进行安装，安装结束后元服务应用不会自动打开，在负一屏的元服务板块也无法找到该安装包。怎么启动元服务？**

**A** ：在负一屏找不到该元服务，是因为**未上架应用市场的元服务不会在负一屏展示**（官方 FAQ：「元服务在未上架状态下不会在负一屏更新图标，将元服务上架后即可在负一屏更新。」）。本地调试阶段，可以用 aa 工具直接拉起元服务：

```bash
hdc shell aa start -a EntryAbility -b {bundleName}
```

其中 EntryAbility 与 {bundleName} 请替换为实际值。

**Q：通过aa工具启动元服务/应用报错"[Fail]ExecuteCommand need connect-key? please confirm a device by help info"？**

**A**：由于使用hdc命令时未正确指定目标设备导致的，可能连接多个设备未指定设备标识符或者设备连接异常，确保执行hdc list targets能够正常获取设备标识符（connect-key），如果有多个设备，需要在命令中通过-t参数指定目标设备标识符。

```bash
hdc -t {connect-key} shell aa start -a EntryAbility -b {bundleName}
```