Class Host

Namespace

Ranorex

Assembly

Ranorex.Core.dll

Represents the host machine running Ranorex.

public class Host : Adapter, IHost, IAdapter

Inheritance

object

Adapter

Host

Implements

IHost

IAdapter

Inherited Members

Adapter.Create(Type, Element)

Adapter.Create<T>(Element)

Adapter.TryCreate(Type, Element, out Adapter)

Adapter.TryCreate<T>(Element, out T)

Adapter.FindSingle(RxPath)

Adapter.FindSingle(RxPath, Duration)

Adapter.FindSingle<T>(RxPath)

Adapter.FindSingle<T>(RxPath, Duration)

Adapter.TryFindSingle(RxPath, out Element)

Adapter.TryFindSingle(RxPath, Duration, out Element)

Adapter.TryFindSingle<T>(RxPath, out T)

Adapter.TryFindSingle<T>(RxPath, Duration, out T)

Adapter.Find<T>(RxPath)

Adapter.Find(RxPath)

Adapter.Find<T>(RxPath, Duration)

Adapter.Find(RxPath, Duration)

Adapter.FindChild<T>()

Adapter.FindChildren<T>()

Adapter.FindDescendant<T>()

Adapter.FindDescendants<T>()

Adapter.Filter<T>(IList<Element>)

Adapter.ListToSingleOrNull<T>(IList<T>)

Adapter.CaptureCompressedImage()

Adapter.As<T>()

Adapter.GetPath(PathBuildMode)

Adapter.GetPath()

Adapter.ToString()

Adapter.EnsureVisible()

Adapter.Focus()

Adapter.Click()

Adapter.Click(MouseButtons)

Adapter.Click(Location)

Adapter.ClickWithoutBoundsCheck(Location)

Adapter.Click(Duration)

Adapter.Click(MouseButtons, Location)

Adapter.ClickWithoutBoundsCheck(MouseButtons, Location)

Adapter.Click(MouseButtons, Duration)

Adapter.Click(Location, Duration)

Adapter.ClickWithoutBoundsCheck(Location, Duration)

Adapter.Click(int, Duration)

Adapter.Click(MouseButtons, Location, Duration)

Adapter.ClickWithoutBoundsCheck(MouseButtons, Location, Duration)

Adapter.Click(MouseButtons, int, Duration)

Adapter.Click(Location, int, Duration)

Adapter.ClickWithoutBoundsCheck(Location, int, Duration)

Adapter.Click(MouseButtons, Location, int, Duration)

Adapter.ClickWithoutBoundsCheck(MouseButtons, Location, int, Duration)

Adapter.DoubleClick()

Adapter.DoubleClick(MouseButtons)

Adapter.DoubleClick(MouseButtons, Duration)

Adapter.DoubleClick(Location)

Adapter.DoubleClickWithoutBoundsCheck(Location)

Adapter.DoubleClick(Duration)

Adapter.DoubleClick(MouseButtons, Location)

Adapter.DoubleClickWithoutBoundsCheck(MouseButtons, Location)

Adapter.DoubleClick(Location, Duration)

Adapter.DoubleClickWithoutBoundsCheck(Location, Duration)

Adapter.DoubleClick(MouseButtons, Location, Duration)

Adapter.DoubleClickWithoutBoundsCheck(MouseButtons, Location, Duration)

Adapter.MoveTo()

Adapter.MoveTo(Duration)

Adapter.MoveToWithoutBoundsCheck(Location)

Adapter.MoveTo(Location)

Adapter.MoveTo(Location, Duration)

Adapter.MoveToWithoutBoundsCheck(Location, Duration)

Adapter.PressKeys(string)

Adapter.PressKeys(string, Duration)

Adapter.Touch()

Adapter.Touch(Duration)

Adapter.Touch(int, int)

Adapter.TouchWithoutBoundsCheck(int, int)

Adapter.Touch(int, int, Duration)

Adapter.TouchWithoutBoundsCheck(int, int, Duration)

Adapter.Touch(double, double)

Adapter.TouchWithoutBoundsCheck(double, double)

Adapter.Touch(double, double, Duration)

Adapter.TouchWithoutBoundsCheck(double, double, Duration)

Adapter.Touch(Location, Duration)

Adapter.TouchWithoutBoundsCheck(Location, Duration)

Adapter.Touch(Location)

Adapter.TouchWithoutBoundsCheck(Location)

Adapter.Touch(int, Location, Duration)

Adapter.TouchWithoutBoundsCheck(int, Location, Duration)

Adapter.LongTouch()

Adapter.LongTouch(Duration)

Adapter.LongTouch(int, int)

Adapter.LongTouchWithoutBoundsCheck(int, int)

Adapter.LongTouch(int, int, Duration)

