Hosting a webpage inside a Windows Form

• Download source files - 87 Kb

Introduction

This article discusses my journey toward having a web page run inside of a WinForm client and fire events back to it. The sample app which is included provides the implementation of this article. While the sample application could have been done in an easier fashion (all ASP.NET for example) the intent is to provide a working model that can implement more difficult designs.

The Application

The application consists of a WinForm application which is broken into two sections:

1. The right side is the web app
2. The left side is the winForm pieces that gets populated based on what was clicked in the web

The application implements the IDocHostUIHandler interface which will allow MSHTML to do callbacks into my code. It then displays the webpage inside the IE container. When a button is clicked, a javascript component is called with a text description of what was clicked on. The javascript passes this data to the external method which will populate the form with data. If data is not found, the purchase button is disabled.

To make the application work on your machine, alter the application config file (SampleEventProgram.exe.config) in the BIN\Release directory and change the path to where the sampleweb application is located on your machine.

The Research

Not being a raw, C++ COM developer - or even knowing much about the internals of the IE engine - I began my deployment by researching on the Internet. The first day I searched the web for anything on putting IE inside a form. I bring this up because it led me to a webpage which appeared to be a BLOG. I read it out of interest to see why the heck it showed up in my search. In it, the author said:

"In my growing years of development, I have had several unanswered questions arise. [...] Why is it so hard to implement a web browser inside a windows form and take control of it?"

I probably should have taken this as a warning, but I plunged forward in my quest. After all, MS had years to improve this proces....right? Over here at CodeProject, I came upon a discussion thread that died with no conclusive help, as well as articles by Wiley Techology Publishing and Nikhil Dabas. The first article was well written, but the most important part of the piece (implementing IDocHostUIHandler and ICustomDoc) were taken offline and done in Delphi! Nikhil's article, however, had a fine discussion on implementing the interface as well as a deployed DLL for the interfaces in his sample application!

However, his deployment for hooking events required that you know the specific controls on the webform and then sink their click events. It also did not allow the web app to send any information back to the winform client. This is great for having the click events dive directly into code. But I needed the HTML object to tell me some information about what was clicked. So while I finally got IDocHostUIHandler implemented, I still did not get my last piece done and working. I was stuck for weeks in a continuous result of 'object null or not an object'.

I had a few hints such as looking into GetExternal and I could SWEAR that a post suggested using window.getExternal in my javascript. Obviously that didn't get me very far since I have since learned that is not a valid javascript call. I also got some suggestions on implementing IDispatch. But nothing really seemed to take the final step of scripting my program.

A lengthy two-day discussion with CP member .S.Rod. finally led to a better understanding and a great assistance in getting everything tied together and working. The most interesting thing with all of this research is that I talked to maybe four different people and got four different implementation approaches. I am sure that in each of those, the person in the discussion had an approach that eventually worked for them. Unfortunately, it was not until my final discussion that I had one that got me past the null object problem.

The only other drawback to all of this research was that I found I was occasionally killing myself by taking input from several people, combining it all together, and having conflicts with what was already done. To make matters worse, I was given a new computer in the middle of all of this and spent two days getting everything back to normal! It was just when I was ready to walk away from this project for awhile that .S.Rod. was kind enough to pull everything together for me. Here are the final results, and a sample application to help guide others in their quest to control IE.

The Code

For this application I am going to have a webpage present buttons and graphics for a product catalog. Clicking on a button in the webpage will populate the form with descriptions and activate the purchase button. Clicking on the purchase button in the winform will send Lefty Larduchi to your front door for some money. My first step was just to build the webpage (just plain HTML and javascript) and get it to a point of displaying stuff.

Creating the form is not a problem. Just start a new C# Windows Form project, customize the toolbar and add Internet Explorer from the COM side of the fence. The form consists of a panel docked to the left, a slider, IE docked to the right, and two textboxes and a button that are inside the panel.

Now one of the first steps in taking control of IE is to implement IDocHostUIHandler. Nikhil wrote a fine article on doing this, so I won't duplicate his efforts. You can cover that first step here.

Make sure you keep track of the MSHtmHstInterop.dll piece of his sample application. I used the sample app to copy and paste the base IDocHostUIHandler implementations into my form.

So after implementing IDocHostUIHandler, what else needs to be done? Well, in Nikhil's article his example would require that you know the controls that will be clicked and that someone click on that control. This is the code that accomplishes that:

private void WebBrowser_DocumentComplete(object sender,
    AxSHDocVw.DWebBrowserEvents2_DocumentCompleteEvent e)
{
  IHTMLDocument2 doc = (IHTMLDocument2)this.WebBrowser.Document;
  HTMLButtonElement button = (HTMLButtonElement)
    doc.all.item("theButton", null);
  ((HTMLButtonElementEvents2_Event)button).onclick += new
    HTMLButtonElementEvents2_onclickEventHandler(this.Button_onclick);
}

I had to face an application requirement where we were showing major sections, with each section being just DHTML, each section had to provide me information about itself and then have the WinForm act upon that information. I found it interesting to find in all the numerous articles I read on this subject that Outlook deploys this WinForm/IE merge - just not in .NET!

In this example, we are using the javascript object window.external to interact with the form. So when a user clicks on a section it will fire a method in the script area. That method, via window.external, issues a call through MSHTML to the IDocHostUIHandler.GetExternal method, then uses the IDispatch methods to get the address of the method and call it. This next section is quoted from a discussion with .S.Rod. I couldn't describe it better:

