You can use the MDriven MVC template to start an ASP.NET MVC application that uses an MDriven model, generated code, and an MVC user interface; this guide is for developers who have received the template source and want to run and adapt it in Visual Studio.
Before you begin
Make sure that the following are available before opening the solution:
- MDriven Framework is installed and available in Visual Studio. See Getting Started with MDriven for installation and environment setup.
- You have the MVC template source on your local computer.
- Visual Studio can restore the NuGet packages referenced by the solution.
- You have decided which persistence mechanism the application will use. The template requires a configured Persistence Mapper, the component that maps model objects to storage.
The original template instructions referenced Visual Studio 2012 or 2013 and a CodePlex download. Treat that location as a historical source for the template archive. Use the template source supplied for your MDriven version, and restore the packages referenced by that source.
Set up the template
- Obtain the template source and extract it to a local working folder.
- Open the solution file in Visual Studio.
- Restore the solution's NuGet packages. If the solution offers NuGet package restore, enable it; otherwise use Visual Studio's package-restore command for the solution.
- Build the solution.
- Resolve package-restore or build errors before changing the model. A successful build confirms that the template, generated code, and referenced MDriven assemblies are aligned.
For example, if Visual Studio reports a missing assembly after opening the solution, restore the NuGet packages first and build again. Do not start by editing generated files to work around a missing package.
Configure persistence
Configure the template's Persistence Mapper before running the application. The mapper determines where the objects represented by your MDriven model are stored.
- Locate the persistence-mapper configuration in the template project.
- Select and configure the mapper appropriate for your development environment.
- Build the solution again.
- Run the application and verify that it can start with the configured mapper.
For a small local experiment, the MVC Core walkthrough uses an XML persistence mapper as an easy way to start. Your project can use a different mapper when its storage requirements require it. Keep the persistence configuration under source control when it is safe to do so, but do not commit environment-specific credentials.
Develop from the model
After the template builds and starts, use the normal MDriven development loop:
- Open and change the model in MDriven Designer.
- Run Codegen whenever you make a structural model change, such as adding or changing classes, associations, or state machines.
- Build the Visual Studio project so that the latest generated and compiled code is available.
- Run and test the MVC application.
- Deploy the built application and model to your MDriven Framework environment, including MDrivenServer where your deployment uses it.
For example, if you add a new association between two classes, run Codegen before building. Building without Codegen can leave the application compiled against an earlier model structure.
Keep model logic visible
MDriven can generate C# stubs for class methods whose EAL body is empty, so you can complement model logic with C# when needed. Keep derivations and other logic in OCL or EAL when that makes the model easier to inspect and cross-reference; use C# where external assemblies or code-level implementation are required.
See Switching to Visual Studio from MDrivenDesigner for the Visual Studio model, Codegen, and CodeDress workflow.
Add MVC ViewModel UI
The starter template gives you an MVC application foundation. To render an MDriven ViewModel in that application, add a controller derived from the appropriate MDriven controller base and provide the required generic Razor view. The detailed controller, view, and layout steps are documented in MVC Generated ViewModel UI in MDrivenFramework.
A ViewModel is the model-defined representation of the data and actions presented to a user. For example, an MVC action can create a ViewModel named SampleViewModel and return the generic view that renders it. Keep the ViewModel definition in the MDriven model; keep MVC-specific controller and Razor integration in the MVC project.
MVC interaction differs from the Angular-based UI used by Turnkey. In MVC, a grid row click selects a row when the ViewModel defines zero or multiple actions, but executes the action when it defines exactly one action. MVC does not show Angular's popup menu for multiple row actions. See MVC before designing row actions and navigation.
Verify the result
Use this checklist after setup:
| Check | Expected result |
|---|---|
| Package restore | The solution's referenced NuGet packages are restored without unresolved references. |
| Build | The solution builds successfully after restore and after persistence configuration. |
| Startup | The MVC application starts using the configured Persistence Mapper. |
| Model change | After a structural change, Codegen completes and the subsequent build uses the changed model. |
| ViewModel UI | A configured MVC route can create and render the intended ViewModel through the generic MVC view. |
Common issues
The solution does not build after opening
Restore NuGet packages, then rebuild. The MVC template relies on the package versions referenced by its solution. If the template was created for an older Visual Studio or framework version, obtain a template or package set intended for the version you are using rather than mixing assemblies manually.
Changes to classes or associations do not appear in the application
Run Codegen and then build the project. Structural changes are not available to the compiled application until both steps have completed.
The application starts but cannot persist data
Review the Persistence Mapper configuration and the storage it targets. Confirm that the mapper is configured for the environment in which you are running the application.
A ViewModel does not render as expected
Check the MVC controller, the ViewModel name, and the location and content of the generic Razor view. Follow MVC Generated ViewModel UI in MDrivenFramework rather than duplicating generated UI markup in individual views.