Adapter.LongTouchWithoutBoundsCheck(int, int, Duration)

Adapter.LongTouch(double, double)

Adapter.LongTouchWithoutBoundsCheck(double, double)

Adapter.LongTouch(double, double, Duration)

Adapter.LongTouchWithoutBoundsCheck(double, double, Duration)

Adapter.LongTouch(Location)

Adapter.LongTouchWithoutBoundsCheck(Location)

Adapter.LongTouch(Location, Duration)

Adapter.LongTouchWithoutBoundsCheck(Location, Duration)

Adapter.Swipe(GestureDirection, Distance)

Adapter.Swipe(Location, GestureDirection, Distance, Duration, int)

Adapter.SwipeWithoutBoundsCheck(Location, GestureDirection, Distance, Duration, int)

Adapter.DoubleTap()

Adapter.DoubleTap(int, int)

Adapter.DoubleTapWithoutBoundsCheck(int, int)

Adapter.DoubleTap(double, double)

Adapter.DoubleTapWithoutBoundsCheck(double, double)

Adapter.DoubleTap(Location)

Adapter.DoubleTapWithoutBoundsCheck(Location)

Adapter.TouchStart(int, int)

Adapter.TouchStartWithoutBoundsCheck(int, int)

Adapter.TouchStart(double, double)

Adapter.TouchStartWithoutBoundsCheck(double, double)

Adapter.TouchStart(Location)

Adapter.TouchStartWithoutBoundsCheck(Location)

Adapter.TouchStart(int, Location)

Adapter.TouchStartWithoutBoundsCheck(int, Location)

Adapter.TouchEnd(int, int)

Adapter.TouchEndWithoutBoundsCheck(int, int)

Adapter.TouchEnd(double, double)

Adapter.TouchEndWithoutBoundsCheck(double, double)

Adapter.TouchEnd(Location)

Adapter.TouchEndWithoutBoundsCheck(Location)

Adapter.TouchEnd(int, Location)

Adapter.TouchEndWithoutBoundsCheck(int, Location)

Adapter.TouchEnd(int, Location, Duration)

Adapter.TouchEndWithoutBoundsCheck(int, Location, Duration)

Adapter.TouchEnd(Location, Duration)

Adapter.TouchEndWithoutBoundsCheck(Location, Duration)

Adapter.TouchMove(int, int)

Adapter.TouchMoveWithoutBoundsCheck(int, int)

Adapter.TouchMove(int, int, Duration)

Adapter.TouchMoveWithoutBoundsCheck(int, int, Duration)

Adapter.TouchMove(double, double)

Adapter.TouchMoveWithoutBoundsCheck(double, double)

Adapter.TouchMove(double, double, Duration)

Adapter.TouchMoveWithoutBoundsCheck(double, double, Duration)

Adapter.TouchMove(int, Location)

Adapter.TouchMoveWithoutBoundsCheck(int, Location)

Adapter.TouchMove(int, Location, Duration)

Adapter.TouchMoveWithoutBoundsCheck(int, Location, Duration)

Adapter.TouchMove(Location)

Adapter.TouchMoveWithoutBoundsCheck(Location)

Adapter.TouchMove(Location, Duration)

Adapter.TouchMoveWithoutBoundsCheck(Location, Duration)

Adapter.MouseDown(MouseButtons)

Adapter.MouseUp(MouseButtons)

Adapter.GetAttributeValue<T>(string)

Adapter.DefaultSearchTimeout

Adapter.TimeoutFactor

Adapter.Element

Adapter.DefaultUseEnsureVisible

Adapter.UseEnsureVisible

Adapter.Children

Adapter.Parent

Adapter.FlavorName

Adapter.ScreenRectangle

Adapter.Visible

Adapter.HasFocus

Adapter.Enabled

Adapter.IsSnapshot

Adapter.Valid

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Constructors

Host()

Creates a new Host adapter instance. This constructor is used internally by the Ranorex Core Framework for performance issues!

protected Host()

Host(Element)

Creates a new Host adapter instance.

public Host(Element element)

Parameters

element Element

The element to create the adapter for.

Exceptions

NullReferenceException

If element is null.

CapabilityNotSupportedException

If the element does not support the capabilities required by this adapter.

Properties

AvailableHosts

Get available hosts.

public static IEnumerable<string> AvailableHosts { get; }

Property Value

IEnumerable<string>

Remarks

The values returned represents all endpoints that can be set as the new element engine root. The first element in this collection will always be 'Localhost'. If there are other endpoints configured these will be appended at the end of the enumerable. The list is not sorted in any specific way. The endpoints returned by this property may change at any time.

Current

Gets the current host element. Use Ranore.Core.ElementEngine.Root to switch the current host. By default the current host is the local host.

public static IHost Current { get; }

Property Value

IHost

The current host element.

CurrentHost

Gets the name of the current active host (automation root)

public static string CurrentHost { get; }

Property Value

string

Display name of the currently active host

Remarks

If a remote host is active the display name of that remote host will be returned. By default 'localhost' will be returned.

this[string]

Gets the Form with the specified title, process name or process id.

public Form this[string appText] { get; }

Parameters

appText string

Property Value

Form

The matching application form.

Local

Gets the local host element.

public static Host Local { get; }

Property Value

Host

The local host element.

MachineName

The network name of the machine Ranorex is running on.

public virtual string MachineName { get; }

Property Value

string

OSEdition

The Windows edition of the machine running Ranorex.

public virtual string OSEdition { get; }

Property Value

string

OSVersion

The operating system version of the machine running Ranorex.

public virtual string OSVersion { get; }

Property Value

string

ProcessArchitecture

The bit width architecture used by the current process.

public virtual string ProcessArchitecture { get; }

Property Value

string

RanorexVersion

The version of the Ranorex Framework in use.

public virtual string RanorexVersion { get; }

Property Value

string

RemoteSession

True if the current user session is a remote session, i.e. operated via the remote desktop protocol.

public virtual bool RemoteSession { get; }

Property Value

bool

RequiredCapabilities

Capabilities required by the adapter implementation.

protected override string[] RequiredCapabilities { get; }

Property Value

string[]

RuntimeVersion

The version of the .NET Runtime currently running Ranorex.

public virtual string RuntimeVersion { get; }

Property Value

string

UserName

The login name of the user who is running Ranorex.

public virtual string UserName { get; }

Property Value

string

VirtualMachineManufacturer

The manufacturer of the virtual machine running the operating system.

public virtual string VirtualMachineManufacturer { get; }

Property Value

string

Methods

ActivateWindowsApp(string, string)

Activates the windows app with the specified app user model ID.

public void ActivateWindowsApp(string appId, string appFamilyName)

Parameters

appId string

The ID of the app.

appFamilyName string

The family name of the app.

Remarks

A timeout of one minute is used (see ActivateWindowsApp(string, string, Duration)).

ActivateWindowsApp(string, string, Duration)

Activates the windows app with the specified app user model ID.

public void ActivateWindowsApp(string appId, string appFamilyName, Duration timeout)

Parameters

appId string

The ID of the app.

appFamilyName string

The family name of the app.

timeout Duration

A timeout specifying how long the app launcher process needs to stay open after activation of the app (see remarks).

Remarks

To automate Windows apps a process needs to be elevated, however, Windows apps can only be activated from a non-elevated process. Therefore, This methods starts a new non-elevated process that activates the Windows app.

For some applications, the activation process needs to stay alive until the activated app is fully loaded. The timeout argument determines how long the activation process should stay alive after activating the Windows app.

ActivateWindowsApp(string, string, Duration, string)

Activates the windows app with the specified app user model ID and arguments.

public void ActivateWindowsApp(string appId, string appFamilyName, Duration timeout, string arguments)

Parameters

appId string

The ID of the app.

appFamilyName string

The family name of the app.

timeout Duration

A timeout specifying how long the app launcher process needs to stay open after activation of the app (see remarks).

arguments string

Arguments passed to the app on activation. Depending on the implementation of the app, these arguments may only be available when the app is currently not running.

Remarks

To automate Windows apps a process needs to be elevated, however, Windows apps can only be activated from a non-elevated process. Therefore, This methods starts a new non-elevated process that activates the Windows app.

For some applications, the activation process needs to stay alive until the activated app is fully loaded. The timeout argument determines how long the activation process should stay alive after activating the Windows app.

ActivateWindowsApp(string, string, string)

Activates the windows app with the specified app user model ID and arguments.

public void ActivateWindowsApp(string appId, string appFamilyName, string arguments)

Parameters

appId string

The ID of the app.

appFamilyName string

The family name of the app.

arguments string

Arguments passed to the app on activation. Depending on the implementation of the app, these arguments may only be available when the app is currently not running.

Remarks

To automate Windows apps a process needs to be elevated, however, Windows apps can only be activated from a non-elevated process. Therefore, This methods starts a new non-elevated process that activates the Windows app.

A timeout of one minute is used (see ActivateWindowsApp(string, string, Duration)).

ClearBrowserCache(string)

Clears the cache of the specified browser.

public void ClearBrowserCache(string browserName)

Parameters

browserName string

The name of the browser where the cache should be cleared. Can either be "firefox", "ie" or "chrome".

ClearBrowserCache(string, string)

Clears the cache of the specified browser.

public void ClearBrowserCache(string browserName, string userProfile)

Parameters

browserName string

The name of the browser where the cache should be cleared. Can either be "firefox", "ie" or "chrome".

userProfile string

User profile to clear cache. Only supported for Firefox and Chrome.

ClearBrowserCookies(string)

Deletes all cookies from specified browser. Warning: Stored passwords or other important information will be deleted.

public void ClearBrowserCookies(string browserName)

Parameters

browserName string

The name of the browser where the cookies should be deleted. Can either be "firefox", "ie" or "chrome".

ClearBrowserCookies(string, string)

Deletes all cookies from specified browser. Warning: Stored passwords or other important information will be deleted.

public void ClearBrowserCookies(string browserName, string userProfile)

Parameters

browserName string

The name of the browser where the cookies should be deleted. Can either be "firefox", "ie" or "chrome".

userProfile string

User profile to delete cookies. Only supported for Firefox and Chrome.

CloseApplication(Element)

Closes an application or web page which contains the specified element.

public void CloseApplication(Element containedElement)

Parameters

containedElement Element

The element whose parent application to close.

CloseApplication(Element, Duration)

Closes an application or web page which contains the specified element. If the application does not react to the close request within the specified grace period, the application process is killed.

public bool CloseApplication(Element containedElement, Duration gracePeriod)

Parameters

containedElement Element

The element whose parent application to close.

gracePeriod Duration

A grace period before the process is killed (does not apply to mobile apps).

Returns

bool

Returns true if the application has closed within the grace period, otherwise false.

Remarks

Setting the grace period to zero causes the application's process not to be killed.

Exceptions

ArgumentOutOfRangeException

If gracePeriod is negative.

CloseApplication(int)

Closes an application with the specified process ID by trying to close its main window.

public void CloseApplication(int processId)

Parameters

processId int

The process ID of the application to close.

CloseApplication(int, Duration)

Closes an application with the specified process ID by trying to close its main window.

public bool CloseApplication(int processId, Duration gracePeriod)

Parameters

processId int

The process ID of the application to close.

gracePeriod Duration

A grace period before the process is killed (does not apply to mobile apps).

Returns

bool

Returns true if the application has closed within the grace period, otherwise false.

Remarks

Setting the grace period to zero causes the application's process not to be killed.

Exceptions

ArgumentOutOfRangeException

If gracePeriod is negative.

CloseApplications(string)

Closes an application with a given process name.

public void CloseApplications(string processName)

Parameters

processName string

The process name of the application to close.

CloseBrowser(string)

Closes any open browser processes with the given name by sending a close message to its main window.

public bool CloseBrowser(string browserName)

Parameters

browserName string

The name of the browser to close. Can either be "firefox", "ie", "chrome" or "edge".

Returns

bool

DeployIosApp(string, string, string)

Deploys an iOS app archive to the specified device.

public void DeployIosApp(string device, string archivePath, string appId)

Parameters

device string

The device name

archivePath string

Path to the app archive (*.ipa)

appId string

The application id e.g. (ranorex.RxBrowser)

FromElement(Element)

Converts an Element to an instance of this class.

public static Host FromElement(Element element)

Parameters

element Element

The element to convert.

Returns

Host

The Host.

Exceptions

ArgumentNullException

If element is null.

CapabilityNotSupportedException

If the element does not support the capabilities required by this adapter.

FromPath(string)

Converts a string to an instance of this class by searching the root.

public static Host FromPath(string path)

Parameters

path string

The search path.

Returns

Host

The Host.

Remarks

The DefaultSearchTimeout is used to search for the specified path.

Exceptions

ArgumentNullException

If path is null.

RxPathException

If the specified path is not valid.

ElementNotFoundException

If no element is found.

CapabilityNotSupportedException

If the element does not support the capabilities required by this adapter.

GetApplicationForm(Process)

Gets the main Form of a process.

public Form GetApplicationForm(Process process)

Parameters

process Process

The process to get the main Form from.

Returns

Form

A Form belonging to the specified Process.

Remarks

If more Form instances are found for the process, the last Form found is returned (to avoid popups).

Exceptions

ArgumentNullException

If process is null.

RanorexException

If getting the process Id from process fails.

ElementNotFoundException

If no Form belonging to the specified process is found within the DefaultSearchTimeout.

GetApplicationForm(Process, Duration)

Gets the main Form of a process.

public Form GetApplicationForm(Process process, Duration timeout)

Parameters

process Process

The process to get the main Form from.

timeout Duration

The time to keep searching for a Form instance belonging to the process.

Returns

Form

A Form belonging to the specified Process.

Remarks

If more Form instances are found for the process, the last Form found is returned (to avoid popups).

Exceptions

ArgumentNullException

If process is null.

RanorexException

If getting the process Id from process fails.

ElementNotFoundException

If no Form belonging to the specified process is found within the timeout.

GetApplicationForm(int, Duration)

Gets the main Form of a process.

public Form GetApplicationForm(int processId, Duration timeout)

Parameters

processId int

The ID of the process to get the main Form from.

timeout Duration

The time to keep searching for a Form instance belonging to the process.

Returns

Form

A Form belonging to the specified process ID.

Remarks

If more Form instances are found for the process ID, the last Form found is returned (to avoid popups).

Exceptions

ElementNotFoundException

If no Form belonging to the specified process ID is found within the timeout.

GetDevToolsSession()

Gets devtools session.

public IDevToolsSession GetDevToolsSession()

Returns

IDevToolsSession

InstrumentAndDeployAndroidApp(string, string, bool, DeploymentModes, Duration)

Can be invoked to instrument/deploy an Android app to a configured device.

public void InstrumentAndDeployAndroidApp(string deviceName, string sourceApkFilePath, bool instrument, Host.DeploymentModes deployMode, Duration timeout)

Parameters

deviceName string

The display name of the device on that the app shall be deployed

sourceApkFilePath string

File path to the android application that shall be instrumented/deployed (*.apk)

instrument bool

If set to true Ranorex will instrument the application prior to deployment. If set to false Ranorex assumes the APK file is instrumented already. The application will simply be deployed to the device. If this parameter is set to false but the *.apk file you try to deploy is not instrumented Ranorex will not be able to communicate with the device correctly.

deployMode Host.DeploymentModes

States how the deployment shall be done. Possible modes are NoDeploy, WiFi and USB. If NoDeploy is passed no deployment will be done (just instrument the APK file). The instrumented file then can be found in [Drive]:\Users[UserName]\Documents\Ranorex\InstrumentedApk[APKName]-instrumented.apk. When WiFi is selected the apk file will be deployed over your wireless network (RanorexService needs to be installed). When USB is selected the app will be deployed over USB cable to your connected device (deployment can be done without installed device service; but for automation the service is still required!). When Auto is selected the app will be deployed using the mode that was used to add the device.

timeout Duration

After the specified timeout the operation aborts (timeout can happen when no connection can be established, instrumentation fails...). Depending on the size of your app, instrumentation and deployment can take quite some time. Instrumentation and deployment on low spec PCs can take up to about 10 minutes.

InstrumentAndDeployAndroidApp(string, string, bool, DeploymentModes, Duration, InstrumentApkOptions)

Can be invoked to instrument/deploy an Android app to a configured device.

public void InstrumentAndDeployAndroidApp(string deviceName, string sourceApkFilePath, bool instrument, Host.DeploymentModes deployMode, Duration timeout, InstrumentApkOptions options)

Parameters

deviceName string

The display name of the device on that the app shall be deployed

sourceApkFilePath string

File path to the android application that shall be instrumented/deployed (*.apk)

instrument bool

If set to true Ranorex will instrument the application prior to deployment. If set to false Ranorex assumes the APK file is instrumented already. The application will simply be deployed to the device. If this parameter is set to false but the *.apk file you try to deploy is not instrumented Ranorex will not be able to communicate with the device correctly.

deployMode Host.DeploymentModes

States how the deployment shall be done. Possible modes are NoDeploy, WiFi and USB. If NoDeploy is passed no deployment will be done (just instrument the APK file). The instrumented file then can be found in [Drive]:\Users[UserName]\Documents\Ranorex\InstrumentedApk[APKName]-instrumented.apk. When WiFi is selected the apk file will be deployed over your wireless network (RanorexService needs to be installed). When Usb is selected the app will be deployed over USB cable to your connected device (deployment can be done without installed device service; but for automation the service is still required!). When Auto is selected the app will be deployed using the mode that was used to add the device.

timeout Duration

Specifies the timeout for each operation in the instrument and deploy process. After the specified timeout the operation aborts (timeout can happen when no connection can be established, instrumentation fails...). Depending on the size of your app, instrumentation and deployment can take quite some time. Instrumentation and deployment on low spec PCs can take up to about 10 minutes.

options InstrumentApkOptions

Advanced instrumentation options. Ranorex.Core.Remoting.RecordItems.InstrumentApkOptions for more information what the specific options are.

Exceptions

NullReferenceException

Will be throw if options is null.

InstrumentAndDeployAndroidApp(string, string, bool, DeploymentModes, Duration, bool, bool)

Can be invoked to instrument/deploy an Android app to a configured device.

public void InstrumentAndDeployAndroidApp(string deviceName, string sourceApkFilePath, bool instrument, Host.DeploymentModes deployMode, Duration timeout, bool treeSimplification, bool fullImageComparison)

Parameters

deviceName string

The display name of the device on that the app shall be deployed

sourceApkFilePath string

