Host your own Web Server in your application using IIS 7.0 Hostable Web Core

  • [アーティクル]

IIS 7.0 includes a very cool feature that is not so well known called Hostable WebCore (HWC). This feature basically allows you to host the entire IIS functionality within your own process. This gives you the power to implement scenarios where you can customize entirely the functionality that you want "your Web Server" to expose, as well as control the lifetime of it without impacting any other application running on the site. This provides a very nice model for automating tests that need to run inside IIS in a more controlled environment. 

This feature is implemented in a DLL called hwebcore.dll, that exports two simple methods:

  1. WebCoreActivate. This method allows you to start the server. It receives three arguments, out of which the most important one is applicationHostConfigPath that allows you to point it to your very own copy of ApplicationHost.config where you can customize the list of modules, the list of handlers and any other settings that you want your "in-proccess-IIS" to use. Just as ApplicationHost.config you can also specify the "root web.config" that you want your server to use, giving you the ability to completely run an isolated copy of IIS.
  2. WebCoreShutdown. This method basically stops the server listening.

The real trick for this feature is to know exactly what you want to support and "craft" the IIS Server configuration needed for different workloads and scenarios, for example:

  1. Static Files Web Server - Supporting only static file downloads, good for HTML scenarios and other simple sites.
  2. Dynamic Web Sites
    1. ASPX Pages
    2. WCF
    3. Custom set of Http Modules and Handlers
  3. All of the above

An interesting thing to mention is that the file passed to ApplicationHostConfigPath parameter is live, in the sense that if you change the configuration settings your "in-process-IIS" will pick up the changes and apply them as you would expect to. In fact even web.config's in the site content or folder directories will be live and you'll get the same behavior.

Sample

To show how easy this can be done I wrote a small simple class to be able to run it easily from managed code. To consume this, you just have to do something like:

internal class Program {
    private static void Main(string[] args) {
        int port = 54321;
        int siteId = 1;

        WebServer server = new WebServer(@"d:\Site", port, siteId);
        server.Start();
        Console.WriteLine("Server Started!... Press Enter to Shutdown");

        Console.ReadLine();

        Console.WriteLine("Shutting down");
        server.Stop();
    }
}

This will start your very own "copy" of IIS running in your own process, this means that you can control which features are available as well as the site and applications inside it without messing with the local state of the machine.

A very interesting thing is that it will even run without administrator privileges, meaning any user in the machine can start this program and have a "web server" of their own, that they can recycle, start and stop at their own will. (Note that this non-administrative feature requires Vista SP1 or Windows Server 2008, and it only works if the binding will be a local binding, meaning no request from outside the machine).

You can download the entire sample which includes two configurations: 1) one that runs only an anonymous static file web server that can only download HTML and other static files, and 2) one that is able to run ASP.NET pages as well.

Download the entire sample source code (9 kb)

You might be asking why would I even care to have my own IIS in my executable and not just use the real one? Well there are several scenarios for this:

  1. Probably one of the most useful, as mentioned above this actually allows non-administrators to be able to develop applications that they can debug, change configuration and pretty much do anything without interfering with the machine state.
  2. Another scenario might include something like a "Demo/Trial CD" where you can package your application in a CD/DVD that users then can insert in their machine and suddenly get a running/live demo of your Web Application without requiring them to install anything or define new applications in their real Web Server.
  3. Test Driven Development. Testing in the real Web Server tends to interfere with the machine state which is by definition something you don't want in your test environments, ideally you want your tests to be done in an isolated environment that is fully under control and that you will not have to do any manual configuration. This makes this feature an ideal candidate for such scenario where you own the configuration and can "hard-code" it as part of your automated tests. No more code for "preparing the server and site", everything starts pre-configured.
  4. Build your own service. You can build your own service and use Hostable WebCore as a simple yet powerful alternative to things like HttpListener, where you will be able to execute Managed and Native code Http Modules and Handlers easily without you having to do any custom hosting for ASP.NET infrastructure.
  5. Have your own Development Web Server where you can have advance interaction between both the client and the server and trace and provide live debugging information.
  6. many, many more...

