DOT

VVM

 DOCS

Version: |

Configuration

DotVVM uses C# code to configure its features and settings.

The typical DotVVM app needs to configure the following things:

In the default project template, there are 2 files - Startup.cs and DotvvmStartup.cs.

In Startup.cs, we configure DotVVM services and register DotVVM middlewares. In DotvvmStartup.cs, we configure routes, resources and controls.

Startup.cs in OWIN

In OWIN, the Startup.cs contains the OWIN startup class. DotVVM is just an OWIN middleware and you can easily combine it with ASP.NET MVC or any other OWIN middlewares in one application.

All you have to do is to register the DotVVM middleware in the IAppBuilder object.

var config = app.UseDotVVM<DotvvmStartup>(ApplicationPhysicalPath, options => {
    // configure DotVVM services (e.g. dependency injection) here

    options.AddDefaultTempStorages("temp");     // register default file upload and returned file storages
});

This extension method initializes the middlewares required by DotVVM. The DotvvmStartup type parameter of the UseDotVVM represents the class which contains DotVVM configuration.

Startup.cs in ASP.NET Core

In ASP.NET Core, the registration of frameworks is splitted to the registration of services and middlewares.

In the ConfigureServices method, we should register DotVVM services:

services.AddDotVVM(options =>
{
    // configure DotVVM services (e.g. dependency injection) here

    options.AddDefaultTempStorages("temp");     // register default file upload and returned file storages
});

In the Configure method we have to register the DotVVM middleware.

var config = app.UseDotVVM<DotvvmStartup>();

This extension method initializes the middlewares required by DotVVM. The DotvvmStartup type parameter of the UseDotVVM represents the class which contains DotVVM configuration.

DotvvmStartup.cs

The DotvvmStartup class must implement the IDotvvmStartup interface and contains the Configure method. There should be only one class implementing the IDotvvmStartup interface in the assembly.

This class configures resources, controls and routes. The default project template prepares this class in the following structure. We have also included examples of how to configure a route, custom control namespace and script resource.

public class DotvvmStartup : IDotvvmStartup
{
    // For more information about this class, visit https://dotvvm.com/docs/tutorials/basics-project-structure
    public void Configure(DotvvmConfiguration config, string applicationPath)
    {
        ConfigureRoutes(config, applicationPath);
        ConfigureControls(config, applicationPath);
        ConfigureResources(config, applicationPath);
    }

    private void ConfigureRoutes(DotvvmConfiguration config, string applicationPath)
    {
        config.RouteTable.Add("Default", "", "Views/default.dothtml");

        // Uncomment the following line to auto-register all dothtml files in the Views folder
        // config.RouteTable.AutoDiscoverRoutes(new DefaultRouteStrategy(config));    
    }

    private void ConfigureControls(DotvvmConfiguration config, string applicationPath)
    {
        // register code-only controls and markup controls
        config.Markup.AddCodeControls("cc", typeof(MyCustomControl));
    }

    private void ConfigureResources(DotvvmConfiguration config, string applicationPath)
    {
        // register custom resources and adjust paths to the built-in resources
        config.Resources.Register("myscript", new ScriptResource()
        {
            Location = new LocalFileResourceLocation("~/wwwroot/Scripts/myscript.js")
        });
    }
}

Please note that the Visual Studio Extension executes the Configure method of the DotvvmStartup class during the project build process so the IntelliSense can suggest custom controls, route and resource names.

Avoid registering any other things than routes, custom resources and custom controls in the Configure method. This method is executed during the project build in Visual Studio, so please don't launch rockets in it.

If you need to register or initialize anything else (e.g. initialize the database, create default users), do it in the Startup.cs, or anywhere else.

Debug Mode

The DotvvmConfiguration object contains the Debug property which should be turned in the development environment, and turned off in production.

In the Debug mode, DotVVM displays an error page for all unhandled exceptions that occur, it uses non-minified versions of scripts (where applicable) and reports validation errors using a red popup that appears in the top right corner of the page.

The property is automatically set in ASP.NET Core based on IHostingEnvironment.IsDevelopment(). In OWIN you need to set the value yourself.

The typical setup that is present in default DotVVM OWIN project, looks like this:

#if !DEBUG
config.Debug = false;
#endif

Static Files

In the default project template, the Startup class also registers a static files middleware. DotVVM doesn't need it itself, however in 99% cases you want to use it to serve static files like images to the user.

Next Chapter



Suggestions


Help & Contribute

The documentation is maintained on GitHub.
We'll be happy if you edit the page and create a pull request.

Send message