IModelHost

Every iTwin.js backend must call IModelHost.startup (usually indirectly via a specialized host, see below) before using any backend services. IModelHost initializes imodeljs-backend so that it may access iModels and serve IModelApps.

IModelHost Specializations

To support the various use cases and platforms for iTwin.js backends, there are specialized "hosts" that should be used where appropriate. Each specialization supplies static methods that may be used for its relevant services.

For a given backend, you will pick one class from the following list, and call its startup method. The type of host running on the backend determines the type of IModelApp that can be used on the frontend.

• IModelHost: supports all configurations and must always be initialized. IModelHost may be used directly for "Agents" that don't connect to any frontends.
  • WebViewerHost: for the backend of web viewing applications using WebViewerApp. They are generally deployed on cloud-based VMs through an orchestration service. They only support RPC and all connections are made through HTTP so requests may be directed to any equivalent instances. They may be started/stopped according to demand. WebViewerHost.startup calls IModelHost.startup.
  • IpcHost: may be used when a backend is dedicated to and paired with a single frontend IpcApp so they may use Ipc. If either end terminates, the other must also. IpcHost.startup calls IModelHost.startup. IpcHost is abstract, and you should not use it directly.
    • WebEditHost: for the backend of a WebEditApp for editing iModels over the web. WebEditHost.startup creates web socket and calls IpcHost.Startup.
    • NativeHost: may be used when the frontend and backend are separate processes on the same computer. NativeHost.startup calls IpcHost.startup. NativeHost also provides access to local file system
      • ElectronHost: for desktop apps on Windows, Mac, and Linux. ElectronHost.startup calls NativeHost.startup,
      • MobileHost: for mobile apps. MobileHost.startupcalls NativeHost.startup and performs Mobile application startup procedures. MobileHost is abstract and should not be used directly.
        • IOSHost: for iOS backends. IOSHost.startup calls MobileHost.startup and performs iOS-specific startup procedures.
        • AndroidHost: for Android backends. AndroidHost.startup calls MobileHost.startup and performs Android-specific startup procedures.

A backend may need to set IModelHostConfiguration.appAssetsDir to identify its own assets directory. This would be needed, for example, if the app imports ECSchemas.

Example:

public static async startupIModelHost(): Promise<void> {
  // The host configuration.
  // The defaults will work for most backends.
  // Here is an example of how the cacheDir property of the host configuration
  // could be set from an environment variable, which could be set by a cloud deployment mechanism.
  let cacheDir = process.env.MY_SERVICE_CACHE_DIR;
  if (cacheDir === undefined) {
    const tempDir = process.env.MY_SERVICE_TMP_DIR || KnownLocations.tmpdir;
    cacheDir = path.join(tempDir, "iModelJs_cache");
  }

  const imHostConfig = new IModelHostConfiguration();
  imHostConfig.cacheDir = cacheDir;

  // Start up IModelHost, supplying the configuration.
  await IModelHost.startup(imHostConfig);
}

Last Updated: 11 June, 2024