Includes String

Coalesce provides a number of extension points for loading & serialization which make use of a concept called an “includes string” (also referred to as “include string” or just “includes”).

Includes String

The includes string is simply a string which can be set to any arbitrary value. It is passed from the client to the server in order to control data loading and serialization. It can be set on both the TypeScript ViewModels and the ListViewModels.

var person = new ViewModels.Person();
person.includes = "details";

var personList = new ListViewModels.PersonList();
personList.includes = "details";

The default value (i.e. no action) is the empty string.

Special Values

There are a few values of includes that are either set by default in the auto-generated views, or otherwise have special meaning:

none
Setting includes to none suppresses the Default Loading Behavior provided by the Standard Data Source - The resulting data will be the requested object (or list of objects) and nothing more.
Editor
Used when loading an object in the generated CreateEdit views.
<ModelName>ListGen
Used when loading a list of objects in the generated Table and Cards views. For example, PersonListGen

DtoIncludes & DtoExcludes

Main document: [DtoIncludes] & [DtoExcludes].

There are two C# attributes, DtoIncludes and DtoExcludes, that can be used to annotate your data model in order to control what data gets put into the DTOs and ultimately serialized to JSON and sent out to the client.

When the database entries are returned to the client they will be trimmed based on the requested includes string and the values in DtoExcludes and DtoIncludes.

Caution

These attributes are not security attributes - consumers of your application’s API can set the includes string to any value when making a request.

Do not use them to keep certain data private - use the Security Attributes family of attributes for that.

It is important to note that the value of the includes string will match against these attributes on any of your models that appears in the object graph being mapped to DTOs - it is not limited only to the model type of the root object.

Example Usage

public class Person
{
    // Don't include CreatedBy when editing - will be included for all other views
    [DtoExcludes("Editor")]
    public AppUser CreatedBy { get; set; }

    // Only include the Person's Department when :ts:`includes == "details"` on the TypeScript ViewModel.
    [DtoIncludes("details")]
    public Department Department { get; set; }

    // LastName will be included in all views
    public string LastName { get; set; }
}

public class Department
{
    [DtoIncludes("details")]
    public ICollection<Person> People { get; set; }
}

In TypeScript:

var personList = new ListViewModels.PersonList();
personList.includes = "Editor";
personList.load(() => {
    // objects in personList.items will not contain CreatedBy nor Department objects.
});
var personList = new ListViewModels.PersonList();
personList.includes = "details";
personList.load(() => {
    // objects in personList.items will be allowed to contain both CreatedBy and Department objects. Department will be allowed to include its other Person objects.
});

Properties

public string ContentViews { get; set; } 1

A comma-delimited list of values of includes on which to operate.

For DtoIncludes, this will be the values of includes for which this property will be allowed to be serialized and sent to the client.

Important

DtoIncludes does not ensure that specific data will be loaded from the database. Only data loaded into current EF DbContext can possibly be returned from the API. See Data Sources for more information.

For DtoExcludes, this will be the values of includes for which this property will never be serialized and sent to the client.