File path to the android application that shall be instrumented/deployed (*.apk)

instrument bool

If set to true Ranorex will instrument the application prior to deployment. If set to false Ranorex assumes the APK file is instrumented already. The application will simply be deployed to the device. If this parameter is set to false but the *.apk file you try to deploy is not instrumented Ranorex will not be able to communicate with the device correctly.

deployMode Host.DeploymentModes

States how the deployment shall be done. Possible modes are NoDeploy, WiFi and USB. If NoDeploy is passed no deployment will be done (just instrument the APK file). The instrumented file then can be found in [Drive]:\Users[UserName]\Documents\Ranorex\InstrumentedApk[APKName]-instrumented.apk. When WiFi is selected the apk file will be deployed over your wireless network (RanorexService needs to be installed). When Usb is selected the app will be deployed over USB cable to your connected device (deployment can be done without installed device service; but for automation the service is still required!). When Auto is selected the app will be deployed using the mode that was used to add the device.

timeout Duration

After the specified timeout the operation aborts (timeout can happen when no connection can be established, instrumentation fails...). Depending on the size of your app, instrumentation and deployment can take quite some time. Instrumentation and deployment on low spec PCs can take up to about 10 minutes.

treeSimplification bool

When set to false no post processing of the UI-Tree takes place. This results in a larger UI-Tree which could be useful for automating 3rd party Android controls. (See: https://www.ranorex.com/help/latest/android-testing#AndroidTesting-FICandtreesimplification)

fullImageComparison bool

When set to true more robust image comparison is used to determine resource id's for images. This option decreases startup performance. (See: https://www.ranorex.com/help/latest/android-testing#AndroidTesting-FICandtreesimplification)

InstrumentAndDeployIosApp(string, string, string, InstrumentIpaOptions)

Instrument and deploy an iOS app.

public void InstrumentAndDeployIosApp(string device, string archivePath, string appId, InstrumentIpaOptions options)

Parameters

device string

The device name

archivePath string

Path to the app archive (*.ipa)

appId string

The application id e.g. (ranorex.RxBrowser)

options InstrumentIpaOptions

Advanced instrumentation options. InstrumentIpaOptions for more information what the specific options are.

KillApplication(Element)

Kills the process which contains the specified element.

public void KillApplication(Element containedElement)

Parameters

containedElement Element

The element whose parent application to kill.

KillApplication(int)

Kills a process which the specified process ID.

public void KillApplication(int processId)

Parameters

processId int

The ID of the process to kill.

KillApplications(string)

Kills all applications with the specified process name.

public void KillApplications(string processName)

Parameters

processName string

The process name of the applications to kill.

KillBrowser(string)

Kills any open browser processes with the given name.

public void KillBrowser(string browserName)

Parameters

browserName string

The name of the browser to close. Can either be "firefox", "ie", "chrome" or "edge".

MakeCurrentHost(string)

Activates the given host that will then be used as the new host.

public static void MakeCurrentHost(string host)

Parameters

host string

The host to activate. Null or whitespace only string will reset the current host to 'Localhost'.

Remarks

The current host will produce the root flavor element. Use AvailableHosts to to get a list of all available hosts.

OpenBrowser(string)

Opens a web page in the default browser.

public int OpenBrowser(string url)

Parameters

url string

The URL of the web page to open.

Returns

int

The process ID of the browser.

OpenBrowser(string, string)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie", "chrome", "chromium" or "edge".

Returns

int

The process ID of the browser.

OpenBrowser(string, string, bool)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName, bool killExisting)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie" or "chrome".

killExisting bool

Specifies whether any running browser instances should be closed first.

Returns

int

The process ID of the browser.

OpenBrowser(string, string, bool, bool)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName, bool killExisting, bool maximized)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie", "chrome", "chromium" or "edge".

killExisting bool

Specifies whether any running browser instances should be closed first.

maximized bool

Specifies whether the started browser instances should be started maximized.

Returns

int

The process ID of the browser.

OpenBrowser(string, string, string, bool, bool)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName, string browserArgs, bool killExisting, bool maximized)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie", "chrome", "chromium" or "edge".

browserArgs string

Additional command line arguments to pass to the browser.

killExisting bool

Specifies whether any running browser instances should be closed first.

maximized bool

Specifies whether the started browser instances should be started maximized.

Returns

int

The process ID of the browser.

OpenBrowser(string, string, string, bool, bool, bool, bool, bool)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName, string browserArgs, bool killExisting, bool maximized, bool clearCache, bool incognitoMode, bool clearCookies)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie", "chrome", "chromium" or "edge".

browserArgs string

Additional command line arguments to pass to the browser.

killExisting bool

Specifies whether any running browser instances should be closed first.

