Toolkit Walkthrough

Now its time to create a new MVC project.
  • In Visual Studio, create a new project (CTRL + SHIFT + N) to open the ‘Add New Project’ dialog.
  • In the ‘Search’ box at the top right, type: MVC
  • Select the ‘MVC Application’ project template, give the project a name, and press OK.
The new MVC application project template

As the project is created a bunch of items are created for you in ‘Solution Explorer’, that represent an ordinary ASP.NET MVC project, with a few extras.
The contents of the new project

You will also see a new window popup called the ‘Solution Builder’, and in this window you will see the logical structure of an MVC application (i.e. Controllers, Actions, Views, ViewModels etc). This is where you are going to build your solution.
  • Have a quick look at the nodes in the ‘Solution Builder’, and their properties in the ‘Properties Window’ (F4).
How an MVC application is represented to the developer

You will also see another window popup called the ‘Guidance Explorer’, and in this window you will see both informational and instructional guidance on what MVC applications are all about, and how to create one.
  • Browse through the guidance and get a feel for the kind of information and instruction you can learn from.
The contextual guidance presented to the developer

It is this kind of guidance that is critical for developers understanding what the application architecture is, how it works, and furthermore how they can shape it for their requirements on the project. This kind of information is invaluable to developers who may be either new to the organization, new to the toolkit, or new to the MVC technology and architecture. It forms the complete document set for building this kind of application, just where the developer needs it -> right next to what they are doing.

Running the project - where is the Login form?

  • Start the application by pressing F5 (or CTRL+F5 for no debugging).
You will see the standard ‘ASP.NET Development Server’ start up, and the web application starts on the default page, just like a standard ASP.NET MVC 2 application.
The application out of the box

Notice the [Log On] link at the top right of the page.
  • Click on the [Log On] link at the top right, it generates an error. "The Login.aspx page cannot be found."
  • Close the web application and return to Visual Studio.
The Login page is not yet implemented!

Creating the login form

In most organizations, to avoid inconsistencies across the web applications they build, and to drive consistency for their users, they tend to want to standardize how standard ‘web application features’ such as logging in and out are implemented. So typically, that kind of organization will want you (the web developer) to use their guidelines for creating a Login form.
  • In ‘Solution Builder’, expand the ‘Accounts’ controller node, and right-click on the 'Actions' node, and select 'Add | Action' to create a new action called "LogOn"
  • Right-click on the ‘LogOn’ action node, and select ‘Add | View | Logon Form’, and name the new form “LogIn”.
Creating a new login form

You will notice that a new node is created representing a login form. You may also notice that a bunch of artifacts were added to the solution at the same time.

To view those artifacts, simply double-click on the ‘LogIn’ form and the generated code is opened.

In the ‘Properties Window’ for the new ‘LogIn’ node, take a look at the properties you can configure for all login forms.
The supported properties of the new ‘LogIn’ form

Let’s now start the application again and see what has happened.
  • Press F5 (or CTRL + F5 for no debugging).

You will now notice that clicking the [Log On] link at the top of the home page now takes you to the Log In page!
New login form implemented and wired up

Not only is the log in page implemented for you, but it is wired up in the right place to the application as well! no code required!

Adding a search form

Now let’s do something a little more complex.

Suppose this web application managed a database of customers, and you now want to allow your users to search for and modify customer records. You would need to implement a number of things in the code: a form to capture search criteria, and form to display search results, a layer of the application that fetched data from a data source (i.e. from a DB or data service of some kind). Then you would have to wire it all into the web application.

Remembering that this is an MVC application and remembering that your implementation needs follow some already established MVC architecture rules for this kind of a feature.

Let’s get started using the toolkit to do this. Actually, we will be using multiple toolkits, working together here, to do the work for us.
  • In the ‘Solution Builder’ window, add a new ‘Controller’, called “Customers”
  • To the ‘Actions’ collection, add a new ‘Action’ to the ‘Customer’ controller, called “Search”
  • To the ‘View’ node, add a new ‘Search Form’ view, to the ‘Search’ action, called “FindCustomer”
