Deborah's Developer MindScape : C#, CSharp

Tips for Building a BO for Silverlight and RIA

Deborah Kurata — Mon, 21 Jan 2013 20:13:42 GMT

The following are some tips when building a business object class for use by Silverlight and RIA services.

NOTE: This assumes you are not using Entity Framework (EF).

Use Class-Level Validation

Specifying class-level validation allows you to perform validation on the entire class. This is a good location for cross-field validation.

For example, say you are creating a Discount class that defines discounts available to your customers. A percentage discount must be less than 100% where a dollar discount can be any amount. In the class-level validation, you can check the discount type against the amount to determine if the fields are valid.

Use the CustomValidation attribute to define class-level validation:

In C#:

[CustomValidation(typeof(DiscountValidation), "ValidateDiscount")]
public class Discount

In VB:

<CustomValidation(GetType(DiscountValidation), "ValidateDiscount")>
Public Class Discount

Define a Key

For WCF RIA Services to recognize your objects, they must have a unique key. In most business objects, this is easy because every object relates to a database row that already has a unique key.

In the above Discount example, the discount already has a unique DiscountId associated with it.

Use the Key attribute to define the key field.

In C#:

private int _DiscountId;
[Key()]
public int DiscountId {
    get { return _DiscountId; }
    set
    {
        if (!_DiscountId.Equals(value))
        {
            // Set the value
            _DiscountId = value;
        }
    }
}

In VB:

Private _DiscountId As Integer
<Key>
Public Property DiscountId() As Integer
    Get
        Return _DiscountId
    End Get
    Set(ByVal value As Integer)
        If Not _DiscountId.Equals(value) Then
            ' Set the value
            _DiscountId = value
        End If
    End Set
End Property

NOTE: If you ever have an issue whereby your WCF RIA Service is returning one row when you know you have many rows, chances are that the Key attribute is missing. Without this attribute, RIA views all rows as the same row and therefore only returns one.

Add a String Property for each Numeric Property

If you define a numeric property in your business object, such as an Integer or Decimal, and bind it in Silverlight, Silverlight will automatically convert any entered value to a number. If the user enters "one", it won't generate a validation error. Silverlight instead converts it to a number. Any string converted to a number is 0.

This may not seem likely, but consider the possibility that the user enters 50%. Because of the "%" sign, Silverlight will convert the value to 0 and consider it a valid number.

To have full control over numeric entry, create a string version of any numeric property. Define a Regular Expression to validate that string as an integer or decimal value. And bind that string value to the Silverlight field.

In C#:

[RegularBLOCKED EXPRESSION

Enjoy!

Adding Tables with SSDT

Deborah Kurata — Mon, 22 Oct 2012 06:12:55 GMT

OK, no more SSDT jokes! SSDT, or SQL Server Data Tools, give you the features of SQL Server Management Studio within Visual Studio 2012. You can use the SQL Server Object Explorer from the SSDT to create and maintain tables in your databases.

See this link for an introduction to SQL Server Object Explorer.

See this link for details on creating a new database with SSDT.

To add a new table to a SQL Server database:

1) Open the SQL Server Object Explorer toolbox using View | SQL Server Object Explorer from Visual Studio.

2) Drill down to the Databases node, then to your database, then to Tables.

3) Right-click and select Add New Table...

4) Visual Studio creates a new table called "Table" and opens it in the Table designer.

At this point you can use the design grid in the upper left panel or the T-SQL in the bottom panel or any combination of both to define your table.

In the example below, the LastName was added in the upper left panel. Notice that Visual Studio automatically generates the matching T-SQL:

In this example, the FirstName field was added in the T-SQL. Notice that Visual Studio automatically generates the matching row in the grid:

To name the table, edit the Create Table statement in the T-SQL.

You can use the Properties window (View | Properties Window) to set additional properties for the fields on the table, such as the Identity information.

When you are done with the table design, click the Update button in the upper left corner. Visual Studio presents a preview dialog:

Click Generate Script to create a deployment script containing the T-SQL. Click Update Database to directly update the database with the new table.

A few issues I have had working with the Table designer:

There are sometimes issues when the Table designer is not docked to the main window, meaning that it is either floating or docked to another tab raft (say on a second monitor). At some point, the window stops accepting keyboard input. I have to then re-dock the window to type anything more.
The only way I was able to get the primary key to be named (instead of unnamed) is to remove the primary key and reset it after naming the table.
I was not able to set the table's name using the Properties window.

Use the SQL Server Object Explorer any time you need to add or edit the table structure of your database.

Enjoy!

Adding a New Database with SSDT

Deborah Kurata — Mon, 22 Oct 2012 03:58:56 GMT

No, SSDT is not a disease; it is a set of SQL Server Data Tools that are included as part of Visual Studio 2012. You can use the SQL Server Object Explorer from the SSDT to maintain or view your databases.

See this link for an introduction to SQL Server Object Explorer.

To create a new database:

1) Open the SQL Server Object Explorer toolbox using View | SQL Server Object Explorer from Visual Studio 2012.

2) Drill down to the Databases node.

3) Right-click and select Add New Database.

4) Visual Studio creates a database named "New Database" by default and provides an opportunity for you to change the name.

5) In this example, the database was named "Customer". Open the new database's node to view the created folders.

You can then create tables, views, stored procedures, or whatever.

Use the SQL Server Object Explorer any time you need to create or maintain a database.

Enjoy!

SQL Server Object Explorer in VS 2012

Deborah Kurata — Mon, 22 Oct 2012 00:20:26 GMT

If you use Visual Studio AND SQL Server Management Studio, you'll be glad to hear that the SQL Server Management Studio tools, called SQL Server Data Tools (SSDT), are now a part of Visual Studio 2012. You can create, edit, and delete SQL Server tables and stored procedures, you can write and execute queries, you can view and edit database data, and so on, all from within Visual Studio.

NOTE: You can also get SSDT for Visual Studio 2010 SP1. See this link for more information.

SSDT includes database project types, the SQL Server Object Explorer toolbox, and tools to work with analysis services, reporting services and business intelligence. This post focuses on just the SQL Server Object Explorer.

Select View | SQL Server Object Explorer from the Visual Studio menu to display the toolbox.

If your SQL Server does not appear on the list, click on the Add SQL Server button in the toolbar or right-click on the SQL Server node and select Add SQL Server. Enter the information to connect to one of your SQL Server databases and your SQL Server should then appear on the list.

Once your instance of SQL Server appears on the list, you can drill down to see the databases and their details. You can list the tables, views, and stored procedures under each database.

For example, here are the tables and stored procedures in one of my databases:

Follow these links to see some of the things you can do with the SQL Server Object Explorer:

Use the SQL Server Object Explorer to work with your SQL Server databases in Visual Studio 2012.

Enjoy!

Web API Help Page and XML Comments

Deborah Kurata — Fri, 28 Sep 2012 06:32:24 GMT

The virtues of a Web API Help Page were extolled in a prior post. That prior post demonstrated the "out of the box" functionality of the Microsoft ASP.NET Web API Help Page. This post extends that functionality to include the XML comments from your code.

You can adjust the configuration file for the Help Page to set the documentation provider to your code's XML comments. That way your help file documentation will match the XML comments from your code.

Let's work through an example:

[See this prior post for an introduction to building an ASP.NET Web API service. The service created in that post is the example service used here.]

[[NOTE: The ASP.NET Web API Help Page is in prerelease and does not currently work with VB.NET.]]

Here is the prior example Web API service with XML Comments added:

In C#:

using ACMService.Models;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace ACMService.Controllers
{
    /// <summary>
    /// Provides customer information.
    /// </summary>
    public class CustomerController : ApiController
    {
        /// <summary>
        /// Provides information for the full list of customers.
        /// </summary>
        /// <returns></returns>
        /// <example>GET api/customer</example>
        public IEnumerable<Customer> Get()
        {
            return Customer.Retrieve();
        }

        /// <summary>
        /// Provides information for a single customer by Id.
        /// </summary>
        /// <param name="id">Customer Id</param>
        /// <returns></returns>
        /// <example>GET api/customer/2</example>
        public Customer Get(int id)
        {
            List<Customer> customerList = Customer.Retrieve();
            Customer customerInstance = customerList.FirstOrDefault(
                                    c => c.CustomerId == id);
            if (customerInstance == null)
            {
                throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound)
                    {
                        Content = new StringContent("Could not locate a customer with id: " + id),
                        ReasonPhrase = "Customer Id not found"
                    });
            }
            return customerInstance;
        }
    }
}

In VB:

Imports System.Net
Imports System.Net.Http
Imports System.Web.Http

