1# @ohos.app.ability.appRecovery (appRecovery) 2 3The **appRecovery** module provides APIs for recovering faulty applications. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. In API version 9, only applications with a single ability in a process can be recovered. In API version 10, applications with multiple abilities in a process can be recovered. 8 9## Modules to Import 10```ts 11import appRecovery from '@ohos.app.ability.appRecovery'; 12``` 13 14## appRecovery.RestartFlag 15 16Enumerates the application restart flags. This enum is used as an input parameter of [enableAppRecovery](#apprecoveryenableapprecovery). 17 18**System capability**: SystemCapability.Ability.AbilityRuntime.Core 19 20| Name | Value | Description | 21| ---------- | ---- | ---------- | 22| ALWAYS_RESTART | 0 | The application is restarted in all cases.| 23| RESTART_WHEN_JS_CRASH | 0x0001 | The application is restarted in the case of JS_CRASH.| 24| RESTART_WHEN_APP_FREEZE | 0x0002 | The application is restarted in the case of APP_FREEZE.| 25| NO_RESTART | 0xFFFF | The application is not restarted in any case.| 26 27## appRecovery.SaveOccasionFlag 28 29Enumerates the scenarios for saving the application state. This enum is used as an input parameter of [enableAppRecovery](#apprecoveryenableapprecovery). 30 31**System capability**: SystemCapability.Ability.AbilityRuntime.Core 32 33| Name | Value | Description | 34| ----------------------------- | ---- | ------------------------------------------------------------ | 35| SAVE_WHEN_ERROR | 0x0001 | Saving the application state when an application fault occurs.| 36| SAVE_WHEN_BACKGROUND | 0x0002 | Saving the application state when the application is switched to the background.| 37 38## appRecovery.SaveModeFlag 39 40Enumerates the application state saving modes. This enum is used as an input parameter of [enableAppRecovery](#apprecoveryenableapprecovery). 41 42**System capability**: SystemCapability.Ability.AbilityRuntime.Core 43 44| Name | Value | Description | 45| ----------------------------- | ---- | ------------------------------------------------------------ | 46| SAVE_WITH_FILE | 0x0001 | The application state is saved and written to the local file cache.| 47| SAVE_WITH_SHARED_MEMORY | 0x0002 | The application state is saved in the memory. When the application exits due to a fault, it is written to the local file cache.| 48 49## appRecovery.enableAppRecovery 50 51enableAppRecovery(restart?: [RestartFlag](#apprecoveryrestartflag), saveOccasion?: [SaveOccasionFlag](#apprecoverysaveoccasionflag), saveMode?: [SaveModeFlag](#apprecoverysavemodeflag)) : void; 52 53Enables application recovery. After this API is called, the first ability that is displayed when the application is started from the initiator can be restored. 54 55**Model restriction**: This API can be used only in the stage model. 56 57**System capability**: SystemCapability.Ability.AbilityRuntime.Core 58 59**Parameters** 60 61| Name| Type| Mandatory| Description| 62| -------- | -------- | -------- | -------- | 63| restart | [RestartFlag](#apprecoveryrestartflag) | No| Whether the application is restarted upon a fault. By default, the application is restarted.| 64| saveOccasion | [SaveOccasionFlag](#apprecoverysaveoccasionflag) | No| Scenario for saving the application state. By default, the state is saved when a fault occurs.| 65| saveMode | [SaveModeFlag](#apprecoverysavemodeflag) | No| Application state saving mode. By default, the application state is written to the local file cache.| 66 67**Example** 68 69```ts 70import appRecovery from '@ohos.app.ability.appRecovery'; 71import AbilityStage from '@ohos.app.ability.AbilityStage'; 72 73export default class MyAbilityStage extends AbilityStage { 74 onCreate() { 75 appRecovery.enableAppRecovery( 76 appRecovery.RestartFlag.ALWAYS_RESTART, 77 appRecovery.SaveOccasionFlag.SAVE_WHEN_ERROR, 78 appRecovery.SaveModeFlag.SAVE_WITH_FILE 79 ); 80 } 81} 82``` 83 84## appRecovery.restartApp 85 86restartApp(): void; 87 88Restarts the current process and starts the first ability that is displayed when the application is started. If the state of this ability is saved, the saved state data is passed into the **wantParam** attribute in the **want** parameter of the **onCreate** lifecycle callback of the ability. 89 90In API version 10, the ability specified by [setRestartWant](#apprecoverysetrestartwant) is started. If no ability is specified, the following rules are used: 91- If the ability of the current application running in the foreground supports recovery, that ability is started. 92- If multiple abilities that support recovery is running in the foreground, only the last ability is started. 93- If no ability is running in the foreground, none of them is started. 94 95This API can be used together with the APIs of [errorManager](js-apis-app-ability-errorManager.md). 96 97**Model restriction**: This API can be used only in the stage model. 98 99**System capability**: SystemCapability.Ability.AbilityRuntime.Core 100 101 102**Example** 103 104```ts 105import appRecovery from '@ohos.app.ability.appRecovery'; 106import errorManager from '@ohos.app.ability.errorManager'; 107 108let observer: errorManager.ErrorObserver = { 109 onUnhandledException(errorMsg) { 110 console.log('onUnhandledException, errorMsg: ', errorMsg); 111 appRecovery.restartApp(); 112 } 113}; 114 115try { 116 errorManager.on('error', observer); 117} catch (paramError) { 118 console.error(`error: ${paramError.code}, ${paramError.message}`); 119} 120``` 121 122## appRecovery.saveAppState 123 124saveAppState(): boolean; 125 126Saves the application state. This API can be used together with the APIs of [errorManager](js-apis-app-ability-errorManager.md). 127 128**Model restriction**: This API can be used only in the stage model. 129 130**System capability**: SystemCapability.Ability.AbilityRuntime.Core 131 132**Return value** 133 134| Type| Description| 135| -------- | -------- | 136| boolean | Whether the application state is saved. The value **true** is returned if the application state is saved, and **false** is returned otherwise.| 137 138**Example** 139 140```ts 141import appRecovery from '@ohos.app.ability.appRecovery'; 142import errorManager from '@ohos.app.ability.errorManager'; 143 144let observer: errorManager.ErrorObserver = { 145 onUnhandledException(errorMsg) { 146 console.log('onUnhandledException, errorMsg: ', errorMsg); 147 appRecovery.saveAppState(); 148 } 149}; 150 151try { 152 errorManager.on('error', observer); 153} catch (paramError) { 154 console.error(`error: ${paramError.code}, ${paramError.message}`); 155} 156``` 157 158## appRecovery.saveAppState<sup>10+</sup> 159 160saveAppState(context?: UIAbilityContext): boolean; 161 162Saves the ability state, which will be used for recovery. This API can be used together with the APIs of [errorManager](js-apis-app-ability-errorManager.md). 163 164**Model restriction**: This API can be used only in the stage model. 165 166**System capability**: SystemCapability.Ability.AbilityRuntime.Core 167 168**Parameters** 169 170| Name| Type| Mandatory| Description| 171| -------- | -------- | -------- | -------- | 172| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md)| No| Context of the target ability.| 173 174**Return value** 175 176| Type| Description| 177| -------- | -------- | 178| boolean | Whether the application state is saved. The value **true** is returned if the application state is saved, and **false** is returned otherwise.| 179 180**Example** 181 182```ts 183import appRecovery from '@ohos.app.ability.appRecovery'; 184import errorManager from '@ohos.app.ability.errorManager'; 185 186let observer: errorManager.ErrorObserver = { 187 onUnhandledException(errorMsg) { 188 console.log('onUnhandledException, errorMsg: ', errorMsg); 189 appRecovery.saveAppState(this.context); 190 } 191}; 192 193try { 194 errorManager.on('error', observer); 195} catch (paramError) { 196 console.error(`error: ${paramError.code}, ${paramError.message}`); 197} 198``` 199 200## appRecovery.setRestartWant<sup>10+</sup> 201 202setRestartWant(want: Want): void; 203 204Sets an ability that will be recovered. The ability must be a UIAbility in the current bundle. 205 206**Model restriction**: This API can be used only in the stage model. 207 208**System capability**: SystemCapability.Ability.AbilityRuntime.Core 209 210**Parameters** 211 212| Name| Type| Mandatory| Description| 213| -------- | -------- | -------- | -------- | 214| want | [Want](js-apis-app-ability-want.md)| Yes| Want of the target ability. You can set the **bundleName** and **abilityName** fields in **Want** to specify the ability.| 215 216**Example** 217 218```ts 219import appRecovery from '@ohos.app.ability.appRecovery'; 220import Want from '@ohos.app.ability.Want'; 221 222@Entry 223@Component 224struct Index { 225 build() { 226 Button ("Start to Recover Ability") 227 .fontSize(40) 228 .fontWeight(FontWeight.Bold) 229 .onClick(()=> { 230 // set restart want 231 let want: Want = { 232 bundleName: "ohos.samples.recovery", 233 abilityName: "RecoveryAbility" 234 }; 235 236 appRecovery.setRestartWant(want); 237 }) 238 } 239} 240``` 241