Creating a new custom search form

At this point you will now see a new ‘Search Form’ node appear in the ‘Solution Builder window, but you will also see new guidance appear in the ‘Guidance Explorer’ window specifically for creating search forms.
  • Browse the guidance and gain an understanding of what search forms are and how they are implemented for you.
This guidance is especially useful for developers who may not be familiar with either the MVC pattern or ASP.NET post back forms.
Search forms come with their own guidance
What may not be obvious at this point, is that the automation, guidance and code that is generated by the Search Form is provided by another toolkit entirely. You are just seeing that toolkit integrated into the MVCApp Toolkit, where it makes sense in your application.

Form Validation

Now let’s mirror an all too common activity in development. Let’s build the solution at this point, and see what happens.
  • Build the solution (F6)
Notice that the ‘Error List’ pops up with some critical errors about the implementation of the web application. Specifically about how the search form is not yet configured correctly.
  • Examine the errors and suggested resolutions.
Something is not yet configured correctly

We are missing vital configuration of the search form that is required for correct operation of it, such as: ‘Search Criteria’, ‘Search Columns’ and a ‘Search Provider’

Because the toolkit understands the architecture and requirements of this MVC pattern, through the use of validation rules, it can point out where the developers need to provide input for their specific requirements on the project.
  • Open and pin the ‘Properties Window’, expand the ‘FindCustomer’ node, and select the ‘Search Provider’ node in Solution Builder.

Notice that the ‘View Model’ property is empty. This is a critical error for the search form. The ‘View Model’ is a required piece of configuration that provides the data for the search form to display.
Properties of a new search provider

Let’s now create a ‘View Model’ we can use.
  • In ‘Solution Builder’, right click on the 'View Models' collection, and add a new ‘ViewModel’, called '”Customer”
  • To the ‘Fields’ collection, add new ‘Fields’ called: “CustomerId”, “Firstname”, “Lastname” and “IsManaged”, and any others you like. Leave all the data type properties defaulted.
A new view model representing a customer

The 'Save' button in ‘Solution Builder’ is provided really just for comfort, as the configuration in solution builder is saved automatically very frequently.
  • Save your implementation by clicking the ‘Save’ button on the toolbar of the ‘Solution Builder’ window.
Save the solution configuration anytime

Now that we have a view model to work with we can complete the search form configuration, and satisfy the validation errors.
  • Select the ‘Search Provider’ node again, and in the ‘Properties Window’ notice that we now have a selection of available view models to choose from.
  • Select the ‘Customer’ view model.
Selecting the new ViewModel as the data model for the Search Provider
Let’s now build the solution again.
  • You can build the solution again (F6) and notice that one of the validation errors have gone.

That configures the ‘Search Provider’, but now we need to configure: the ‘Search Columns’ and ‘Search Results’.
  • To the ‘Search Columns’ collection, add a new ‘Text Column’, called “First Name”.
  • From the drop down of the ‘Display Field’ property, select the “Firstname” field of the view model
Notice that the list of available fields come from the fields of the actual view model that we selected for the ‘Search Provider’.
New search column

Now all that is left is to configure the ‘Search Results’
  • To the ‘Search Criteria’ collection, add a new ‘Text Criterion’, called “Name”.
Notice this time, a wizard appears that can guide us through the process of configuring the properties of the Text Criterion.
A wizard that helps guide you through complex configuration

Wizards are very useful UI guides to help steer developers through complex configuration processes, like this one, where the extra text and layout is more helpful than just a properties grid.
  • Complete the wizard by clicking the ‘Finish’ button.
  • In the ‘Properties Window’ for the ‘Name’ node, From the drop down of the ‘Search Field’ property, select the “Lastname” field of the view model.
Configuring a search criterion

Now that we think we have completed the configuration for a search form, it’s time to build the solution and see if those validation errors are gone.
  • Build the solution (F6), and notice that the solution builds fine, the errors are gone.
In the process you may notice that a significant amount of new code is added to the solution in the ‘Solution Explorer’ window.

Many of the nodes in solution builder generate and configure multiple artifacts (files) in the solution depending on the configuration of those nodes. There is a many to many mapping from nodes in the Solution Builder to items in the Solution Explorer.

You can always view the code and configuration files associated to a node in the Solution Builder.
  • Right-click on the ‘FindCustomer’ search form node in Solution Builder, and select ‘Open Solution Items’, or double-click the node.
How to track files controlled by nodes in Solution Builder
You will see multiple (5x) code files open in the IDE that have been generated for you that represent the implementation of the search form.
The search form generates a lot of code integrated into the solution

Wiring up the Search Form

At this point we have configured the search form, it’s time to wire in the search form to the web application to test it.

In this example, we are simply going to add a link in the site master page to display the search form manually. But there are many possibilities in a web application.

The toolkit may or may help you to different levels with things like this wiring using automation, or manual instructions, depending on what the designer of the toolkit wished to focus upon.
  • In Solution Explorer, open and edit the file ‘\Views\Shared\Site.Master’
  • On around line 26, where there is a list of <li> elements within the <ul id="menu">, add the following additional <li> to the end of the list:
<li><%: Html.ActionLink("Search", "Search", "Customers")%></li>

Now you can build and run the web application again and take a look at your search form.
  • Press F5, to build and run the solution
The new search form link appears

Now we can test our search form:
  • Click on the 'Search' link, and the search criteria page is displayed.
Notice that the 'Name' (text) search criteria that you configured is displayed.
  • Enter some search criteria, and press 'Submit'
The search criteria page

The search results page is now displayed.
Notice that the 'First Name' result column that you configured is displayed, and that there are no search results.
The search results page

Wiring up the Search Provider - Where are the search results?

You have already seen many examples of automation at work in this toolkit. And you have seen the guidance that can provide high value in the form of documented instructions or information for understanding. In fact, you will probably have noticed that most of the instructions provided in this walkthrough are illustrated in the guidance windows that you may have seen during this walkthrough.

Toolkit users should expect that given any kind of application or architectural pattern, that there will always be custom development activities on a project that are better left to manual coding rather than automated with tools. No toolkit can do everything for you nor presume every aspect and feature of your specific software project.
A toolkit is there to guide you through the 60%-80% of the predictable stuff that is automatable, leaving the 40%-20% manual stuff to your creativity and hand-crafting skills.

You'll notice that there are no search results displayed, because in this toolkit the 'Search Provider' does not implement any data access mechanism to access the data for the search results. In this toolkit, the data access implementation has been deliberately left up the developer to custom code. But the toolkit hasn't quite abandoned the developer to integrate that custom code into what the toolkit has generated. The toolkit has in fact provided some handy hooks for the developer to integrate their data access strategy with the search provider.
Depending on where the data for the search results comes from (i.e. Database, Cloud, service, XML file, etc.), it must be handled by the ViewModel, and presented by the View.
  • In Solution Explorer, open the file 'Models\FindCustomer.cs'
This file is one of the files that is generated by the Search Form.
In the file you will find the 'List' method, and if you read the comments you will see what has to be done to integrate your data access strategy with the Model.
  • In the 'Models' folder, create a new C# class called "CustomerViewModelProvider.cs"
  • The namespace that is created for you in this file will be <YourApplicationName>.Models. Change that namespace to be <YourApplicationName>.Providers
  • Change the name of the class to "CustomerViewModelProvider", and replace the public keyword with "partial"
  • In the class body, type the word "override", press space, and select the 'List' method from intellisense.
The overridden method body is generated for you, and the class should look something like this:
namespace MVCApplication1.Providers
    partial class CustomerViewModelProvider
        public override IEnumerable<Models.CustomerViewModel> List(Models.FindCustomerModel model)
            return base.List(model);

Notice that this method takes a single parameter containing the search criteria (of type 'FindCustomerModel'), and must return a list of search results (of type 'CustomerViewModel').
It is in this method that you would normally write some custom code that does something at minimum like: connect to your data source, construct a query using the parameters in the search criteria, and query the data source. The data source would then return its data in whatever form, and you would likely write some conversion logic to populate a new collection of 'CustomerViewModel' instances.