maximized bool

Specifies whether the started browser instances should be started maximized.

clearCache bool

Specifies whether cache should be cleared on browser start.

incognitoMode bool

Specifies whether the browser should start in incognito mode

clearCookies bool

Specifies whether cookies should be deleted on browser start.

Returns

int

The process ID of the browser.

OpenBrowser(string, string, string, bool, bool, bool, bool, bool, bool)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName, string browserArgs, bool killExisting, bool maximized, bool clearCache, bool incognitoMode, bool clearCookies, bool instrument)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie", "chrome", "chromium", "edge" or "edgechromium".

browserArgs string

Additional command line arguments to pass to the browser.

killExisting bool

Specifies whether any running browser instances should be closed first.

maximized bool

Specifies whether the started browser instances should be started maximized.

clearCache bool

Specifies whether cache should be cleared on browser start.

incognitoMode bool

Specifies whether the browser should start in incognito mode

clearCookies bool

Specifies whether cookies should be deleted on browser start.

instrument bool

Specifies whether the browser should be instrumented before browser start.

Returns

int

The process ID of the browser.

OpenBrowser(string, string, string, bool, bool, bool, bool, bool, bool, bool)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName, string browserArgs, bool killExisting, bool maximized, bool clearCache, bool clearCodeCache, bool clearServiceWorker, bool incognitoMode, bool clearCookies)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie", "chrome", "chromium" or "edge".

browserArgs string

Additional command line arguments to pass to the browser.

killExisting bool

Specifies whether any running browser instances should be closed first.

maximized bool

Specifies whether the started browser instances should be started maximized.

clearCache bool

Specifies whether cache should be cleared on browser start.

clearCodeCache bool

Specifies whether code cache should be cleared on browser start.

clearServiceWorker bool

Specifies whether Service Worker folder should be cleared on browser start.

incognitoMode bool

Specifies whether the browser should start in incognito mode

clearCookies bool

Specifies whether cookies should be deleted on browser start.

Returns

int

The process ID of the browser.

OpenBrowser(string, string, string, bool, bool, bool, bool, bool, bool, bool, bool)

Opens a web page in the specified browser.

public int OpenBrowser(string url, string browserName, string browserArgs, bool killExisting, bool maximized, bool clearCache, bool clearCodeCache, bool clearServiceWorker, bool incognitoMode, bool clearCookies, bool instrument)

Parameters

url string

The URL of the web page to open.

browserName string

The name of the browser to open. Can either be "firefox", "ie", "chrome", "chromium", "edge" or "edgechromium".

browserArgs string

Additional command line arguments to pass to the browser.

killExisting bool

Specifies whether any running browser instances should be closed first.

maximized bool

Specifies whether the started browser instances should be started maximized.

clearCache bool

Specifies whether cache should be cleared on browser start.

clearCodeCache bool

Specifies whether code cache should be cleared on browser start.

clearServiceWorker bool

Specifies whether Service Worker folder should be cleared on browser start.

incognitoMode bool

Specifies whether the browser should start in incognito mode

clearCookies bool

Specifies whether cookies should be deleted on browser start.

instrument bool

Specifies whether the browser should be instrumented before browser start.

Returns

int

The process ID of the browser.

RunApplication(string)

Runs an application with the specified filename.

public int RunApplication(string fileName)

Parameters

fileName string

The file name of the application to run.

Returns

int

The process ID of the started application.

Remarks

Using an AppUserModelId (familyName!appName) instead of a file name activates a Windows 8 App instead.

Exceptions

RanorexException

Thrown if the application cannot be started.

RunApplication(string, string)

Runs an application with the specified filename, passing the specified arguments.

public int RunApplication(string fileName, string arguments)

Parameters

fileName string

The name of the application to run.

arguments string

The arguments to pass to the application on startup.

Returns

int

The process ID of the started application.

Remarks

Using an AppUserModelId (familyName!appName) instead of a file name activates a Windows 8 App instead.

Exceptions

RanorexException

Thrown if the application cannot be started.

RunApplication(string, string, string)

Runs an application with the specified filename, passing the specified arguments and setting the specified working directory.

public int RunApplication(string fileName, string arguments, string workingDirectory)

Parameters

fileName string

The name of the application to run.

arguments string

The arguments to pass to the application on startup.

workingDirectory string

The working directory to use for the started application.

Returns

int

The process ID of the started application.

Remarks

Using an AppUserModelId (familyName!appName) instead of a file name activates a Windows 8 App instead.

Exceptions

RanorexException

Thrown if the application cannot be started.

RunApplication(string, string, string, bool)

Runs an application with the specified filename, passing the specified arguments and setting the specified working directory.

public int RunApplication(string fileName, string arguments, string workingDirectory, bool maximized)

