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 customize data loading and serialization. It can be set on both the TypeScript ViewModels and the ListViewModels.

 

import { PersonViewModel, PersonListViewModel } from '@/viewmodels.g'

var person = new PersonViewModel();
person.$includes = "details";

var personList = new PersonListViewModel();
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:

Value	Description
'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.
'admin-list'	Used when loading a list of objects in the Vue admin list page.
'admin-editor'	Used when loading an object in the Vue admin editor component.
'Editor'	Legacy. Used when loading an object in the generated Knockout CreateEdit views.
'<ModelName>ListGen'	Legacy. Used when loading a list of objects in the generated Knockout 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 customize 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.

DANGER

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.

Important

DtoIncludes does not ensure that specific data will be loaded from the database. It only permits what is already loaded into the current EF DbContext to be returned from the API. See Data Sources to learn how to control what data gets loaded from the database.

Example Usage

Server code:

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 `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; }
}

Client code:

 

import { PersonListViewModel } from '@/viewmodels.g'

const personList = new PersonListViewModel();
personList.$includes = "Editor";
await personList.$load();
// Objects in personList.$items will not contain CreatedBy nor Department objects.

const personList2 = new PersonListViewModel();
personList2.$includes = "details";
await personList.$load();
// Objects in personList2.items will be allowed to contain both CreatedBy and Department objects. 
// Department will be allowed to include its other Person objects.

Properties

// Also settable via constructor parameter #1
public string ContentViews { get; set; }

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.

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