How to run Umbraco 9 in IIS

This post demonstrates how you can run Umbraco 9 (.Net Core) in IIS using IIS Builder to automate the boring bits.

As of writing, Umbraco 9 is currently in Beta so expect things to break and workarounds to be "hacky" workarounds. The package version I am currently using is 9.0.0-beta003.

Why?

I guess the first question to ask is why do this?

Benefits

• The first benefit is you may decide to host your production Umbraco 9 site in IIS so it’s a good idea to figure out how it behaves now and as new versions are released.
• There's no need to use the dotnet run command and work with the localhost domains strictly, i.e. localhost:[various port numbers go here]. You can use whatever custom domain you wish.
• Using IIS builder you work with a self signed certificate for your HTTPS needs. In some cases your localhost:44307 will show up as insecure in the browser.
• Run multiple instances of Umbraco 9 sites locally all under different domain names. Maybe you plan to have two Umbraco 9 sites talking to each other?

Current Drawbacks

When running the site from IIS the site will have a file lock on the websites dll file. This prevents you from building the site, you will need to turn off the IIS site before you can build again. Currently I haven't figured out a way to avoid this yet.

How?

First get Umbraco 9 by following Bjarke Berg’s helpful blog post here: https://umbraco.com/blog/umbraco-9-beta-release/ or looking at the docs. For this example I am creating a project without SQLCE using this command: dotnet new umbraco -n mattou07-v9. Don't forget to build your project once you have the code downloaded!

Before creating the IIS site you will need to install the IIS Module. You can find this here: https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/?view=aspnetcore-5.0

Once this is installed, in an Administrator Command Prompt type iisreset. This will restart IIS on your machine.

Next add a Web.Config file into project. It should be in the same folder as the Startup.cs and Program.cs files. The Web.Config should contain the following:

<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\bin\Debug\net5.0\UmbracoProject.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Pay attention to the arguments area in the aspNetCore element. You will need to provide the path to the dll for your website, since beta 003 it looks like it defaults to UmbracoProject.dll. I am not 100% sure on this. In previous versions the DLL name would be the name you specify in the dotnet new command.

Now we move onto the IIS Builder setup, create an iis-config.json file at the same level as the Web.Config. Set your names and bindings as desired.

However, we need to set the Dot Net Clr version to ran as No Managed Code. To do this we leave the IIS-App-Pool-Dot-Net-Version as an empty string. Your json config should look something like this:

{
    "IIS-Site-Name": "umbraco-core9",
    "App-Pool-Name": "umbraco-core9",
    "IIS-App-Pool-Dot-Net-Version": "",
    "bindings": ["umbraco-core9.localtest.me"]
}

Obtain IIS Builder from my Github https://github.com/mattou07/iis-builder and place it into your webroot and run it. You can also run via a Powershell alias if you have set that up which is mentioned here: https://github.com/mattou07/iis-builder#setup-a-powershell-alias

Potentially in most cases you may receive a 500 error like this:

We need to turn on debugging to see the error. This is a hacky way to do it and I have tried enabling debugging via the appsettings.json but had no luck so doing this. So were doing it the quick and dirty way!

To do this go to Startup.cs and comment out the if (env.IsDevelopment()) statement on line 57. This forces app.UseDeveloperExceptionPage(); to run. Obviously this is not the ideal way and there is probably a better way to get the error messages without having to hack the code!

We now get detailed errors:

Here its complaining about a missing library System.Drawing.Common. Here is where we get into treacherous waters if we add this nuget package does it still work in Linux etc? Still lets press on! Looking up the package on nuget System.Drawing.Common I can just install it with dotnet add.

It also complains about this package too System.Security.Cryptography.Pkcs I added this package also:

This should be the last package and you should now have Umbraco 9 beta 003 running under IIS with a self signed certificate for HTTPS:

Done

Hooray you should now be seeing the Umbraco installer on your screen. You should then be able to proceed as normal.