Parameters

fileName string

The name of the application to run.

arguments string

The arguments to pass to the application on startup.

workingDirectory string

The working directory to use for the started application.

maximized bool

Specifies whether the application should be started with a normal or maximized main window.

Returns

int

The process ID of the started application.

Remarks

Using an AppUserModelId (familyName!appName) instead of a file name activates a Windows 8 App instead.

Exceptions

RanorexException

Thrown if the application cannot be started.

RunApplication(string, string, string, bool, RunAppFlags)

Runs an application with the specified filename, passing the specified arguments and setting the specified working directory.

public int RunApplication(string fileName, string arguments, string workingDirectory, bool maximized, RunAppFlags runFlags)

Parameters

fileName string

The name of the application to run.

arguments string

The arguments to pass to the application on startup.

workingDirectory string

The working directory to use for the started application.

maximized bool

Specifies whether the application should be started with a normal or maximized main window.

runFlags RunAppFlags

Specifies special startup behavior to use when running an application.

Returns

int

The process ID of the started application.

Remarks

Using an AppUserModelId (familyName!appName) instead of a file name activates a Windows 8 App instead.

Exceptions

RanorexException

Thrown if the application cannot be started.

RunMobileApp(string, string)

Starts an app on a mobile device. This operation only works for devices that were configured trough the Ranorex user interface. This operation also works when the app is running on the device already. In that case the running app will be closed and started again to reset it into the initial state. Only apps that were instrumented by the Ranorex system can be started by Ranorex.

public void RunMobileApp(string deviceDisplayName, string appName)

Parameters

deviceDisplayName string

The name you configured for your device. If no device with that name exists or is not connected (that means Ranorex isn't able to communicate with the corresponding device) the operation will fail.

appName string

The app that shall be started. This has to be the unique application identifier. E.g. for android devices such an app identifier looks like 'ranorex.android.DemoGui'.

Exceptions

ArgumentException

If deviceDisplayName or appName is null or empty.

RunMobileApp(string, string, bool)

Starts an app on a mobile device. This operation only works for devices that were configured trough the Ranorex user interface. This operation also works when the app is running on the device already. In that case the running app will either be closed and started again to reset it into the initial state or only brought to the foreground depending on the 'resetInitialState' parameter. Only apps that were instrumented by the Ranorex system can be started by Ranorex.

public void RunMobileApp(string deviceDisplayName, string appName, bool resetInitialState)

Parameters

deviceDisplayName string

The name you configured for your device. If no device with that name exists or is not connected (that means Ranorex isn't able to communicate with the corresponding device) the operation will fail.

appName string

The app that shall be started. This has to be the unique application identifier. E.g. for android devices such an app identifier looks like 'ranorex.android.DemoGui'.

resetInitialState bool

Indicates if the app should be restarted on launch or just brought to the foreground in case the app is already running.

Exceptions

ArgumentException

If deviceDisplayName or appName is null or empty.

RunMobileApp(string, string, bool, string)

Starts an app on a mobile device. This operation only works for devices that were configured trough the Ranorex user interface. This operation also works when the app is running on the device already. In that case the running app will either be closed and started again to reset it into the initial state or only brought to the foreground depending on the 'resetInitialState' parameter. Only apps that were instrumented by the Ranorex system can be started by Ranorex.

public void RunMobileApp(string deviceDisplayName, string appName, bool resetInitialState, string url)

Parameters

deviceDisplayName string

The name you configured for your device. If no device with that name exists or is not connected (that means Ranorex isn't able to communicate with the corresponding device) the operation will fail.

appName string

The app that shall be started. This has to be the unique application identifier. E.g. for android devices such an app identifier looks like 'ranorex.android.DemoGui'.

resetInitialState bool

Indicates if the app should be restarted on launch or just brought to the foreground in case the app is already running.

url string

The url the RxServiceApp should open a browser.

Exceptions

ArgumentException

If deviceDisplayName or appName is null or empty.

Operators

implicit operator Host(Element)

Implicitly converts an Element to an instance of this class.

public static implicit operator Host(Element element)

Parameters

element Element

The element to convert.

Returns

Host

The Host.

Exceptions

ArgumentNullException

If element is null.

CapabilityNotSupportedException

If the element does not support the capabilities required by this adapter.

implicit operator Host(string)

Implicitly converts a string to an instance of this class by searching the root.

public static implicit operator Host(string path)

Parameters

path string

The search path.

Returns

Host

The Host.

Remarks

The DefaultSearchTimeout is used to search for the specified path.

Exceptions

ArgumentNullException

If path is null.

RxPathException

If the specified path is not valid.

ElementNotFoundException

If no element is found.

CapabilityNotSupportedException

If the element does not support the capabilities required by this adapter.