Upcoming Webinar: Jump Start Your Automated Testing Efforts With Record & Play Save Your Seat

Blog We love to talk!

Feb Thu

Getting Started With The BrowseEmAll Core API

  •  2-11-2016

In this short guide I would like to show you real quick how you can get started with the BrowseEmAll Core API. I will use Visual Studio 2015 Community but any other version will do.

Getting the API

For your convenience we have created a little setup which contains all the necessary files to use the Core API. Please note that you don’t have to install anything on the machines your software will be deployed to. You can download the setup here.

Download the file and install it at a location of your choosing. I will use c:\BrowseEmAllCoreAPI as an example. Of course spaces in the file location are perfectly fine.

Integrating the API

Now we can create a new project in Visual Studio. For this example I will create a simple WinForms application but WPF or a Console application would be fine as well.

We need to add a reference to ‘BrowseEmAll.API.dll‘ to this project. You can find the file in c:\BrowseEmAllCoreAPI\API\BrowseEmAll.API.dll.

Embedding A Browser Instance

Here is the complete code to get a new Chrome instance up and running. I’ll walk you through it line by line after the listing.

using BrowseEmAll.API;
using BrowseEmAll.API.Events;
using BrowseEmAll.API.Models;
using System;
using System.Windows.Forms;

namespace GettingStartedExample
{
    public partial class Form1 : Form
    {
        private BrowserManager manager = new BrowserManager(IntegrationMode.Winforms);

        public Form1()
        {
            InitializeComponent();

            manager.OnBrowserReady += Manager_OnBrowserReady;
        }

        private void Form1_Load(object sender, EventArgs e)
        {
            Control browser = (Control)manager.OpenBrowser(Browser.CHROME48, new BrowserSettings());

            browser.Dock = DockStyle.Fill;
            panelBrowser.Controls.Add(browser);
        }

        private void Manager_OnBrowserReady(object sender, BrowserReadyEventArgs e)
        {
            manager.Navigate(e.BrowserID, "http://www.google.de");
        }
    }
}

As a first step we’ll need to create a new ‘BrowserManager‘ instance. This BrowserManager is the central object which will manage all communication between your code and the different running browsers.

private BrowserManager manager = new BrowserManager(IntegrationMode.Winforms);

The IntegrationMode tells the BrowserManager that you would like to use the browser as a WinForms control. For a Console application you would use the IntegrationMode Standalone where every browser instance is running in a separate process.

In the constructor of the Form we subscribe to the OnBrowserReady event provided by the BrowserManager:

public Form1()
{
    InitializeComponent();

    manager.OnBrowserReady += Manager_OnBrowserReady;
}

The BrowseEmAll Core API is event driven, which means you can subscribe to different events provided by the BrowserManager. The most used events are OnBrowserReady (A browser instance is ready to take any commands) and OnDocumentComplete (A browser instance has finished loading a URL). You can find a list of all event in the documentation.

Lastly we need to tell the BrowserManager to create a new browser instance for us. We will do so in the ‘Load’ event of our Form.

Control browser = (Control)manager.OpenBrowser(Browser.CHROME48, new BrowserSettings());
browser.Dock = DockStyle.Fill;
this.Controls.Add(browser);

As you can see we call the OpenBrowser method to tell the BrowserManager to start a new Chrome48 instance. Because we have chosen the Integration Mode Winforms the manager will return a winforms user control for us to embed in our form. We just need to add the control to our Form.

After the BrowserManager has returned the user control to us it will start up the actual rendering and JavaScript engine for Chrome 48. This can take a few seconds depending on the local machine and the load. The so created browser instance runs directly on the local machine! After the browser instance is ready to go the BrowserManager will fire the OnBrowserReady event to inform you about this. You can now start working with the browser instance. In our example we will navigate to the Google homepage.

private void Manager_OnBrowserReady(object sender, BrowserReadyEventArgs e)
{
    manager.Navigate(e.BrowserID, "http://www.google.de");
}

Please make sure to add the user control to your form otherwise the OnBrowserReady event may not fire for some browser instances.

Running The Example

That was all the code that is necessary to start using the BrowseEmAll Core API. There are 2 more things we need to do to run our small example.

In your project settings make sure to disable the ‘Visual Studio Hosting Process’ under ‘Debug’, otherwise you might get strange errors when running Internet Explorer instances.

Secondly the API needs a few files to run the browsers properly. These are located in the subfolder ‘API’ of the API installation folder. (C:\BrowseEmAllCoreAPI\API in this example). Simply copy the content of this folder in the output folder of our project (bin\Debug).

We can finally run our example. It should open up the form and add our browser instance:

getting-started-example

What now?

Now you are ready to explore more of the functionality of the Core API. Maybe you want to take a Screenshot or execute some JavaScript? You can find more information and examples at the Core API page.

You can download the sample project here.

As always, if you run into any problems feel free to contact our support team at support@browseemall.com.

Photo by Tsahi Levent-Levi

No Comments

Leave a Reply

Your email address will not be published.