Edit on Github

Viewmodels overview

The viewmodel has two main responsibilities:

  • It manages the state of the page - i. e. values in all form fields, rows in a GridView, items in a ComboBox, and so on.

  • It processes commands invoked by the user - e. g. defines what happens when the user clicks on a Button.

public class CalculatorViewModel 
{
    // The state of the page is represented by public properties.
    // If you serialize the viewmodel, you should have all the information to restore the page exactly same state in the future.

    public int Number1 { get; set; }

    public int Number2 { get; set; }

    public int Result { get; set; }


    // The commands that can be invoked from the page are public methods.
    // They can access the state of the viewmodel and change it.

    public void Calculate() 
    {
        Result = Number1 + Number2;
    }
}

Be careful. The viewmodels viewmodels are sent to the client in the JSON format - any property can be changed by the user even though the UI doesn't allow such change.

Always validate that the values submitted by the user are correct, and that the user has appropriate permissions to perform the operation.

Do not put sensitive information in the viewmodels. Check out the viewmodel protection chapter for more details.

Types supported in viewmodels

The state of the page is represented using public properties. Please note that the viewmodel must be JSON-serializable, because DotVVM needs to send it to the browser together with the page HTML.

Therefore, the viewmodel can contain properties of the following types:

  • supported primitive types
    • string
    • numeric types - int and double are preferred (you can use byte, sbyte, short, ushort, uint, long, ulong, float, and decimal, but the precision can be lost during the JSON serialization)
    • bool
    • Guid
    • DateTime
    • enums
  • nullable versions of supported primitive types (e. g. int?, DateTime?...)
  • objects with properties of supported types, and a public parameterless constructor
  • collections of supported objects, or primitive types
    • Arrays: T[]
    • Lists: List<T>
    • Dictionaries: Dictionary<K,V> (new in version 3.1)

Please note that the TimeSpan and DateTimeOffset are not supported in the current version.

Base class

Viewmodels in DotVVM commonly inherit from the DotvvmViewModelBase class. Although it is not mandatory, we recommend to follow this convention.

The DotvvmViewModelBase class offers several useful mechanisms that you may need:

  • The Context property gives you information about the current HTTP request.
  • You can override the Init, Load and PreRender methods that are called during the viewmodel lifecycle.

If you cannot use the DotvvmViewModelBase base class, you can implement the IDotvvmViewModel interface to get a similar functionality.

Viewmodel lifecycle

In the following diagram, you can see the lifecycle of the HTTP request in DotVVM.

The left side shows what's going on when the client access the page first time (the HTTP GET request). The right side shows what happens when a command is invoked (e.g. when the user clicks a button to call a method in the viewmodel).

Viewmodel lifecycle

Other features

DotVVM supports dependency injection in the viewmodels - it is easy for the viewmodels to request any services they may need in their commands. We recommend to declare the injected services as private fields in the viewmodel class - this will exclude them from the serialization automatically.

public class MyViewModel : DotvvmViewModelBase 
{

    private MyService _myService;

    public MyViewModel(MyService myService)
    {
        this._myService = myService;
    }

}

If you need to store sensitive information in the viewmodel, or you want to sign some properties to be sure the users didn't change them, see the viewmodel protection chapter for more details.

You can instruct DotVVM to exclude some properties from serialization, or to transfer them only in one way (e. g. from the server to the client). This can be configured using the Bind attribute.

See also