EcoController is the base ASP.NET MVC controller for developers who need an EcoSpace to read and persist MDriven business objects during an MVC request.

What EcoController provides

Use EcoController as the base class for an MVC controller that works directly with an EcoSpace. It provides:

• Creation and disposal of an EcoSpace for the controller request.
• Optional reuse of an EcoSpace through an EcoSpace cache provider.
• Shelving: temporary storage of an active EcoSpace across an MVC redirect.
• Support for using a VMClass as the MVC model, including validation updates to MVC ModelState.

Turnkey MVC Controllers build on EcoController. In particular, ModelDrivenControllerBase is an EcoController subclass that adds ViewModel, action, and navigation handling. Use EcoController when you are implementing a controller at this lower level; use the Turnkey controller types when you need their MDrivenServer and generated-UI features.

EcoSpace lifetime

By default, a typed EcoController creates the EcoSpace type specified by its generic type parameter. When the controller goes out of scope, normally when the page response has been returned to the browser, that EcoSpace is disposed.

For example, a controller can declare the EcoSpace type it uses:

public class CustomerController : EcoController<YourEcoSpaceType>
{
}

This request-scoped lifetime is suitable for an action that loads data, returns a view, and completes in the same request. A redirect is different: MVC creates a new controller for the destination request. Use shelving when the destination must continue working with the current EcoSpace.

Keep an EcoSpace across a redirect

Shelving places the active EcoSpace in TempData before a redirect. The controller created for the redirected request retrieves it with the same shelf key.

Use a shelf key that identifies the destination and the data being edited. A page name combined with an identifier is a typical choice, such as CustomerEdit-42.

Redirect workflow

1. In the first controller action, choose a shelf key.
2. Call ShelveEcoSpace() to place the active EcoSpace on the shelf.
3. Pass the shelf key as route values in the redirect.
4. In the destination controller, retrieve the EcoSpace with UnshelveEcoSpace(), or call EnsureEcoSpace() when creating the controller and supply the shelf key through route values.

The following outline shows the required relationship between the two requests. The exact action and route names are application-specific.

// First request: retain the active EcoSpace before redirecting.
string shelfKey = "CustomerEdit-" + customerId;
ShelveEcoSpace(shelfKey);
return RedirectToAction("Edit", new { id = customerId, shelfKey = shelfKey });

// Redirect destination: use the same shelfKey to retrieve the shelved EcoSpace.
// UnshelveEcoSpace(), or EnsureEcoSpace() during controller creation,
// uses the shelf key supplied in the route values.

Shelf expiry and abandoned redirects

A shelved EcoSpace is temporary. If the browser does not complete the redirect, the EcoSpace remains shelved until it is recovered or cleaned up.

• If it is not unshelved within one minute, a subsequent controller using the same session disposes it or returns it to the configured cache provider.
• If the whole session is removed and garbage collection occurs, shelved EcoSpaces are also disposed or returned to the cache provider.

Do not treat shelving as long-term storage or as a substitute for persistence. It exists to carry an active EcoSpace through a redirect.

Use VMClass as an MVC model

A VMClass can be the model for an EcoController view. This gives MVC validation support that updates the view's ModelState.

In an MVC POST, the VMClass received from the client is an offline ViewModel: it contains values posted by the client. Apply those values to an online ViewModel, which is backed by persistent storage in the EcoSpace. This separation helps you control which business-object data the view can submit.

For a full discussion of offline and online ViewModels, generated ViewModel types, and MVC view-model design, see Documentation:MVC View Model handling.

Example: apply an offline ViewModel in a POST action

The following example creates an online ViewModel for a new business object, applies the posted offline values, and then commits the EcoSpace.

[HttpPost]
public ActionResult Create(ElaborateVM offlineElaborateVM)
{
    ViewModelHelper.ApplyValues(
        offlineElaborateVM,
        ElaborateVM.Create(EcoSpace, new ElaborateClass(EcoSpace)),
        null);

    if (Commit())
        return RedirectToAction("Index");

    return View(offlineElaborateVM);
}

Redirect functions can also pass a VMClass object to the destination controller. This avoids rendering the ViewModel again before the destination action uses it.

Configure an EcoSpace cache provider

An EcoSpace cache provider lets controllers obtain and return EcoSpaces through application-specific caching logic instead of always creating a new one. Implement this only when your application needs to select a cached EcoSpace based on request information.

The cache design has three parts:

Part	Responsibility
IEcoSpaceCacheProvider	Implement this interface on the class that manages the cache mechanism.
IEcoSpaceCacheWrapper	Implement this interface on objects held by the provider. Add the information needed to select the most appropriate cached EcoSpace.
EcoSpaceRequestInfo	Subclass this type to carry the request attributes that the provider uses when serving a controller request.

Setup steps

1. Implement IEcoSpaceCacheProvider for the cache mechanism.
2. Implement IEcoSpaceCacheWrapper for cached entries and include the information the provider needs to choose an EcoSpace.
3. Create a subclass of EcoSpaceRequestInfo and add the request attributes used by the provider.
4. In your EcoController subclass, assign the application EcoSpace provider.
5. Override GetEcoSpaceRequestInfo() and return the request information for the current controller request.

For example:

public TurnkeyController_Base() : base()
{
    // Install the cache/EcoSpace provider for the application.
    EcoSpaceProvider = yourEcoSpaceProvider;
}

protected override EcoSpaceRequestInfo GetEcoSpaceRequestInfo()
{
    // Return a request-info object containing the values
    // that your cache provider uses to select an EcoSpace.
    return yourRequestInfo;
}

The provider, wrapper, and request-information types must agree on the information used to select a cached EcoSpace. For example, if the provider needs a request attribute to distinguish two cache entries, include that attribute in the EcoSpaceRequestInfo subclass and preserve the corresponding selection information in the wrapper.

See also

• Documentation:Turnkey MVC Controllers
• Documentation:MVC View Model handling
• Documentation:Introduction to ECO