For this walkthrough, we are simply going to demonstrate this working with some trivial, and nonsense fun code.
  • Simply copy this code, and paste it into the body of the method, replacing all lines of the method.
            if (!string.IsNullOrEmpty(model.Lastname) 
                && model.Lastname.StartsWith("A"))
                return new[]
                    new Models.CustomerViewModel
                        CustomerId = "1000", Firstname = "Aaron", Lastname = "Smith", IsManaged = "true"
                    new Models.CustomerViewModel
                        CustomerId = "1001", Firstname = "Alice", Lastname = "Jonsson", IsManaged = "false"
                return new[]
                    new Models.CustomerViewModel
                        CustomerId = "9000", Firstname = "Peter", Lastname = "Yang", IsManaged = "true"

You are now ready to try it out in your application.
  • Press F5, to build and run the application
  • In the browser, click the 'Search' link on the home page.
  • In the 'Name' search criteria textbox, type any word starting with the letter "A", and press 'Submit'
You now see the code you just pasted working for you.
Search results populated

Clearly, this code is nonsense, and would not represent real production code you may need to write. And such code would probably consider aspects like validation of the criteria, and constructing a sensible query etc.
But the point is that to be able to get to the point of writing that code for your application (which is really the interesting stuff), the toolkit has done 95% of the work and plumbing for you.
It is taking care of constructing the OO objects that are used to collect the search criteria, and those which make up the ViewModel. Make a change in the Solution Builder, and the code is adjusted correctly. No manual errors. Not only that but it has generated the right hooks for you to enable you to simply integrate your custom code into the right place in the architecture, making it simple for you to be productive with what the application should be doing.

Wrapping Up

Well, that concludes our walkthrough, we hope you enjoyed using this toolkit, and you could see from this walkthrough the potential value that a toolkit like this can provide (albeit a sample).
We hope you can see ways of improving this experience for other developers yourself, and you may have some good ideas on how you would do it differently if you were to build a toolkit like this.

You may be surprised to know that this toolkit was envisioned, and built to its current level of functionality in about 7-8 days by a developer who had little ASP.NET MVC experience at the time. Although it took a few more days to polish it up with icons, text and guidance, and get and refine with some user feedback.

Where to from here?

You have seen many ideas in this sample toolkit. This one specifically focused on ASP.NET MVC web applications. Remember this is just a sample of some things that a toolkit can do. Not an example of everything a toolkit can do.

So, where to from here? Perhaps the concept of this example really resonated with you but the technology or implementation patterns were not quite right for you or your organization/community. So why not start by creating a toolkit for something that is very familiar for you. Perhaps one based on your own understanding of how components in the types of application you work on should be implemented. There are no rules here. Your toolkits should reflect your learned understanding of what works for you and your organization/community. There is no single right way to do something in software today. But oftentimes a group of developers agree on a way that works for them, and reproducing that across multiple projects consistently is a tedious and error prone process. Why not use automation to help you get it right every time?

Notice how much code you actually wrote to achieve all that you have seen implemented in the Web Application in this walkthrough. That is a huge benefit of toolkits, reducing human error, and enforcing consistency, saving time, money and manual maintenance.

You should get a few tips and pointers to how to implement similar patterns in your own toolkit. And within a few hours or days you could have a similar or better toolkit.

In the Source Code tab of this project you can ‘Download’ or ‘Clone’ the code, open it in Visual Studio, and investigate how this toolkit was created and works.

By using the NuPattern tools you can get started by building your own toolkit. The tools provided to you use the same principles and cues as you have seen in this toolkit: you use Solution Builder to create and configure your toolkit, add the features of your toolkit you want, and add written guidance to help inform and instruct your users on getting their jobs done faster and more consistently with automation and guidance.

Good Luck! and if you have any questions, go ahead and ask them at the Discussion Board of the NuPattern Project.

Last edited Feb 6, 2013 at 7:17 AM by jezzsa, version 16


No comments yet.