1. anyone willing to implement custom menus or external method calls should register a custom site handler. That's what is done with the ICustomDoc.SetUIHandler(object) method call.
2. the passed object reference has to implement the IDocHostUIHandler interface, an IUnknown based interface. Among the methods are one which is used as an entry point for all window.external.mymethod() calls, that's IDocHostUIHandler.GetExternal(out object ppDispatch).
3. the GetExternal method should return a reference to an object which implements a dispatch interface. In case you don't know, a dispatch interface is a standard automation interface providing the ability to have methods called by their names, thanks to two helper methods : GetIdOfName() and Invoke().
4. the good news is that the .NET Framework provides the attribute,
   
   [InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
   
   which implements all the underlying plumbing. What's left to do is to declare and implement the actual methods.

In the end, we have a sample html file, which reacts on clicks by calling javascript's window.external.MyMethod(). In order for this to work, the afore mentioned object must be declared and implement the MyMethod() method. In the sample application, that method name is

public void PopulateWindow(string selectedPageItem).

It should be important to note at this point that any method which will interact at the COM level should be defined to always return void. If there is need to return data, that is done via the parameters with the return parameters marked as out. If there is a need to return an error, for example, that is done by setting an HRESULT via System.Runtime.InteropServices. Setting the HRESULT is done in C# by doing a

throw new ComException("", returnValue)

returnValue is an int value defined somewhere in your class, and is set to the value you want to raise.

In the sample application, the first step to exposing an object via IDispatch is to create the custom interface:

[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
interface void ICallUIHandler
{
  void PopulateWindow(string selectedPageItem)
}

Then we implement the interface in a class definition:

public class PopulateClass:IPopulateWindow
{
  SampleEventProgram.Form1 myOwner;

  /// <SUMMARY>

  /// Requires a handle to the owning form

  /// </SUMMARY>

  public PopulateClass(SampleEventProgram.Form1 ownerForm)
  {
    myOwner = ownerForm;
  }

  /// <SUMMARY>

  /// Looks up the string passed and populates the form

  /// </SUMMARY>

  public void PopulateWindow(string itemSelected)
  {
    // insert logic here

  }
}

So what we have done here is create an interface that exposes IDispatch, we implemented that interface in the PopulateClass class definition, and we take in the constructor logic a pointer to our form. This give access to the specific fields we choose. I'm going to need the class to be able to change the two textboxes as well as enable the button. So I have to go into the form code and change those three item definitions from private to public. So in these definitions, I have made the following connections:

1. My interface is bound to IDispatch
2. My class is bound to my interface
3. My class is bound to my form, acting like a bridge between the MSHTML world and C# .NET world

Finally I have to implement the last piece of code that will connect my webform to my class I defined above. In the implementation for IDocHostUIHandler.GetExternal I need to set the object passed to an instance of my class. In implementing IDocHostUIHandler, you should have taken the implementation from Nikhil's sample app and cut/paste it into your program. Alter the necessary implementation as follows:

void IDocHostUIHandler.GetExternal(out object ppDispatch)
{
  ppDispatch = new PopulateClass(this);
}

This now ties your class to the window.external portion of mshtml, it ties the form to the new class definition, and it readies everything for processing. The class implementation basically acts as a go-between between the two worlds of System.Windows.Forms.Form and Microsoft.MSHTML and your web form. The final step - before I write my code in the PopulateWindow method - is to pick which fields I want my class to access and change their definition from private to public, or to follow better coding standards - add public accessors to those fields. In this sample, I exposed the various elements that were to be changed with public accessors.

Conclusion

Now that I have a working application as well as a working sample application, I have to wonder why it took so long to pull all of this information together. But now, here it is. In the sample application:

1. The WinForm loads and the constructor is called
2. InitializeComponents occurs. This loads the WebBrowser control.
3. The WebBrowser is loaded with about:blank which will initialize the document object portion of the browser.
4. With the document initialized I can now implement IDocHostUIHandler via the ICustomDoc interface.
5. Finally the html page is loaded.

When an HTML button is clicked, it calls the method CallHostUI passing it the name of the item clicked.

1. The CallHostUI script calls window.external.PopulateWindow() passing the text each button sends.
2. window.external calls through MSHTML into IDocHostUIHandler.GetExternal and gets set to an instance of the object.
3. The logic to set the instance also passes reference to the form. Next it uses IDispatch to discover the PopulateClass method and where it is located.
4. The method is called, the reference to the form gives the class access for modifying the fields and enabling the button.

With all of this working I should add a note of warning. I have found that the Visual Designer code does not expect you to have an interface and class definition in front of your form definition. The result is if you add a control or modify a control it visually appears to take, but no change in your code has actually occured and the change disappears once you close and reopen the project. More frustrating is when you add an event handler: you get the binding to the delegate, but no actual base method implementation. Fortunately, all you need to do to work around this is to move your interface and class down to the bottom of your source code.

This can provide a very rich form of client presentation as well as rich WinForm elements for processing data. In my particular example, I'm exposing webpages developed for our internal web UI presentation engine. When each section inside of a web page is moused over, the section is highlighted with a bright yellow border. Clicking on the section passes that information to my WinForm which expresses that section in a properties page display. The various built-in editors in the framework as well as custom editors we write will hook into that properties page to allow for simple modification of data. For example, changing color in a cell element pops up the color picker editor and changing a font pops up the font picker editor.