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 consists of a WinForm application which is broken into two sections:
- The right side is the web app
- The left side is the winForm pieces that gets populated based on what was clicked in the web
The application implements the
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.
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
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
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.
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,
IHTMLDocument2 doc = (IHTMLDocument2)this.WebBrowser.Document;
HTMLButtonElement button = (HTMLButtonElement)
((HTMLButtonElementEvents2_Event)button).onclick += new
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!
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:
- 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.
- 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).
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 :
- the good news is that the .NET Framework provides the attribute,
which implements all the underlying plumbing. What's left to do is to declare and implement the actual methods.
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
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:
interface void ICallUIHandler
void PopulateWindow(string selectedPageItem)
Then we implement the interface in a class definition:
public class PopulateClass:IPopulateWindow
public PopulateClass(SampleEventProgram.Form1 ownerForm)
myOwner = ownerForm;
public void PopulateWindow(string itemSelected)
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:
- My interface is bound to
- My class is bound to my interface
- 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
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
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.
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:
- The WinForm loads and the constructor is called
InitializeComponents occurs. This loads the WebBrowser control.
- The WebBrowser is loaded with about:blank which will initialize the document object portion of the browser.
- With the document initialized I can now implement
IDocHostUIHandler via the
- 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.
CallHostUI script calls
window.external.PopulateWindow() passing the text each button sends.
window.external calls through MSHTML into
IDocHostUIHandler.GetExternal and gets set to an instance of the object.
- 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.
- 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.
I was born.
I'm currently coding.
I'll die some time in the future.
I have interests outside of programming and if you knew me then you'd know what those interests are.