In future posts I intent to share more samples that showcase some of this cool stuff.

Summary

IIS 7.0 Hostable WebCore feature allows you to host a "copy" of IIS in your own process. This is not your average "HttpListener" kind of solution where you will need to implement all the functionality for File downloads, Basic/Windows/Anonymous Authentication, Caching, Cgi, ASP, ASP.NET, Web Services, or anything else you need; Hostable WebCore will allow you to configure and extend in almost any way the functionality of your own Web Server without having to build any code.

Comments

  • Anonymous
    April 13, 2008
    PingBack from http://microsoftnews.askpcdoc.com/?p=2233

  • Anonymous
    April 14, 2008
    CarlosAg demonstrates how to create a hostable instance of IIS 7.0 within your own application here.It’s not just a lightweight simulation of IIS — it really is IIS....

  • Anonymous
    May 20, 2008
    Hi. Do I actually place my processing code (as the scenarios above) in between Server.Start and Server.Stop? Is this like ASP.NET 2.0 FileSystem (like Cassini)?Do you have more code examples based on real life scenarios?Any help? Thanks.

  • Anonymous
    February 24, 2010
    What is Microsoft's policy on redistributing  hwebcore.dll ?  I remember at first, back in 2000, the IE library was available for developers, but it turned out we were not allowed by Microsoft to redistribute it.

  • Anonymous
    February 24, 2010
    It is not supported to be distributed, in fact that DLL is only the "activation" of the server, most of the "important" functionality is actually fullfilled by the rest of the IIS modules like if you want to support download static files, Windows Authentication or default document or anything else that still requires the IIS binaries.

  • Anonymous
    November 24, 2010
    I have been trying to get this to work and been half - successful. I have the in-proc serving static pages, but anything asp.net 2.0 either 503s or gives me a blank page. Now, I am exclusively using VS2010 and have .net 4 installed as well, so that could be a problem.I would prefer to get this to working with asp.net 4.0 apps. According to this post blogs.iis.net/.../ins-amp-outs-of-hostable-web-core.aspx , second last paragraph, "Also HWC always uses .Net 2.0 schema and there is no way to make it pick .Net 4.0 schema. ".IIS Express (Beta 3 as of writing this) appears to ship with an updated version of HWC (7.5?) and a look inside applicationhost.config confirms .net 4 support. But when I try to reference hwebcore.dll in the IIS install path (C:Program Files (x86)IIS Express instead of System32InetSrv ), I get a type a TypeInitilizationException at IntPtr procaddr = NativeMethods.GetProcAddress(hwc, "WebCoreActivate"); Basically it looks like the HWC api has changed.Any pointers / tips on whether your original post is achievable with the IIE Express's HWC?Many thanks.

  • Anonymous
    March 28, 2012
    Can HWC work only on localhost by design? what if I want this website to to accessible in my intranet?

  • Anonymous
    March 28, 2012
    It works with both, if you run it as administrator you should be able to run in any port. If you want to run the process as a normal user you will need to allow access to the port before running your app using "netsh http add urlacl" see the blog from Vaidy that explains similar process for IIS Express blogs.iis.net/.../serving-external-traffic-with-webmatrix-beta.aspx

  • Anonymous
    October 18, 2013
    Where can I find hwebcore.dll?Thanks.

  • Anonymous
    November 08, 2014
    The comment has been removed

  • Anonymous
    September 29, 2015
    "Probably one of the most useful, as mentioned above this actually allows non-administrators to be able to develop applications that they can debug, change configuration and pretty much do anything without interfering with the machine state." Except you need to be an administrator to enable the prerequisite features in Windows

  • Anonymous
    December 07, 2015
    Is there any way to run an MVC application in apache server?