App Lifecycle

In this article we’ll go over the lifecycle of iTwin Studio app

Pre App Initialization

When an iTwin Studio app is launched, the starting point is the initialization of iTwin Studio itself. An important factor in this initialization is the application config file, which is provided to iTwin Studio and conveys settings such as offline support, authentication configuration, GPRID and more.

Many of these settings directly affect the startup process of iTwin Studio.

Note

iTwin Studio is responsible for many tasks like authentication, launching the backend and frontend/renderer processes, loading localization resources and more.

iTwin Studio concurrently starts its backend and frontend processes before the application’s activation functions are invoked. These involve, among other things:

• Setting up IPC communication
• Gathering and applying startup options from your app via startupOptions hook
• Initializing iTwin.js native host and app, initializing services like localization, presentation, RPC etc.
• Initializing user preferences
• User authentication

Optional pre-initialization

If iTwin Studio provides the project selection page, iTwin Studio will ensure that a project is selected before activating an app. There are a few ways a project might be selected:

• Project selected using the selection page (automatically showed to user when there is no project selection cached)
• Project from cached preferences (caching is handled automatically by iTwin Studio and reflects the most recent user selection)
• Project id passed when starting a new iTwin Studio session, via CLI or URL args

Note

apps can opt out of iTwin Studio provided project selection by setting disableITwinSelection: true in the app.config.json or backend startupOptions. Once opted out, project selection will be skipped and your app will be activated without a project. Note that this will disable the project selection page all together, and your app should provide an alternative if it’s applicable.

App activation hooks

After iTwin Studio initializes, it activates the apps. Activation order is always as follows:

• Activate app backend - await activateBackend()
• Activate app frontend - await activateFrontend()

If either of the hooks throw an error, initialization will be stopped and a crash screen will be presented to the user.

App deactivation hooks

Apps will be deactivated in the following order:

• Deactivate app backend - await deactivateBackend()
• Deactivate app frontend - await deactivateFrontend()

Other events

In addition to the standard “session start” and “session end” events, app lifecycle is also affected by the following:

Sign out and sign in

If a user signs out mid-session, app will be deactivated, and once a user signs in again, app will be re-activated.

Since a different user might sign in mid-session, the app should be prepared for a different iTwin/iModel, different permissions, etc.

Note

It’s important to note that iTwin.js will not be re-created - as such, your app should clean up any singletons (e.g. widgets and frontstages) in the deactivation hook, or have the activation hook handle already initialized singletons.