Table of Contents

Basic Setup and Initialization

This guide walks you through setting up your development environment and initializing the Ranorex runtime for API-based automation.

Development Environment Setup

Requirements

  • Ranorex Studio (version 10.x or later)
  • Visual Studio (2019 or later) or Visual Studio Code
  • .NET Framework 4.7.2 or later
  • Valid Ranorex License

Add Ranorex assemblies to your Visual Studio project

  1. Create a new C# project Create a new Console Application project or open an existing one.

    File > New > Project > Visual C# > Console App (.NET Framework)

  2. Add Ranorex references: In the Solution Explorer, right-click References > Add Reference.

  3. Click Browse and browse to the \Bin\ folder of your Ranorex Studio installation, by default: C:\Program Files (x86)\Ranorex\Studio\Bin

  4. Add the following:

    • Ranorex.Bootstrapper
    • Ranorex.Core
    • Ranorex.Core.Resolver
    • all Ranorex.Plugin .dll files

If you already know your test won't use a particular plugin .dll, you can exclude it.

Copy Local must be set to True for Ranorex.Core.Resolver. For all others, you can set it as desired.

Ranorex Runtime Initialization

Basic Initialization

Every Ranorex automation script must initialize the runtime before performing any operations:

using System;
using System.Runtime.CompilerServices;
using System.Configuration;
using Ranorex.Core.Resolver;
using Ranorex;
using Ranorex.Core;
using Ranorex.Core.Reporting;
using Ranorex.Core.Testing;

namespace BasicSetupExample
{
    class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            try
            {
                // Basic initialization pattern
                InitResolver();
                RanorexInit();
                RunBasicAutomation();
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Application error: {ex.Message}");
                Environment.ExitCode = 1;
            }
        }

        [MethodImpl(MethodImplOptions.NoInlining)]
        private static void InitResolver()
        {
            Ranorex.Core.Resolver.AssemblyLoader.Initialize();
        }

        [MethodImpl(MethodImplOptions.NoInlining)]
        private static void RanorexInit()
        {
            // Basic Ranorex setup - core libraries will be loaded automatically
            Console.WriteLine("Ranorex core libraries loaded");
        }

        [MethodImpl(MethodImplOptions.NoInlining)]
        private static void RunBasicAutomation()
        {
            // Your automation code goes here
            Console.WriteLine("Ranorex initialized successfully!");
            Console.WriteLine("Ready for automation operations");
        }
    }
}

Configuration Loading Example

You can load and use configuration settings from your app.config file:

/// <summary>
/// Demonstrates loading configuration from App.config.
/// </summary>
static void ConfigurationExample()
{
    try
    {
        Console.WriteLine("Loading configuration from App.config...");
        LoadConfiguration();
        Console.WriteLine("✓ Configuration loading completed successfully");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"✗ Configuration loading failed: {ex.Message}");
    }
}

/// <summary>
/// Loads configuration settings from app.config file.
/// </summary>
static void LoadConfiguration()
{
    try
    {
        Console.WriteLine("  - Reading configuration values...");

        // Read configuration values with defaults
        var timeoutConfig = ConfigurationManager.AppSettings["Ranorex.Core.DefaultTimeout"];
        if (int.TryParse(timeoutConfig, out int timeout))
        {
            Console.WriteLine($"  - Default timeout from config: {timeout}ms");
        }

        var logLevelConfig = ConfigurationManager.AppSettings["Ranorex.Core.LogLevel"];
        if (!string.IsNullOrEmpty(logLevelConfig))
        {
            Console.WriteLine($"  - Log level from config: {logLevelConfig}");
        }

        var highlightConfig = ConfigurationManager.AppSettings["Ranorex.Core.HighlightElements"];
        if (bool.TryParse(highlightConfig, out bool highlight))
        {
            Console.WriteLine($"  - Element highlighting from config: {highlight}");
        }

        var browserConfig = ConfigurationManager.AppSettings["Ranorex.Plugin.Web.DefaultBrowser"];
        if (!string.IsNullOrEmpty(browserConfig))
        {
            Console.WriteLine($"  - Default browser from config: {browserConfig}");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"  ⚠ Configuration loading failed: {ex.Message}");
        Console.WriteLine("  - Using default settings");
    }
}

Configuration Files

App.config Setup

