AppStartup

Overview

During application launch, a series of startup tasks are often required. If all these tasks are placed within the onCreate lifecycle of the UIAbility in the application's main module (module of the entry type), they can only be executed sequentially on the main thread, which significantly affects the application launch speed. In addition, when there are too many tasks, complex dependencies between them make the code difficult to maintain.

AppStartup offers an efficient approach to application launch. By supporting asynchronous initiation of startup tasks, it ensures a smoother startup process. The centralized configuration of execution order and dependencies of multiple startup tasks in a single file simplifies and clarifies the startup codebase, enhancing maintainability.

AppStartup supports startup tasks in automatic or manual mode. By default, automatic mode is used. During the creation of an AbilityStage, the configured startup tasks are loaded and executed in automatic mode. You can also call startupManager.run to execute the startup tasks in manual mode after a UIAbility is created.

Figure 1 Startup procedure

app-startup-procedure

Constraints

AppStartup can be used only in the UIAbility of an entry module.
Circular dependencies are not allowed between startup tasks.

Development Process

Defining an AppStartup Configuration File: Create an AppStartup configuration file in the resource file directory, add the configuration about startup tasks, and reference this configuration file in module.json5.
Setting Startup Parameters: In the startup parameter file, set parameters such as the timeout interval and startup task listener.
Adding a Startup Task for Each Component to Be Initialized: Implement the StartupTask interface.

How to Develop

Defining an AppStartup Configuration File

Create an AppStartup configuration file in the resources/base/profile directory of the application's main module (module of the entry type). The file name can be customized. The following uses startup_config.json as an example.

In the startup_config.json file, add the configuration for each startup task in sequence.

It is assumed that the application has six startup tasks. The dependencies between the tasks are shown in the figure below. To facilitate concurrent execution of startup tasks, a startup task file should contain only one startup task. In this example, each startup task corresponds to a startup task file.

Figure 2 Dependencies between startup tasks

app-startup

In the ets/startup directory, create six startup task files and a common startup parameter file. The file names must be unique.
1. Create six startup task files. In this example, the six files are named from StartupTask_001.ets to StartupTask_006.ets.
2. Create a startup parameter file. In this example, the file name is StartupConfig.ets.

Add the information about the startup task files and startup parameter file to the startup_config.json file.

The following is an example of the startup_config.json file:

{
  "startupTasks": [
    {
      "name": "StartupTask_001",
      "srcEntry": "./ets/startup/StartupTask_001.ets",
      "dependencies": [
        "StartupTask_002",
        "StartupTask_003"
      ],
      "runOnThread": "taskPool",
      "waitOnMainThread": false
    },
    {
      "name": "StartupTask_002",
      "srcEntry": "./ets/startup/StartupTask_002.ets",
      "dependencies": [
        "StartupTask_004"
      ],
      "runOnThread": "taskPool",
      "waitOnMainThread": false
    },
    {
      "name": "StartupTask_003",
      "srcEntry": "./ets/startup/StartupTask_003.ets",
      "dependencies": [
        "StartupTask_004"
      ],
      "runOnThread": "taskPool",
      "waitOnMainThread": false
    },
    {
      "name": "StartupTask_004",
      "srcEntry": "./ets/startup/StartupTask_004.ets",
      "runOnThread": "taskPool",
      "waitOnMainThread": false
    },
    {
      "name": "StartupTask_005",
      "srcEntry": "./ets/startup/StartupTask_005.ets",
      "dependencies": [
        "StartupTask_006"
      ],
      "runOnThread": "mainThread",
      "waitOnMainThread": true,
      "excludeFromAutoStart": true
    },
    {
      "name": "StartupTask_006",
      "srcEntry": "./ets/startup/StartupTask_006.ets",
      "runOnThread": "mainThread",
      "waitOnMainThread": false,
      "excludeFromAutoStart": true
    }
  ],
  "configEntry": "./ets/startup/StartupConfig.ets"
}

Table 1 Fields in the startup_config.json file

Field	Description	Data Type	Optional
startupTasks	Configuration about the startup tasks. For details, see the following table.	Object array	Mandatory
configEntry	Path of the startup parameter file.	String	Mandatory

Table 2 Description of startupTasks

Field	Description	Data Type	Optional
name	Name of the startup task, which can be customized. It is recommended that the name be the same as the class name.	String	Mandatory
srcEntry	Path of the file corresponding to the startup task.	String	Mandatory
dependencies	Array holding the class names of other startup tasks on which this task depends.	Object array	Optional, defaults to an empty array
excludeFromAutoStart	Whether to exclude automatic mode. For details, see Changing the Startup Mode. - true: manual mode. - false: automatic mode.	Boolean	Optional, defaults to false
runOnThread	Thread where the startup task is executed. - mainThread: executed in the main thread. - taskPool: executed in an asynchronous thread.	String	Optional, defaults to mainThread
waitOnMainThread	Whether the main thread needs to wait until the startup task finishes execution. This parameter is valid only when runOnThread is set to taskPool. - true: The main thread loads the application home page only the startup task finishes execution. - false: The main thread does not wait for the startup task to finish execution.	Boolean	Optional, defaults to true