''' <summary>
''' Privides customer information.
''' </summary>
''' <remarks></remarks>
Public Class CustomerVBController
Inherits ApiController

    ''' <summary>
    ''' Provides information for the full list of customers.
    ''' </summary>
    ''' <returns></returns>
    ''' <example>GET api/customerVB</example>
    Public Function [Get]() As IEnumerable(Of CustomerVB)
        Return CustomerVB.Retrieve()
    End Function

    ''' <summary>
    ''' Provides information for a single customer by Id.
    ''' </summary>
    ''' <param name="id">Customer Id</param>
    ''' <returns></returns>
    ''' <example>GET api/customerVB/2</example>
    Public Function [Get](id As Integer) As CustomerVB
        Dim customerList = CustomerVB.Retrieve()
        Dim customerInstance = customerList.FirstOrDefault(
                    Function(c) c.CustomerId = id)
        If customerInstance Is Nothing Then
            Throw New HttpResponseException(New HttpResponseMessage(HttpStatusCode.NotFound) With
            {
              .Content = New StringContent("Could not locate a customer with id: " & id),
                    .ReasonPhrase = "Customer Id not found"
            })
        End If
        Return customerInstance
    End Function
End Class

To modify the Help Pages to use the XML comments from the above code, follow these steps:

1) Ensure that your code has XML comments. (See the examples above.)

2) Modify the HelpPageConfig file.

Find it in Solution Explorer under your Web API project, Areas / HelpPage / App_Start folder.

3) Uncomment the code line provided in the HelpPageConfig file to set the documentation provider to the XML document generated from your Web API code.

4) Ensure that your build generates the required XML file.

5) Ensure that the XML file name used in the dialog above matches the XML file name defined in the HelpPageConfile file:

config.SetDocumentationProvider(new XmlDocumentationProvider
(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

6) Execute the Web API project in Visual Studio and append "/help" to the address bar of the browser.

The result is shown below:

Notice that the description is now taken from your XML comments.

Drill down to see the detail:

Use these extra steps any time you want to use your Web API XML comments in your help pages.

Enjoy!

Discovering your Web API

Deborah Kurata — Fri, 28 Sep 2012 05:47:18 GMT

If your ASP.NET Web API service is on the 'net and no one is around to explain it, does it provide a service? Unlike no one hearing the tree falling in the woods, this question is more than a philosophical thought experiment. It could be a big issue for the clients needing your service.

[See this prior post for an introduction to building an ASP.NET Web API service. The service created in that post is the example service used here.]

Once you have a Web API service in place, clients can call it. But there is no easy way for those clients to discover the available service methods or their parameters. What they need is a way to view your API.

That's where the Help Page comes in to help you help them. As it states in the dialog below, "The ASP.NET Web API Help Page automatically generates help page content for the Web APIs on your site."

The Help Page is available as a NuGet Package. To install it:

1) Select your Web API service project in Solution Explorer.

2) Select Project | Manage NuGet Packages from the Visual Studio menu.

3) Search for "helppage" using the search box in the upper right corner of the resulting dialog.

4) Click the Install button next to the Microsoft ASP.NET Web API Help Page.

This package adds an Areas directory into the project which contains all of the generated code:

That's it. After you install it you don't have to do anything else.

To view the generated help page, launch your Web API service in Visual Studio and append "/help" to the url in the Address bar of the browser. The generated help page is displayed.

Notice that it contains the name of the controller and descriptions of the two methods in the Web API service.

Click on an action name to drill down. The details provide information on the parameters, if any, and the response body formats. It even contains an example response.

Since all of the code for these help pages are generated into your project, you can easily change them. You can style the layout and change the textual content as desired.

Use the Help Page NuGet package any time you want to provide documentation to the clients of your Web API service.

Enjoy!

Running Your Unit Tests Continuously

Deborah Kurata — Wed, 26 Sep 2012 23:56:45 GMT

One of the new unit testing features in VS 2012 (Premium or Ultimate) is the continuous test runner. When turned on, it automatically executes your unit tests after every successful build.

Digressing a moment … in the early 1990's Shari Lewis and Lamb Chop would sing a version of "The Song that Never Ends" at the end of each episode of their show. In memory of Lamb Chop:

It is the test that never ends.
It goes on and on my friends.
Someone starting running it not knowing what it was,
and they'll continue running it forever just because… <repeat>

To turn on the continuous test runner, select the icon in the upper left corner of the Test Explorer:

The tests will automatically execute asynchronously after each build. They also automatically run when first opening a solution containing the tests.

NOTE: The tests are not executed after a build that is part of a Start With Debugging (F5) or Start Without Debugging operation.

Any failed tests from previous runs are executed first. If they pass, the other (previously passed) tests are executed. If they fail, the other (previously passed) tests are not executed.

This last point has caused me problems. I made a change that would have caused a previously passed tests to fail but I was not notified because I have some other failing tests. I had to manually run the tests in order for the previously passed tests to fail appropriately.

Use the search feature of Test Explorer (detailed in this prior post) to filter the list of tests to execute.

Enjoy!

Adding Simple Exception Handling to your Web API Service

Deborah Kurata — Tue, 25 Sep 2012 06:47:04 GMT

There is nothing perfect in life, not even an ASP.NET Web API service. The service may not understand the provided parameters, or may not find the requested data, or may have trouble connecting to the database. Whatever the issue, if the service cannot return the desired data it would be nice to instead return an appropriate exception notification.

[See this prior post for an introduction to building an ASP.NET Web API service. The service created in that post is the example service used here.]

The following code is the ASP.NET Web API service controller from the example mentioned above, but with a simple exception.

In C#:

using ACMService.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace ACMService.Controllers
{
    public class CustomerController : ApiController
    {
        // GET api/customer
        public IEnumerable<Customer> Get()
        {
            return Customer.Retrieve();
        }

        // GET api/customer/5
        public Customer Get(int id)
        {
            List<Customer> customerList = Customer.Retrieve();
            Customer customerInstance = customerList.FirstOrDefault(
                                    c => c.CustomerId == id);
            if (customerInstance == null)
            {
                throw new ApplicationException("Customer not found");
            }

            return customerInstance;
        }
    }
}

In VB:

Imports System.Net
Imports System.Net.Http
Imports System.Web.Http

Public Class CustomerVBController
Inherits ApiController

    ' GET api/customerVB
    Public Function [Get]() As IEnumerable(Of CustomerVB)
        Return CustomerVB.Retrieve()
    End Function

    ' GET api/customerVB/2
    Public Function [Get](id As Integer) As CustomerVB
        Dim customerList = CustomerVB.Retrieve()
        Dim customerInstance = customerList.FirstOrDefault(
                    Function(c) c.CustomerId = id)
        If customerInstance Is Nothing Then
            Throw New ApplicationException("Customer not found")
        End If
        Return customerInstance
    End Function
End Class

Run the application. Press F12 to launch the F12 developer tools. Select the Network tab and the Start capturing button. [For more information on the F12 tools, see this prior post.]

Then add to the address bar the following: api/customer/10 (api/customerVB/10 in the VB example).

The F12 window displays the request with a result of 500: Internal Server Error. When an exception is thrown in a Web API controller, by default the response is returned with a status code of 500.

Select the request and click the Go to detailed view button to see the details. Click on the Response body tab to see the error message as a JSON string.

Notice that it provides the full stack trace. This can be helpful when debugging the application, but may provide more information than you want to share when your service goes live.

As an alternative, you could use the provided HttpResponseException. By default, this has a header but no content. And instead of always returning a 500 status code, it returns the code you specify.

Change the exception thrown in the example above to instead throw a new HttpResponseException.

In C#:

throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound));

In VB:

throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound))

Repeat the steps above to look at the result with the F12 developer tool:

Notice that the Result is now a 404: Not found. Looking at the detail, there is no body to display.

But what if you do want to provide more information, such as a more detailed message? The HttpResponseException provides properties that allow you to specify more information.

The Content property allows you to provide a response body.

The ReasonPhrase property is a textual description of the status code. You can add any text you would like, such as "Customer Id not found". This may be more useful to the client applications than getting a 404.

Change the exception in the prior example as shown below.

In C#:

throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound)
{
   Content = new StringContent("Could not locate a customer with id: "
                                                     + id),
   ReasonPhrase = "Customer Id not found"
});

In VB:

Throw New HttpResponseException(New HttpResponseMessage(HttpStatusCode.NotFound) With
{
.Content = New StringContent("Could not locate a customer with id: " &
id),
.ReasonPhrase = "Customer Id not found"
})

Repeating the F12 process one more time... Notice that the Response Body now includes the information provided in the Content property.

If you developed the JavaScript client as shown in this prior post, you'll notice that it already has code to handle an exception. The result is shown below:

Use the HttpResponseException whenever you want to control the exception information passed to your ASP.NET Web service clients.

Enjoy!

Building a JavaScript Client for a Web API Service

Deborah Kurata — Mon, 24 Sep 2012 05:54:24 GMT

An ASP.NET Web API service provides support for many different types of client applications. One such client is a JavaScript application. This post provides a very simple JavaScript client you can use to test your Web API service.

[See this prior post for an introduction to building an ASP.NET Web API service. The service created in that post is the example service used here.]

Here is the HTML/JavaScript code to display all of the key/value pairs for a single object returned by a Web API service.

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Customer Information</title>
    <script src="../../Scripts/jquery-1.7.1.min.js"
        type="text/javascript"></script>
    <script type="text/javascript">
        $(document).ready(function () {
            // Send an AJAX request for Customer Info
            $.getJSON("api/customer/2",
            function (data) {
                // On success, 'data' contains the customer details.
                $.each(data, function (key, val) {
                    // Format the text to display.
                    var str = key + ': ' + val;

                    // Add a paragraph for each property.
                    $('#info').append('<p>' + str + '</p>');
                    })
                })

             // Handle a fail
            .fail(
                function (jqXHR, textStatus, err) {
                    $('#info').html('Error: ' + err);
                });
            });
    </script>
</head>

<body>
    <div>
        <h1>Customer Account Information</h1>
        <p id='info' />
    </div>
</body>

</html>

If you followed the prior post mentioned above and built the sample Web API service, you can delete all of the code from the Index.cshtml file and replace it with the above code.

When you run the application, you get this:

Let's go through the JQuery script code. The example uses the 1.7.1 version of JQuery. The script itself does the following:

$.getJSON: Gets the JSON format of the data returned when passing "api/customer/2" to the Web API service. You can change the url string passed to the service to match any url accepted by your service.
$.each: Iterates over each object, executing a function for each one. In this case, it processes each name/value pair provided by the JSON format.

It builds a string with the name of the field, a colon, and the value.
It adds the string to a paragraph element and then appends the paragraph to an element with an Id of #info.

.fail: Provides error information if an error is returned by the service.

The HTML code displays the header and a paragraph placeholder that is extended by the script.

If you want to display a set of business objects with their name/value pairs, you can change the script as follows:

                $('#info').append('<p>' + 'Item: ' + key + '</p>');
                // Process each customer ("row")
                $.each(row, function (rowKey, rowValue) {

// Format the text to display.
var str = rowKey + ': ' + rowValue;

                    // Add a paragraph for each property.
                    $('#info').append('<p style="text-indent: 5em;">'
                                                      + str + '</p>');
                })
            })
         })

         // Handle a fail
        .fail(
            function (jqXHR, textStatus, err) {
                $('#info').html('Error: ' + err);
            });
        });
</script>

This script includes two .each methods, the first one processes each customer and the second one processes each field of the customer from the JSON.

The result of this script is shown below:

Notice that both scripts could be used for any set of JSON objects returned from a Web API service. You just need to change the url string as appropriate for the service.

Enjoy!

Using IE 9 and F12 to Debug your Web API Service

Deborah Kurata — Mon, 24 Sep 2012 00:39:31 GMT

Internet Explorer 9 allows you to see the HTTP request and response information using the F12 developer tools. This can be useful when debugging or testing your ASP.NET Web API service.

[See this prior post for an introduction to building an ASP.NET Web API service. The service created in that post is the example service used here.]

Start your Web API Service in Visual Studio, viewing it in Internet Explorer 9.

I always forget which key to press for the F12 developer tools, but if I recall correctly, it is F12. :-)

The tool window appears as shown below:

Select the Network tab and click the Start Capturing button to start capturing the HTTP request and response information. Then select the browser window and add "api/customer" (or "api/customerVB" for the VB service) to the address bar. Cancel the request to open or save the result.

Returning to the F12 window, you will see the HTTP request:

Select the api/Customer entry and click the Go to detailed view button. From there, you can view the Request header to see more details on the request. Click the Response body to see the response:

Right-click on the body and select Word Wrap from the context menu to view the JSON in a nicer layout:

Use the F12 tool whenever you need to debug or test your Web API service or any client calling your Web API service.

Enjoy!

The World's Simplest Web API/POCO Example

Deborah Kurata — Sun, 23 Sep 2012 23:28:40 GMT

This post demonstrates how to use the ASP.NET Web API to access plain old custom objects (POCO) and build a service for a line of business application. No Entity Framework (EF).

The Web API is a new easy-to-use framework that allows you to build a service that can send or receive data over HTTP to a range of clients. If this sounds something like Windows Communication Foundation (WCF), you are right. But this new framework is MUCH easier to use and provides content that is much easier to consume by client applications.

A Web API service can provide content to .NET clients, but also JavaScript clients and clients written in other languages such as Ruby or Python. It provides that content in different formats such as XML or JSON (JavaScript Object Notation).

The example in this post is as absolutely simple as possible to help you get up and running with these technologies. To meet this goal, this first post covers how to build a service that only provides data. Later posts will cover building clients to get the data, and updating the service for insert and update operations.

So first, the prerequisites:

If you are using Visual Studio 2012 you are ready.
If you are using Visual Studio 2010, download and install ASP.NET MVC 4 for Visual Studio 2010 SP1 and Visual Web Developer 2010 SP1.

Since Visual Studio 2012 is now officially released, the screen shots in this post are all of the Visual Studio 2012 tools.

STEP 1: Create the Web API project.

1) In Visual Studio, select File | New | Project

2) Select the ASP.NET MVC 4 Web Application under the Visual Basic or Visual C# templates and click OK.

3) Select Web API as the project template and click OK.

Visual Studio creates all of the files you need to get started with your Web API service.

The resulting code is complete enough to execute. If you run the application at this point (F5) it appears as follows:

To see the data provided by the default service, add "api/values" to the end of the string in the address bar. The result is something like: http://localhost:2152/api/values. You will then be asked to open or save the data returned by the service. Select to Open and if asked, select to open with Notepad. The result is:

So the default pre-built service returns two values in JSON format called "value1" and "value2". Yes, well it is a start.

The key parts of code required for a Web API service are the Models and the Controllers.

The Models provide the content for your service. They define which data or other content that your service will expose to client applications. For example, for the Acme Customer Management application, the models could include Customer, Purchase, and Invoice. These would expose basic customer information, customer purchasing information, and customer invoice information.

No models are created for you in this case. They are created manually as defined in the next step.

The Controllers basically control your service. They define the actions that your service accepts and performs the response appropriate for the requested action. For example the Acme Customer Management application would provide a Get action that would return the list of all of the customers and a Get action with a key that would provide information for a specific customer.

Two controllers are created in the generated code. The HomeController is a MVC controller which controls the generated sample user interface. The ValueController is the sample Web API controller that provided the two values shown in the screen shot above. You can delete it.

STEP 2: Add your Model

The service is this example provides customer information. That information is defined in the model with a Customer class.

1) Right-click on the Models folder in Solution Explorer and select Add | Class.

2) Add the code for a Customer class.

In C#:

using System.Collections.Generic;

namespace ACMService.Models
{
    public class Customer
    {
        public int CustomerId { get; set; }
        public string LastName { get; set; }
        public string FirstName { get; set; }
        public string EmailAddress { get; set; }

        /// <summary>
        /// Retrieves a list of customers.
        /// </summary>
        /// <returns></returns>
        /// <remarks>
        /// In a "real" application, this code would
        /// call a data access component that retrieves
        /// the data from a database.
        /// </remarks>
        public static List<Customer> Retrieve()
        {
            List<Customer> custList = new List<Customer>
                    {new Customer()
                          { CustomerId = 1,
                            FirstName="Bilbo",
                            LastName = "Baggins",
                            EmailAddress = "bb@hob.me"},
                    new Customer()
                          { CustomerId = 2,
                            FirstName="Frodo",
                            LastName = "Baggins",
                            EmailAddress = "fb@hob.me"},
                    new Customer()
                          { CustomerId = 3,
                            FirstName="Samwise",
                            LastName = "Gamgee",
                            EmailAddress = "sg@hob.me"},
                    new Customer()
                          { CustomerId = 4,
                            FirstName="Rosie",
                            LastName = "Cotton",
                            EmailAddress = "rc@hob.me"}};
            return custList;
        }
    }
}

In VB:

''' <summary>
''' Manages a customer
''' </summary>
''' <remarks></remarks>
''' <editHistory></editHistory>
Public Class CustomerVB
    Public Property CustomerId As Integer
    Public Property FirstName() As String
    Public Property LastName() As String
    Public Property EmailAddress() As String

    ''' <summary>
    ''' Retrieves a list of customers.
    ''' </summary>
    ''' <returns></returns>
    ''' <remarks>
    ''' In a "real" application, this code would
    ''' call a data access component that retrieves
    ''' the data from a database.
    ''' </remarks>
    Public Shared Function Retrieve() As List(Of CustomerVB)
        Dim custList As New List(Of CustomerVB) From
                    {New CustomerVB() With
                          {.CustomerId = 1,
                            .FirstName = "Bilbo",
                            .LastName = "Baggins",
                            .EmailAddress = "bb@hob.me"},
                    New CustomerVB() With
                          {.CustomerId = 2,
                            .FirstName = "Frodo",
                            .LastName = "Baggins",
                            .EmailAddress = "fb@hob.me"},
                    New CustomerVB() With
                          {.CustomerId = 3,
                            .FirstName = "Samwise",
                            .LastName = "Gamgee",
                            .EmailAddress = "sg@hob.me"},
                    New CustomerVB() With
                          {.CustomerId = 4,
                            .FirstName = "Rosie",
                            .LastName = "Cotton",
                            .EmailAddress = "rc@hob.me"}}
        Return custList
    End Function
End Class

NOTE: This code does not use a data access layer at this time. To keep this example as simple as possible, the Retrieve method "mocks" a retrieve that would call your data access component and retrieve the data from the database. This code will be replaced in a later post to actually access a database.

NOTE: Normally I build a Customer class (singular) with the properties and methods that mange a singe customer and a Customers class (plural) that works with a list of those customers. The functionality for both were added to one class to keep this example as simple as possible.

Step 3: Add your Controller

The controller in this example provides two operations: one to get all customers, and one to get one customer by Id.

1) Right-click on the Controllers folder in Solution Explorer and select Add | Controller.

2) Select Empty API Controller

Visual Studio provides several scaffolding options, which define the type of code that it will automatically generate in the controller. To keep this example simple, it will only provide read actions, so select Empty API Controller.

3) Write the code for the controller.

In C#:

using ACMService.Models;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

        // GET api/customer/2
        public Customer Get(int id)
        {
            List<Customer> customerList = Customer.Retrieve();
            Customer customerInstance = customerList.FirstOrDefault(
                                c => c.CustomerId == id);
            return customerInstance;
        }
    }
}

In VB:

Imports System.Net
Imports System.Web.Http

Public Class CustomerVBController
Inherits ApiController

    ' GET api/customerVB
    Public Function [Get]() As IEnumerable(Of CustomerVB)
        Return CustomerVB.Retrieve()
    End Function

The controller class inherits from ApiController. This ensures that the service understands that this is a Web API controller class.

The class is called CustomerController (CustomerVBController in the VB example). The name should define the type of content the controller provides and end with "Controller". The service automatically locates the controller by name. To access the CustomerController, you would add "api/Customer" to the address bar and .NET automatically executes the Get method in the CustomerController class. (Enter api/CustomerVB to call the CustomerVBController.)

Both functions are named "Get". Note that in VB, "Get" is a keyword so it needs brackets around it to use it as a function name. But you could change the name to something more specific like GetCustomer.

The functions contain code to provide the requested data. The Get without any parameters retrieves the entire list. The Get with the id parameter uses LINQ with a Lambda expression to find the requested customer in the list. (For an overview of Lambda expressions, see this link.)

NOTE: This is not the most efficient approach to retrieve one customer. You would instead want to get the one requested customer from the database.

Now when you run the application, the same Welcome page appears because we have not changed the UI. And since we are building a service, we could actually remove the default UI.

To get the customer data, add "api/customer" to the address bar. ("api/customerVB" if you are running the VB example.)

If you open the results in Notepad, you will see the following:

If you instead add "api/customer/2" to the address bar ("api/customerVB/2" in VB), you get this:

Use this basic set of steps as a starting point for building your Web API service.

Enjoy!

Test Explorer in Visual Studio 2012

Deborah Kurata — Mon, 17 Sep 2012 00:30:02 GMT

One of the new things about testing in Visual Studio 2012 is that it is now available in *all* editions of Visual Studio all the way to Visual Studio Express!

The Test Explorer in Visual Studio 2012 replaces the Test View window in Visual Studio 2010. The following posts outline the Test Explorer features:

Enjoy!

101 Ways to Run Tests with Visual Studio 2012

Deborah Kurata — Sun, 16 Sep 2012 20:59:09 GMT

OK 101 is an exaggeration, but there are many ways to run your tests in Visual Studio 2012.

From the test code file

While you are writing or editing a test method, you can right click anywhere within the method and run or debug the test.

[Red rectangle added for illustration.]

All of the tests in Test Explorer are displayed "grayed out" except for the executed test as shown below. Click on the test to view the result details in the right pane (or bottom pane if your Test Explorer is sized to display vertically).

From the code editor, you can also run all of the tests within a code file by right-clicking anywhere within the code file, but outside of a specific method. Clicking in an empty space between two methods, for example, will execute all of the tests in the code file.

From Test Explorer Toolbar

View the Test Explorer window using Test | Windows | Test Explorer. The Test Explorer window toolbar provides many ways to run your tests.

Run All
Runs all of the tests displayed in Test Explorer. If the list of tests are filtered by search criteria, only the filtered tests are executed. (See this prior blog post for information on searching within Test Explorer.)
Run Failed Tests
Runs only the failed tests displayed in Test Explorer.
Run Not Run Tests
Only runs the tests displayed in Test Explorer which were not previously run since opening Visual Studio.
Run Passed Tests
Runs only the passed tests displayed in Test Explorer.
Repeat Last Run
Runs the prior test run again, but only on the files displayed in Test Explorer. If you Run All then filter the tests in Test Explorer then Repeat Last Run, only the filtered tests will be executed again.

From Test Explorer Context Menu

Right-clicking on a test in Test Explorer provides run options.

You can select a single test, multiple tests using the Ctrl and Shift keys, or all tests using the Select All option from the context menu. Then you can Run or Debug the selected tests.

Use these techniques to run only the tests you are interested in.

Enjoy!

Searching and Grouping in VS 2012 Test Explorer

Deborah Kurata — Sun, 16 Sep 2012 19:59:50 GMT

Visual Studio 2012 Test Explorer has extensive searching and limited grouping capabilities. (Visual Studio 2010's Test View window had more grouping options by way of its many sorting parameters.)

Searching

Entering text into the Test Explorer Search box filters the list of tests to those containing the entered text. In the example below, entering "customer" in the search box filters the list to all test names containing "customer".

By default, the search matches within the test name, but there are other choices. To view the other options, click the down arrow to the right of the Search box in the toolbar as shown below. Even though it looks a little like one large option name, these are actually three options:

Test File Path
Fully Qualified Name
Test Result

Select one of these options, then type the search parameter within the provided quotation marks. Press the Enter key to execute the search.

Test File Path searches the paths to the test code files. In this example, the tests are in two components in two different directories:

C:\Users\Deborah\Speaking\Other\AcmeCustomerManagement_BestKeptSecrets_2012\ACM.LibraryCSharpTest
C:\Users\Deborah\Speaking\Other\AcmeCustomerManagement_BestKeptSecrets_2012\ACM.BLCSharpTest

The above example finds all of the tests in the LibraryCSharpTest component.

Fully Qualified Name searches the path and file name.

Test Result has several valid search parameters: "Not Run", "Skipped", "Passed" or "Failed". These options filter the list to defined test outcome.

Grouping

By default, the Test Explorer groups the tests by test outcome as shown in the prior screen shots. The only other group-by option is by duration. This groups by the time it took to execute the test.

Use these techniques to filter and group the tests in the Test Explorer window.

Enjoy!

EDITED 9/28/12 to correct typographical errors.

Layout of Test Explorer in Visual Studio 2012

Deborah Kurata — Sun, 16 Sep 2012 01:18:47 GMT

In Visual Studio 2012, the Visual Studio 2010 Test View window has been replaced by a new Test Explorer window.

By default, it appears on the left side of the Visual Studio Interactive Development Environment (IDE) as shown below:

(Red box added for illustration)

When you run the unit tests, the result appears in the bottom panel of the Test Explorer window:

Since many unit tests may have the same prefix and a long and descriptive name, docking the Test Explorer on the left often cuts off the unique portions of the names. Instead of making the window wider, consider moving it to the bottom:

(Red box added for illustration)

The test results now appear in the right panel of the Test Explorer window:

Moving the Test Explorer window from the left side to the bottom gives you more horizontal space to view the tests and their execution times. It also gives you more space to view the test results.

Enjoy!

Solution Explorer in Visual Studio 2012

Deborah Kurata — Sun, 09 Sep 2012 22:53:02 GMT

There are lots of new Solution Explorer features in Visual Studio 2012, so many that they did not all fit into one blog post. The following are posts that outline the new features:

Enjoy!

Solution Explorer Sync'ing in Visual Studio 2012

Deborah Kurata — Sun, 09 Sep 2012 02:08:10 GMT

This is just a little feature, but a very useful one: Solution Explorer now allows you to control the sync to the currently active tab.

In prior versions of Visual Studio, Solution Explorer automatically synchronized its position to the active tab. When you clicked on a tab, Solution Explorer positioned itself to that file.

This was frustrating when you were working on files in a particular component. You click on another tab to look at something and Solution Explorer automatically jumped to that file. It was possible to turn off this behavior using Tools | Options, but then you could never find where you were in Solution Explorer.

In Visual Studio 2012, Solution Explorer allows you to define when it should synchronize to the current tab. Here is how it works:

First, open one code file from one of your components and another code file from another component. The results will look something like the figure below.

In the above example, the Customers.cs and the CustomerWin.cs files are opened. Solution Explorer has the CustomerWin.cs highlighted.

Click on the other tab, Customers.cs in this example. Notice that Solution Explorer does not automatically sync up to the selected tab.

If you do want Solution Explorer to sync up at any time, click the Sync button in the Solution Explorer toolbar.

[The red box around the sync button was added for illustration.]

If you want the old behavior, where Solution Explorer tracks with the active tab, you can use Tools | Options:

[The red box around the sync button was added for illustration.]

Use the new Sync button any time you want to sync Solution Explorer to the active tab.

Enjoy!

Visual Studio 2012: Did You Call Me?

Deborah Kurata — Tue, 04 Sep 2012 01:42:05 GMT

As you debug and refactor your application, you often want to know who called whom. Visual Studio has always provided features to help you with that, but Visual Studio 2012 provides more.

With the following, you can determine which properties and methods called which properties and methods:

Solution Explorer features (new in VS 2012)
Call Stack
Call Hierarchy (new in VS 2010 for C#; VS 2012 for VB)
Find all References

Solution Explorer

The new Solution Explorer in Visual Studio 2012 allows you to drill down from a code file to the classes, properties, and methods within that code file. From a property or method, you can view all of the properties or methods it calls. Or you can view all of the properties and methods that call it. Or you can view each line of code that uses it.

In Solution Explorer, drill down from a project to a class to a property or method. Right-click on the property or method to view the context menu.

Select the Calls option to see all of the properties and methods that the selected property or method calls. For example, the FindCustomers method calls the following properties and methods:

Select Is Called By to see all of the properties and methods that call the selected property or method. For example, the FindCustomers method is called by the following methods:

Select Is Used By to see each line of code that uses the the selected property or method. For example, the FindCustomers method is called by the following lines of code.

In all of these scenarios, you can click on a result to view it in the Preview Tab or double-click on a result to view it in a normal tab.

Call Stack

The Call Stack (Debug | Windows | ) is only available when debugging. From it, you can see all of the calls that led to the break point. Double-click on an entry in the Call Stack to jump to that location in the code.

Call Hierarchy

The Call Hierarchy (View | Call Hierarchy) is only available when debugging. Right-click on a property or method name in the code window when on a break point and select View Call Hierarchy.

The left pane displays the "calls to" and the "calls from" the selected property or method. Clicking on one of the properties or methods displays the associated line(s) of code.

Find All References

This one has been around for a while, so I probably don't need to provide any instructions. Just right-click on any property or method in a code file and select Find All References from the context menu.

Use these techniques any time you need to navigate the call stack.

Enjoy!

Solution Explorer Scoping in Visual Studio 2012

Deborah Kurata — Mon, 03 Sep 2012 17:23:46 GMT

In prior versions of Visual Studio, the Solution Explorer has been basically static. With Visual Studio 2012, it is much more dynamic with features such as filtering and scoping.

[For information on the filtering features, see this prior blog post.]

The scoping feature allows you to limit the display of Solution Explorer to one specific folder, project, code file, or class. This allows you to more easily find the code you want to work with during a particular coding session.

For example, if you are building an MVVM application you could scope Solution Explorer on one monitor to your Views folder and Solution Explorer on another monitor to your ViewModels folder. [For more information on displaying Solution Explorer on a second monitor see this upcoming post.]

To scope Solution Explorer to a folder, right-click on the folder and select "Scope To This" from the context menu.

To return to the full list of folders and files, click the Home button in Solution Explorer's toolbar.

Scoping to a class provides a quick way to access any property or method in the class. Right-click on a class in Solution Explorer and select "Scope to This" from the context menu.

Use the scoping features of Solution Explorer any time you want to focus on a specific folder, code file, or class during your coding session.

Enjoy!

Solution Explorer Filtering in Visual Studio 2012

Deborah Kurata — Mon, 03 Sep 2012 01:39:24 GMT

In prior versions of Visual Studio, the Solution Explorer has been basically static. With Visual Studio 2012, it is much more dynamic with features such as filtering and scoping.

[For information on the scoping features, see this prior blog post.]

The filtering feature allows you to filter the contents of Solution Explorer to files containing the entered text. Depending on your settings, it will find within the file name and within the contents of any code file.

This allows you to focus on specific files or files containing specific classes, properties, or methods. For example, if you are working on an MVVM application, you can filter to "Invoice" to find the model, view, and view/model for the invoice feature.

The filtering uses a "contains" style of matching, so it finds the match anywhere in the file name or in the code file classes, properties, and methods. It can also match using Pascal casing. Typing CFW will match any Pascal-cased string with the entered letters, such as CustomerFindWindow.

Searching for "Customer":

In this example, "Customer" is found in both the file names, such as Customer.cs, and in the contents of the code files, such as the Customer class, the CustomerList property, and the FindCustomers method.

To limit the search to only the file names, turn off the "Search within file contents" by unchecking it in the search options.

You can also uncheck "Search within external items", which turns off searching of external items, such as those in the External Dependencies folders. (I spent some time this afternoon trying to determine what this actually means and did not have a lot of luck. Best I can find, it prevents searching within the C/C++ External Dependencies folder. If anyone has found any more information on this, I'd love to hear about it. Please post in the Comments section of this post.)

Turning off "Search within file contents" provides these results:

Searching for CFW results in:

In this example, any file names, classes, properties, or methods that are Pascal cased to match CFW are included in the filtered list.

Notice, however, the difference between the C# project and the VB project in the above example. This difference is because the filtering does not search through hidden folders/files by default. In VB, the designer file is hidden.

To search through hidden files and folders, select the project and then click the Show All Files button in the Solution Explorer toolbar. Then the VB designer file will be found.

To turn off the results and return to the full list of files, click the Home button on the Solution Explorer toolbar. Solution Explorer is then reset to its original file list.

Use these techniques any time you want to filter Solution Explorer to specific folders, files, classes, methods, or properties in your solution.

Enjoy!