Create an app.config file to manage settings:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <!-- Ranorex Settings -->
    <add key="Ranorex.Core.DefaultTimeout" value="10000" />
    <add key="Ranorex.Core.LogLevel" value="Info" />
    <add key="Ranorex.Core.HighlightElements" value="true" />
    
    <!-- WebDriver Settings -->
    <add key="Ranorex.Plugin.Web.DefaultBrowser" value="Chrome" />
    <add key="Ranorex.Plugin.Web.BrowserTimeout" value="30000" />
  </appSettings>
  
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

Loading Configuration

using System.Configuration;

// Read configuration values
var timeout = int.Parse(ConfigurationManager.AppSettings["Ranorex.Core.DefaultTimeout"] ?? "10000");
var logLevel = ConfigurationManager.AppSettings["Ranorex.Core.LogLevel"] ?? "Info";

// Apply configuration
Host.Current.DefaultTimeout = TimeSpan.FromMilliseconds(timeout);

Setup Verification

Test your setup with this comprehensive verification method that handles common development environment limitations:

/// <summary>
/// Comprehensive setup verification as described in the documentation.
/// This verifies that Ranorex is properly configured and functional.
/// Note: Some features require full Ranorex Studio installation with native components.
/// </summary>
static void SetupVerificationExample()
{
    try
    {
        Console.WriteLine("Running setup verification...");

        // Test basic Ranorex functionality
        Console.WriteLine("✓ Ranorex assemblies loaded successfully");
        Console.WriteLine("✓ Ranorex core libraries accessible");

        // Test timing functionality (this always works)
        Console.WriteLine("  - Testing timing functionality...");
        var startTime = System.DateTime.Now;
        Delay.Milliseconds(100);
        var elapsed = System.DateTime.Now - startTime;
        Console.WriteLine($"✓ Timing test completed in {elapsed.TotalMilliseconds:F0}ms");

        // Test reporting functionality (this always works)
        Console.WriteLine("  - Testing reporting functionality...");
        Report.Info("Test report message from basic setup example");
        Console.WriteLine("✓ Reporting system functional");

        // Test element engine access (may fail in dev environment)
        Console.WriteLine("  - Testing element engine availability...");
        TestElementEngineAccess();

        // Test native API access (may fail in dev environment)
        Console.WriteLine("  - Testing native Windows API access...");
        TestNativeApiAccess();

        Console.WriteLine("\n✓ Core setup verification completed successfully!");
        Console.WriteLine("  Ranorex core libraries are properly configured.");
        Console.WriteLine("  For full UI automation, ensure Ranorex Studio is installed.");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"✗ Setup verification failed: {ex.Message}");
        Environment.ExitCode = 1;
    }
}

/// <summary>
/// Tests element engine access - may fail in development environments.
/// </summary>
static void TestElementEngineAccess()
{
    try
    {
        // Try to access element finding capabilities
        var desktop = Host.Local.Find<Unknown>("/");
        Console.WriteLine($"✓ Element engine functional: {desktop.Count} root elements found");
    }
    catch (TypeInitializationException ex)
    {
        Console.WriteLine($"  ⚠ Element engine limited: {ex.InnerException?.Message ?? ex.Message}");
        Console.WriteLine("    This is expected in development environments without full Ranorex installation.");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"  ⚠ Element engine access limited: {ex.Message}");
    }
}

/// <summary>
/// Tests native API access - may fail due to architecture or installation issues.
/// </summary>
static void TestNativeApiAccess()
{
    try
    {
        // Try to access native API functionality
        var forms = Host.Local.Find<Unknown>("/form", TimeSpan.FromSeconds(1));
        Console.WriteLine($"✓ Native API functional: Found {forms.Count} forms/windows");
    }
    catch (System.BadImageFormatException ex)
    {
        Console.WriteLine($"  ⚠ Native API limited: Architecture mismatch ({ex.Message.Split('.')[0]})");
        Console.WriteLine("    This requires matching processor architecture (x86/x64) and full Ranorex installation.");
    }
    catch (TypeInitializationException ex)
    {
        Console.WriteLine($"  ⚠ Native API limited: {ex.InnerException?.Message ?? ex.Message}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"  ⚠ Native API access limited: {ex.GetType().Name}");
    }
}

Next Steps

Now that you have Ranorex properly set up and initialized:

  1. Create Your First Automation Script - Build your first automation
  2. Understanding Element Identification - Learn about RanoreXPath
  3. Working with Repository - Manage UI elements efficiently

Troubleshooting

Common Issues

  • "Ranorex.Core.dll not found": Check that Ranorex is properly installed and referenced
  • License errors: Verify your Ranorex license is valid and accessible
  • Initialization failures: Ensure you have sufficient permissions and no conflicting processes

Getting Help