You use the Turnkey MVC controller base classes when you build ASP.NET MVC endpoints that need MDriven persistence, MVC ViewModels, account handling, Turnkey server features, or streaming-client operations.

Choose a controller base

The controller base determines which MDriven services are available to your ASP.NET MVC controller. Start with the narrowest base class that provides the behavior your endpoint needs.

Base class	Use it when you need	What it provides
EcoController	An MVC controller backed by an EcoSpace.	An EcoSpace for persistence, an EcoSpace cache provider, and a mechanism that stores the EcoSpace in TempData during a redirect.
ModelDrivenControllerBase	MVC pages that work with ViewModels, actions, and navigation.	Everything in EcoController, plus handling for model-driven ViewModels, actions, and navigation.
TurnkeyController_Base	An endpoint that uses MDriven Turnkey and MDrivenServer features.	Connection to the MDrivenServer Admin EcoSpace, download of the model and views, Bootstrap rendering of ViewModels, server-side MVC or client-side AngularJS data binding, and the streaming API.
AccountControllerBase	Login, registration, or other ASP.NET account operations that must be available to your model.	ASP.NET security functions integrated with a class model in the running EcoSpace, so user information is available to business objects.
ApiController	An ASP.NET API endpoint that returns responses without a user interface.	The built-in ASP.NET API controller behavior.
ValuesController_Base	Operations for Turnkey MVC or streaming clients.	Functions used alongside normal page loading for MVC clients, and streaming-client functions for navigation, object download, and opening and closing modal windows.

Typical choices

• Derive a custom controller from EcoController when you need a conventional MVC controller that reads and writes persistent business objects through an EcoSpace.
• Derive from ModelDrivenControllerBase when an MVC action receives or renders a model-defined ViewModel.
• Use TurnkeyController_Base for functionality that depends on the MDrivenServer model and view download, Turnkey rendering, AngularJS binding, or streaming.
• Use AccountControllerBase for account UI and authentication integration rather than treating the authenticated user as unrelated to the business model.

Controller inheritance and responsibilities

ModelDrivenControllerBase is a subclass of EcoController. Therefore, a controller based on ModelDrivenControllerBase has the EcoSpace persistence support of EcoController and adds model-driven UI behavior.

For example, an MVC details page that exposes a ViewModel façade over a business object belongs on a controller derived from ModelDrivenControllerBase. A controller that only needs to query persistent objects and return a conventional MVC view can use EcoController.

Do not expose a whole business object to a view when the page requires only a defined subset or transformation of its data. Use a ViewModel to define what the page can display and update. See MVC View Model handling for the ViewModel pattern and MVC View Model constraints for update and constraint examples.

Understand offline and online ViewModels

An MVC request can involve two versions of a ViewModel (VMClass): an offline ViewModel received from the client and an online ViewModel backed by persistent storage.

ViewModel version	Created or used when	Purpose
Offline VMClass	A request arrives from the client, including an HTTP POST.	Holds values posted by the client. It is submitted or applied to the online ViewModel.
Online VMClass	The controller creates a ViewModel against its EcoSpace and persistent objects.	Reads and writes the persistent state through the EcoSpace.

The key rule is: a posted ViewModel is offline; apply its values to an online ViewModel before committing persistent changes.

This distinction means that an action decorated with [HttpPost] is the action that receives client-entered data. Other actions do not automatically write the received data to the online ViewModel or EcoSpace.

Example: apply a posted ViewModel

The following pattern resolves the persistent object, creates its online ViewModel, applies the offline values, and commits the EcoSpace.

[HttpPost]
public ActionResult Details(string Identity, VMExample2 offlinevm)
{
  Example2 e2 = EcoSpace.ExternalIds.ObjectForId(Identity).AsObject as Example2;
  try
  {
    VMExample2 onlinevm = VMExample2.Create(EcoSpace, e2);
    ViewModelHelper.ApplyValues(offlinevm, onlinevm, null);
    Commit();
    return View("Details", onlinevm);
  }
  catch
  {
    return View("Details", offlinevm);
  }
}

In this example, offlinevm contains the submitted values. onlinevm is the instance connected to EcoSpace and the persistent Example2 object. Applying values controls the update through the ViewModel rather than granting the view direct access to the full business object.

For a fuller discussion of offline ViewModels and MVC binding, see MVC View Model handling.

Rendering a ViewModel in a custom MVC application

You can render a model-driven ViewModel from an MVC application without using the complete Turnkey UI. Make the Razor model a VMClass, then render the ViewModel partial selected by the runtime.

@model VMClass
@Html.Partial(Html.RazorPartialFile())

You can also render the left-side actions and validation summary:

@Html.DisplayLeftSection()
@Html.ValidationSummary(true)

Create VMClass instances with Eco.ViewModel.Runtime.ViewModelHelper. For the complete setup and rendering guidance, see Render MVC ViewModel without turnkey.

MVC, Turnkey, and streaming

MDriven Turnkey uses MVC for its index and login pages and uses AngularJS by default for other pages. To use MVC for another ViewModel, set the ViewModel tagged value MVC=true. MVC behavior differs from AngularJS behavior; for example, MVC executes the one defined row action on a grid-row click, while zero or multiple actions result in selection, and MVC does not show Angular's popup menu for multiple actions. See MVC for the complete behavior and setup notes.

TurnkeyController_Base and ValuesController_Base support both MVC-related and streaming-related scenarios. In particular, ValuesController_Base supports operations beside the normal MVC page-loading flow and streaming operations such as navigation, object download, and modal-window open and close.

When navigation moves from MVC to Angular, Turnkey uses two EcoSpaces: the MVC EcoSpace is handed to the streaming API so work done in the MVC action remains available in the AngularJS EcoSpace. This preserves action continuity. Follow Serverside Turnkey and MVC functioning for the request sequence and architecture details.

Account controllers

AccountControllerBase connects ASP.NET security functions to a class model inside the running EcoSpace. This allows business objects to use the available user information.

To take control of Turnkey account UI with ViewModels, create ViewModels named AccountLogin, AccountRegister, or AccountManage. Each name overrides its corresponding account page. For the supported override strategy and the older file-based override option, see Customizing login and other account UI MVC.

See also

• Documentation:MVC
• Documentation:MVC View Model handling
• Documentation:MVC View Model constraints
• Documentation:Render MVC ViewModel without turnkey
• Documentation:Serverside Turnkey and MVC functioning
• Documentation:Customizing login and other account UI MVC