Setting up the development environment

Installation steps that explain how to setup an empty Litium solution, and multi-server installations.

Read the system requirements for the development environment before installing, then follow the steps below:

  1. Open Visual Studio.
  2. Create an empty web application that uses .NET framework 4.7.2 or later.
    Click OK.
    Select Empty and click OK. Note: Selecting any other template will result in a non startable site due to conflicts.
  3. Open Package Manager Console from the Tools > NuGet Package Manager menu.
  4. Update the Microsoft packages for the Roslyn compiler to the latest release (due to conflicting references, see this issue)
    Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform
  5. Install the Litium NuGet packages with the command in Package Manager Console:
    Install-Package Litium.Web.Setup.Complete -IncludePrerelease

Litium is now installed and you can start your solution with the Start command from the Debug menu.

Binding redirects in Visual Studio

In certain Visual Studio installations you may get a build warning complaining of mismatching assembly versions. If not resolved, this may result in a run-time error.

To resolve, double click the warning in Visual Studio, which will automatically add the binding redirects.

A typical warning looks like this:

build warning.png

Without correct binding redirects your application will not start and displays an error message like:

Method 'SelectController' in type 'Litium.Web.WebApi.HttpControllerSelector' from assembly 'Litium.Web.Application, Version=, Culture=neutral, PublicKeyToken=093d4a638630e7c5' does not have an implementation.


For developers working in projects, Litium allows Windows accounts that are members of the server (or developer machine) administrator's group to log in. The account can be a local server account or a domain account. When logging in with the Windows account, no account will be created in Litium for this login, but technically you will be logged in as "System" with full permissions.

The Windows account login only works for the Litium back office login page. To log in on the public site a regular Litium account is needed. This means that the back office login page handles both logging in with Windows credentials and Litium credentials. For Litium to know when a Windows account should be used, the user name should contain a \ (backslash) to separate the domain and the username in a Windows pre-2000 mode.


The database is placed in the App_Data folder inside the web application you created. When you start the web application, the database will be updated to the version of the Microsoft SQL version that is used locally. If you use an older version in the staging and/or production environment you can find a default 2012r2 version of the database in the Tools\db folder inside the Litium.Setup.Core package directory that you can use and attach to the environment.

Using underscore in local domain names and Internet Explorer

If you are working with several sites on your local machine you might use different domain names for each site, for example “mysite.local”. If you create domain names using underscore (“_”) the site will work properly in Mozilla Firefox and Google Chrome, but in Internet Explorer 6 and later, you will not be able to login. This is because domain cookies will not be set in the browser.

Using Active Directory login on your local machine

To be able to use AD login locally you should use the domain name “localhost” instead of “mysite.local”. If you use “mysite.local” there will be problems logging in even when submitting the correct username and password.

Developing on a local machine using IE

When developing locally and using Internet Explorer you might encounter problems with the browser being locked in compatibility mode. Internet Explorer supports a number of document compatibility modes that enable different features and can affect the way content is displayed.

<YourDomainName> domain name

If you use the pattern "<your domain name>" in your ASP.NET web sites on your local machine, you do not have to edit the hosts file.

More information here:

Give directory access permission to the IIS application pool

IIS needs read/write access to several Windows directories in order for Litium to work properly. The main directories that need access are the Files and Integration folders.

If the application pool that Litium is configured with does not have read/write access to the Files or Integration folder, you may get error messages about IIS not having read/write access. In this case you need to add read/write permission to your application pool identity user.

The Files folder is specified in the web.config file:

    <filesDirectory value="D:\work\inetpub\LS46lhf\Files" />
    <smtpServer value="" username="" password="" enableSsl="false" />
    <eventLog maxAgeInMinutes="60" deleteIntervalInMinutes="60" pollingIntervalInSeconds="5" />

You need to give the IIS application pool that the website is running under access to the folder specified above.

app pool name.png

The user group for the IIS application pools is called "IIS AppPool" in IIS 7.0 and later (Windows 7 and later machines).

In Windows Explorer, right-click the Files folder, click Properties and select the Security tab. Give read/right permissions to the folders as shown below.

iis permissions.png


Command line option

Open a command prompt as an administrator and run the following command:

icacls <your files folder path> /grant "IIS AppPool\<your application pool name>":F /T

icacls D:\work\inetpub /grant "IIS AppPool\Studio46":F /T

Note that in Windows 7 and later, additional parameters may need to be specified. Always check the Security tab of the Files folder if you still get error messages.

Multiserver installation

Installation steps for adding the extra components that are needed for a multiserver environment (web farm or multiple developer computers using the same database).

Read the system requirements for the development environment before installing Litium!

To replicate events to multiple Litium applications running on the same server, or multiple servers, you need to install an additional package for a service bus.

Packages for Azure Service Bus can be installed from our NuGet feed.

Install with NuGet Package Manager Console

  1. Open NuGet Package Manager Console.
  2. Select the web project as default project.
  3. Run the following command:
    Install-Package Litium.Web.Setup.MicrosoftServiceBus
  4. Update web.config or app.config with the connection string for Azure Service Bus.

Install the package from NuGet Package Manager

  1. Open NuGet Package Manager.
  2. Find the Litium.Web.Setup.MicrosoftServiceBus package.
  3. Select the project to install into and click Install.
  4. Update web.config or app.config with the connection string for Azure Service Bus.
Is this page helpful?
Thank you for your feedback!