Add the index of the AppStartup configuration file to the appStartup tag in the module.json5 file.

The following is an example of the module.json5 file:

{
"module": {
"name": "entry",
"type": "entry",
// ...
"appStartup": "$profile:startup_config," // AppStartup configuration file
// ...
}
}

Setting Startup Parameters

In the startup parameter file (ets/startup/StartupConfig.ets in this example), call StartupConfigEntry to set the common AppStartup parameters, including the timeout interval and listener.

StartupConfig: sets the task timeout interval and AppStartup listener.
StartupListener: listens for the execution result of the startup task.

import { StartupConfig, StartupConfigEntry, StartupListener } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class MyStartupConfigEntry extends StartupConfigEntry {
  onConfig() {
    hilog.info(0x0000, 'testTag', `onConfig`);
    let onCompletedCallback = (error: BusinessError<void>) => {
      hilog.info(0x0000, 'testTag', `onCompletedCallback`);
      if (error) {
        hilog.info(0x0000, 'testTag', 'onCompletedCallback: %{public}d, message: %{public}s', error.code, error.message);
      } else {
        hilog.info(0x0000, 'testTag', `onCompletedCallback: success.`);
      }
    };
    let startupListener: StartupListener = {
      'onCompleted': onCompletedCallback
    };
    let config: StartupConfig = {
      'timeoutMs': 10000,
      'startupListener': startupListener
    };
    return config;
  }
}

Adding a Startup Task for Each Component to Be Initialized

Through the preceding operations, you have configured the AppStartup configuration file and startup parameters. Now you need to implement StartupTask in each startup task file by calling the following two APIs:

init: starts task initialization. Call init to initialize a task only after all startup tasks on which the task depends are executed, that is, after onDependencyCompleted is invoked.
onDependencyCompleted: invoked when the startup task on which the current task depends is complete.

The following uses the StartupTask_001.ets file in startup_config.json as an example. You must add a startup task for each component to be initialized.

NOTE

StartupTask follows the Sendable protocol. Therefore, the Sendable annotation must be added when this API is inherited.

import { StartupTask, common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Sendable
export default class StartupTask_001 extends StartupTask {
  constructor() {
    super();
  }

  async init(context: common.AbilityStageContext) {
    hilog.info(0x0000, 'testTag', 'StartupTask_001 init.');
    return 'StartupTask_001';
  }

  onDependencyCompleted(dependence: string, result: Object): void {
    hilog.info(0x0000, 'testTag', 'StartupTask_001 onDependencyCompleted, dependence: %{public}s, result: %{public}s',
      dependence, JSON.stringify(result));
  }
}

(Optional) Changing the Startup Mode

AppStartup provides automatic and manual mode. By default, the automatic mode is used. However, you can change the mode to manual as required.

Automatic mode: After an AbilityStage is created, startup tasks are automatically executed.
Manual mode: After a UIAbility is created, you need to manually call the API to execute the startup task. Modules that are infrequently used do not need to be initialized when the application is launched. You can change the startup mode of these modules to manual. After the application is started, you can call startupManager.run to execute the startup task.

The following uses the onCreate lifecycle of the UIAbility as an example to describe how to manually trigger a startup task. The sample code is as follows:

import { AbilityConstant, UIAbility, Want, startupManager } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
    let startParams = ["StartupTask_005", "StartupTask_006"];
    try {
      startupManager.run(startParams).then(() => {
        console.log('StartupTest startupManager run then, startParams = ');
      }).catch((error: BusinessError) => {
        console.info('StartupTest promise catch error, error = ' + JSON.stringify(error));
        console.info('StartupTest promise catch error, startParams = '
          + JSON.stringify(startParams));
      })
    } catch (error) {
      let errMsg = JSON.stringify(error);
      let errCode: number = error.code;
      console.log('Startup catch error , errCode= ' + errCode);
      console.log('Startup catch error ,error= ' + errMsg);
    }
  }

  // ...
}

You can also call the API to trigger the manual mode after a page is loaded. The sample code is as follows:

import { startupManager } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  @State message: string = 'Manual Mode'
  @State startParams: Array<string> = ["StartupTask_006"];

  build() {
    RelativeContainer() {
      Button(this.message)
        .id('AppStartup')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .onClick(() => {
          if (!startupManager.isStartupTaskInitialized("StartupTask_006")) { // Check whether the startup task finishes execution.
            startupManager.run(this.startParams)
          }
        })
        .alignRules({
          center: {anchor: '__container__', align: VerticalAlign.Center},
          middle: {anchor: '__container__', align: HorizontalAlign.Center}
        })
    }
    .height('100%')
    .width('100%')
  }
}