ExternalAppHost

The host control which can embed external application windows.

Type

RoyalApps.Community.ExternalApps.WinForms.ExternalAppHost

Properties

AttachmentState (AttachmentState)

Gets how the current external window is attached to the host.

EmbeddedWindowHandle (IntPtr)

Gets the handle of the currently tracked external window, or System.IntPtr.Zero when no window is attached.

IsEmbedded (bool)

Gets a value indicating whether the current window is embedded in the host control.

LoggerFactory (ILoggerFactory)

Gets or sets the logger factory used to create host loggers.

Options (ExternalAppOptions?)

Gets the options used by the current session, or null when no session is active.

Process (Process?)

Gets the tracked process for the current session, or null when no process is attached.

Events

ApplicationActivated

Handler Type: EventHandler<EventArgs>?

Occurs when the embedded application receives focus.

ApplicationClosed

Handler Type: EventHandler<ApplicationClosedEventArgs>?

Occurs when the tracked application closes or the session terminates with an error.

ApplicationStarted

Handler Type: EventHandler<EventArgs>?

Occurs after the application has started and any initial embedding work has completed.

WindowSelectionRequested

Handler Type: EventHandler<WindowSelectionRequestEventArgs>?

Occurs while candidate windows are being discovered and allows the consumer to choose the window to embed.

WindowTitleChanged

Handler Type: EventHandler<WindowCaptionEventArgs>?

Occurs when the tracked window caption changes.

Methods

CloseApplication()

Returns: void

Requests that the tracked application is closed.

Depending on the application, this may show confirmation dialogs. If ExternalAppLaunchOptions.KillOnClose is enabled, the process is terminated when graceful shutdown fails.

FocusApplication(bool)

Returns: void

Transfers focus to the tracked application.

Parameters

• force (bool): true to focus even when the window is detached; otherwise, focus is applied only while embedded.

SetWindowPosition()

Repositions the tracked application window to match the current host bounds.

SetWindowPosition(Rectangle)

Returns: void

Moves and resizes the tracked application window to the specified bounds.

Parameters

• rectangle (Rectangle): The target bounds, in host coordinates when embedded or screen coordinates when detached.

Start(ExternalAppOptions)

Returns: void

Starts a new external application session with the specified options.

Parameters

• options (ExternalAppOptions): The runtime options that control launch, selection, and embedding behavior.

This method schedules the startup workflow on a background task and returns immediately. Subscribe to ExternalAppHost.ApplicationStarted, ExternalAppHost.ApplicationClosed, and ExternalAppHost.WindowSelectionRequested to observe progress.

Back to API index