DPS907 notes – Tue Oct 3

App-building topics: Web app and service in the same project, improved error-handling, documentation strategies.


Code examples

In the GitHub code example repository for this week, you will see several interesting assets.

The WebAppAndService code example will be studied today, and discussed in the notes below.

Another code example, BetterErrorHandling, is referenced, and discussed below.

Finally, DocumentationIntro covers the final topics, out-of-band and embedded documentation.

More will be posted for the Thursday class.


Reminder – use the Visual Studio Task List…

Make sure that your Visual Studio app is configured to use the “ATTENTION” comment token.

Then use Visual Studio’s “Task List” to help you study the design and coding features of the code example.


Mixing web app (MVC) and web service (Web API) controllers
in the same project

Can you have web app (MVC) and web service (Web API) controllers in the same project? Yes.

What about resource URIs – can we have this, for the Employee entity, for example:

  • Web app – /employees, or /employees/detail/5
  • Web service – /api/employees, or /api/employees/5


It requires a bit of extra work, however.


What could go wrong

Assume that you have an existing Web API controller for the Employee entity. Its source code file will be named EmployeesController, and the class inside the file will also be named EmployeesController. This you know.

Now, assume that you want to add a web app (MVC) controller. If you attempt to add another controller with the same name, it will not be possible. Your first reaction may be to choose a new name, but that will affect the resource URIs for the web app. If you choose an ugly name (e.g. Employees2Controller, or EmployeesMVCController), then it’s bad news.


How to solve 

We suggest that you make small modifications to the web service (Web API) controller. Doing this will clear the way for you to add a web app (MVC) controller. Here’s the suggested sequence, using the Employee entity as an example.

1. Create a Web API controller, named EmployeesController.

2. In Solution Explorer, rename the new source code file to EmployeesApiController. When asked “Would you also like to perform a rename…?”, answer No.

3. Change the namespace name to <projectname>.Controllers.Api.

4. Then, you can create an MVC controller, also named EmployeesController.


This all works because we are placing the Web API controller in a different namespace. That enables us to support two classes named EmployeesController, because they will be in different namespaces.

Note: It is not necessary to do this for every Web API controller. Do it when needed, whenever you want to support both an MVC controller and a Web API controller for the same entity/collection.


Minor improvement for exceptions/errors

Up to this point in the course, we have been using HTTP status codes and the ASP.NET Web API framework stack trace to communicate error conditions to requestors.

Today, we’ll make a minor improvement to that process. We take advantage of your recent experience in working with modules (e.g. byte formatter, and soon an “HTTP OPTIONS” handler) that plug into the request-processing pipeline.

In the near future, we will make another improvement to the process, by capturing and saving information about the error/exception.


Studying the changes

Open the BetterErrorHandling code example.

Notice the new class in the ServiceLayer folder. It is initialized in the Register method of the WebApiConfig class.

We have included a throw-away controller, CreateErrorController, that you can use to create (generate/cause) different kinds of errors. Just for fun. Use Fiddler to test your interaction with the controller.


Documentation for your web service

As you would expect, there are different kinds of documentation in a web service:

  1. Code comments
  2. Out-of-band (web page) documentation for users/requestors
  3. Embedded documentation in responses (hypermedia representations)


Code comments are for the programmer (duh). You should add code comments to introduce a section of code that needs it, and to explain logic that is not apparent or is dependent on context or disjointed knowledge.

Note, and reminder: You can – and should, as a new learner – use code comments as a way to create a coding plan or algorithm for a piece of logic. Very useful. Think about the problem, and write out code comments as you work through the step-by-step in your head or while talking to others. Then, it becomes easier to write code, because the coding plan is right in front of you.

Out-of-band documentation is for users/requestors. It is typically presented on a set of web pages. The ASP.NET Web API project type has a very nice documentation generator. If you do your part (explained below), it will automatically generate these web pages. Sweet.

Embedded documentation is found in the responses delivered to users/requestors. Soon, you will learn about hypermedia representations, which implements this idea.

Today (below), you will learn about out-of-band documentation, and get a very brief exposure to embedded documentation.


Code comments, and
Out-of-band (web page) documentation

When you run your app, it loads in a browser. You may have noticed an “API” link on the top-of-page menu strip.



The link will show you pages that are generated by the Web API Help Page feature. This feature is turned on in every new Web API project in Visual Studio 2015. (Its principal author is Yao Huang Lin.)

Its default configuration will show a list of all the requests that can be handled by your app’s controllers. It does this by looking for classes that inherit from ApiController, and then inspecting their methods and routes. The ApiExplorer class enables this feature.

In its default configuration, every documented request has a “Description” field that reads “No documentation available”. We should change that, to make the documentation more useful:



Implementing the Web API Help Page

There are several discrete tasks to fully implement a useful Web API Help Page.

Change the project’s properties

Open the project properties panel, and show the Build settings.

In the “Errors and warnings” settings, add “CS1591” to the “Suppress warnings” textbox. As it suggests, it will suppress warnings for C# compiler warning number 1591.

In the “Output” settings, check (mark) the “XML documentation file” setting, and add a file path name (App_Data\XmlDocument.xml) to the textbox. As it suggests, the compiler will output/save the data to that named file.

Save, and close the project properties panel.



Configure the help page to use the just-configured XML documentation file

Open the source code file that holds the HelpPageConfig class. It’s in Areas > HelpPage > App_Start.

Uncomment the statement that sets/configures the XML documentation file:



Add documentation to controller methods

For each public web service controller method, add XML Documentation Comments.

If you have never used this feature, here’s how to get started: Position the cursor on the line above the method declaration statement. Type a triple slash ( / / / ). That will add the structure. Then, fill it in with useful comments.

Incidentally, you can add XML Documentation Comments to every method and property, in every class, in your project. Then, during coding, Visual Studio will use the data as you write code, and show it with its code sense feature. (Yes, this is how Microsoft has done this for framework-provided code.)



When you build and run your project, the compiler will generate the content it needs to fully configure the Web API Help Page feature.

Please follow the instructions above. They are intended for late 2015 projects. However, you should also read/skim the original documents that describe the Web API Help Page feature, because they include some background information and so on. Be careful, because some of the documents are two or three years old, and may not (or will not) apply to current new projects.

Creating Help Pages for ASP.NET Web API, by Mike Wasson, April 2013

Introducing the ASP.NET Web API Help Page, by Yao Huang Lin, August 2012

More info, Part 1, Part 2, and Part 3, by Yao, also from 2012


Configure an initial URI for the web service

docs-initial-uriIn this section, we introduce embedded documentation. The easiest way to understand the concept is to configure an “initial URI” for a web service project. A “root”, in other words.

The idea is that the web service provider can publish one single URI for the web service, and clients/requestors will be able to use that to discover all of the available resources, without the need to look at out-of-band documentation.

The available resources are rendered as a collection of link relations. As a preview, let’s define a link relation as a data object, which informs the client/requestor about links to other resources, and actions that can be performed on the current resource.

To publish an “initial URI” for the web service, we must perform these steps:

  1. Add a default value “Root” for the “controller” placeholder, in the App_Start > WebApiConfig class
  2. Add a new ApiController class (named “RootController”) that uses the value you provided above
  3. Implement a single “get” method, which returns a collection of link relations


Please note that you, as the web service author, will be manually coding and creating these link relations. Soon, you will learn how to programmatically generate link relations.

The LinkRelationsMore code example was enhanced with this feature.


Get started on the assignment

Assignment 5 is now available.

Before leaving the classroom at the end of the timeslot, hand in your work report.





























%d bloggers like this: