Now paging can be implemented in one of two ways:

• Client-driven paging:  The client decides how big of a page it wants to display and asks the server for a page of that size. So in our previous example, the client would be saying "Give me twenty comedies".

• Server-driven paging: The client asks for a collection of entities, and the server sends back partial results as well as a link to use to retrieve more results. In our example, the client would be saying "Give me comedies" and the server would respond with "Here are twenty comedies and here's how to get more of them".

The good news is that the OData support we're adding to Web API adds built-in support for both of these options.

Client-driven paging

The way to implement client-driven paging with Web API is to take advantage of OData's query syntax and the $top query option. $top lets a client ask for a particular number of entities. So all the client would have to do is turn on Web API query support with this attribute on your action:

   1: [Queryable]

   2: public IQueryable<Movie> GetMovies

To get the first twenty comedies, you could then make a GET request for the following URI:

https://server/Movies?$filter=Genre eq 'Comedy'&$top=20

The $filter query option is narrowing down our query to only consider movies that have a category . Since we're not specifying an ordering on the movies, the server will infer a stable ordering based on the entity key so the results would be ordered by the movie ID in this case.

Now this only gets us the first page of comedies. If we want the next page of comedies, we can use the $skip query option to ignore the comedies we've already displayed. So:

https://server/Movies?$filter=Genre eq 'Comedy'&$skip=20&$top=20

Would display comedies 21-40, the next page we need to display.

A word of caution here: using $skip works great if your movie data isn't changing. But if you're inserting new movies into your database, it can cause movies to appear twice in your results. And if you're deleting movies, it can cause movies not to appear at all. If this is an issue for you, you should consider getting subsequent pages in a different way. You can use the properties you're ordering by and the value of these properties in the last entity of the current page to create a request that gets the next page. Let's demonstrate with an example. We've been ordering our movies by ID so far. So let's say we get the first page of comedies and the last comedy we get back has ID equal to 86. We could request the next page of comedies with a request for the following URI:

https://server/Movies?$filter=Genre eq 'Comedy' and ID gt 86&$top=20

This retrieves the first twenty comedies with an ID greater than 86, which is exactly what we need to display our second page. And even if new movies are inserted or movies are deleted, we'll avoid displaying the same movie twice or missing a movie.

Server-driven paging

In our previous examples, the client always needed to send "$top=20" to let the server know that it shouldn't send back more than twenty movies. But you can also choose to let the server control paging instead. You'll just need to slightly tweak your [Queryable] attribute like this:

   1: [Queryable(PageSize=20)]

   2: public IQueryable<Movie> GetMovies

This limits the number of movies to send back to the client to 20. If the query for this action yields fewer than or exactly twenty results, then nothing happens and the results are sent as if there were no paging. But if the query yields more than twenty results, then the server will only send back the first twenty results and add a next page link to the response body to give the client a way to get the next page of links. So for a request to this URI:

https://server/Movies?$filter=Genre eq 'Comedy'

Here's what the response body might look like:

   1: {

   2:   "odata.metadata":"https://localhost:23645/api/$metadata#Movies","value":[

   3:     {

   4:       "ID":17,"Title":"Six Days Seven Nights","ReleaseYear":1998,"Genre":"Comedy","Rating":2,"Popularity":6

   5:     },

   6:     ...

   7:     {

   8:       "ID":57,"Title":"Army of Darkness","ReleaseYear":1992,"Genre":"Comedy","Rating":9,"Popularity":9

   9:     }

  10:   ],"odata.nextLink":"https://localhost:23645/api/Movies?$filter=Genre%20eq%20'Comedy'&$skip=20"

  11: }

Notice that the next link that you see generated is based on $skip and is therefore subject to the same limitations as discussed earlier. The client can always choose to ignore this next page link and create one based on ordering instead.

Using the $inlinecount query option

So far, we've shown how clients can display pages of results in two different ways. It's fairly easy for clients to navigate to the next page by using the next page link or by generating one. And it's also fairly easy for clients to navigate to previous pages just be remembering the URI associated with the previous pages. But there is one additional piece of information that is very useful for paging in a web application: how many pages are there anyways?

This is where the $inlinecount query option comes in. $inlinecount can be applied to any query to get the server to send back the total number of entities matching the request. Let's see an example in action. For a request to this URI:

https://server/Movies?$filter=Genre eq 'Comedy'&$inlinecount=allpages

We'd get back the following response body if we had a page size limit on the server:

   1: {

   2:   "odata.metadata":"https://localhost:23645/api/$metadata#Movies","odata.count":"799","value":[

   3:     {

   4:       "ID":17,"Title":"Six Days Seven Nights","ReleaseYear":1998,"Genre":"Comedy","Rating":2,"Popularity":6

   5:     },

   6:     ...

   7:     {

   8:       "ID":57,"Title":"Army of Darkness","ReleaseYear":1992,"Genre":"Comedy","Rating":9,"Popularity":9

   9:     }

  10:   ],"odata.nextLink":"https://localhost:23645/api/Movies?$filter=Genre%20eq%20'Comedy'&$inlinecount=allpages&$skip=20"

  11: }

We now have a count in our response body. This count represents the total number of comedies in the server's database. The client can use this information to infer the number of pages that can be displayed, like this for example:

   1: var numberOfPages = Math.ceiling(count / pageSize);

Web API testing can be broadly categorized into one of three groups:

• Unit testing a controller in isolation
• Submitting a request to an in-memory HttpServer and testing the response you get back
• Submitting a request to a running server over the network and testing the response you get back

Unit Testing Controllers

The first and simplest way of testing a Web API service is to unit test individual controllers. This means you'll first create an instance of the controller. And then call the Web API action you want to test with the parameters you want. Finally, you'll test that the action did what it was supposed to do, like updating a database for example and that it returned the expected value.

To illustrate the different ways of testing Web API services, let's use a simple example. Let's say you have an action that gets a movie by its ID. The action signature might look like this:

   1: public class MoviesController : ApiController

   2: {

   3:     public Movie GetMovie(int id);

   4: }

Let's give this method the following contract. If the movie ID exists in our database, it should return the corresponding movie instance. But if there isn't a movie with a matching ID, it should return a response with a 404 Not Found status code. An example of a unit test for this action might look like this:

   1: [Fact]

   2: public void GetMovie_ThrowsNotFound_WhenMovieNotFound()

   3: {

   4:     var emptyDatabase = new EmptyMoviesDbContext();

   5:     var controller = new MoviesController(emptyDatabase);

   6:     HttpResponseException responseException = Assert.Throws<HttpResponseException>(() => controller.GetMovie(1));

   7:     Assert.Equal(HttpStatusCode.NotFound, responseException.Response.StatusCode);

   8: }

As a general principle, you should always try to test as little as possible and unit testing controllers is as simple as it gets.

Submitting requests against an in-memory HttpServer

Unit testing controllers is great, and you should be trying to do so whenever you can. But it does have its limitations. First off, Web API sets up state on the controller like the Request or the Configuration properties that may be needed for your action to function properly. It also sets properties on the request that are used by certain methods. Commonly used methods in the framework like Request.CreateResponse work fine in a normal Web API pipeline, but will not work when unit testing a controller unless you configure some additional properties.

Secondly, unit testing a controller doesn't cover everything else that might go wrong with your service. If you're using custom message handlers, routing, filters, parameter binders, or formatters, none of that is accounted for when unit testing. And even if you're using all the defaults, the request might never make it to your action or might result in your action being called with the wrong parameters. Unit testing doesn't help at all with this kind of issue.

And thirdly, unit testing doesn't always help you figure out what the HTTP response looks like. Maybe you really care about a certain HTTP header being set on the response or maybe you care about your response sending back the right status code to the client. If your action returns an HttpResponseMessage or throws an HttpResponseException like our example above, then you may be able to inspect and test the response. But otherwise, you won't get any insight into what response will actually be received by the client.

The recommended way to deal with all these issues is to set up an HttpServer, create a request you want to test, and submit it to the server. You can then test the response you get back and make sure it matches your expectations. One of the advantages of Web API's architecture is that you can do this without ever having to use the network. You can create an in-memory HttpServer and simply pass requests to it. It will simulate the processing of the request and return the same response you would have gotten if it were a live server.

Here's what the same unit test we wrote earlier would look like:

   1: [Fact]

   2: public void GetMovie_ReturnsNotFound_WhenMovieNotFound()

   3: {

   4:     HttpConfiguration config = new HttpConfiguration();

   5:     config.Routes.MapHttpRoute("Default", "{controller}/{id}");

   6:     HttpServer server = new HttpServer(config);

   7:     using (HttpMessageInvoker client = new HttpMessageInvoker(server))

   8:     {

   9:         using (HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, "https://localhost/Movies/-1"))

  10:         using (HttpResponseMessage response = client.SendAsync(request, CancellationToken.None).Result)

  11:         {

  12:             Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);

  13:         }

  14:     };

  15: }

If you wanted to test the response body instead, you could use these lines:

   1: ObjectContent content = Assert.IsType<ObjectContent>(response.Content);

   2: Assert.Equal(expectedValue, content.Value);

   3: Assert.Equal(expectedFormatter, content.Formatter);

Submitting requests against a running HttpServer

The last way to write a Web API test is to start a running server that's listening to a network port and send a request to that server. Usually, that involves starting up WebAPI's self-host server like this:

   1: [Fact]

   2: public void GetMovie_ReturnsNotFound_WhenMovieNotFound()

   3: {

   4:     HttpSelfHostConfiguration config = new HttpSelfHostConfiguration("https://localhost/");

   5:     config.Routes.MapHttpRoute("Default", "{controller}/{id}");

   6:     using (HttpSelfHostServer server = new HttpSelfHostServer(config))

   7:     using (HttpClient client = new HttpClient())

   8:     {

   9:         server.OpenAsync().Wait();

  10:         using (HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, "https://localhost/Movies/-1"))

  11:         using (HttpResponseMessage response = client.SendAsync(request).Result)

  12:         {

  13:             Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);

  14:         }

  15:         server.CloseAsync().Wait();

  16:     };

  17: }

To test the response body instead, you could write:

   1: Assert.Equal(expectedResponseBody, response.Content.ReadAsStringAsync().Result);

If at all possible, you should try avoiding writing these kinds of tests. Instead of just testing the service, you're testing a whole lot more - you're testing the client, you're testing the operating system's networking stack, and you're testing the host for your service. Whenever you test more than you have to, you expose yourself to potential issues at other layers that can make test maintenance and debugging a nightmare. For example, you might now have to run your tests with administrator privileges for the self host server to open successfully.

Now with all that said, there may be cases where this kind of test is the most appropriate. If you need to test that a client and a server can communicate, it's usually better to test the client and the server individually. You can test that the client is sending the request you expect it to send, and then you can test that the server returns the expected response given that request. But there may be cases where the hosting actually matters and you need to make sure that the client request actually makes it to the Web API server correctly. The best example that comes to mind is if you're using SSL/TLS and you want to make sure that the connection is working. You might then write one test against a running server to check that the connection is working, and write the rest of your tests as unit tests or against an in-memory server to check that the service is handling requests the way you'd expect it to.

Before we get started, there are a few requirements for using WebSockets. It must be supported by both the browser and the web server. The WebSocket protocol is currently supported in Chrome, Firefox, and Safari and will be supported in the upcoming Internet Explorer 10 release. On the server side of things, you will need Windows 8 (or Windows Server 2012) to support WebSockets. Now you may not always be able to guarantee that your client browser and your web server support WebSockets. If that’s your case, I highly recommend you take a look at SignalR. SignalR provides you with the abstraction of a real-time, persistent connection without having to worry about how the data is being sent back and forth between the browser and the server.

Now once you’ve met the requirements, you’ll need to enable support for WebSockets on IIS. You can do so by going through Control Panel > Programs > Turn Windows features on or off. You’ll then need to make sure the following boxes are checked:

• Internet Information Services > World Wide Web Services > Application Development Features > ASP.NET 4.5
• Internet Information Services > World Wide Web Services > Application Development Features > WebSocket Protocol
• .NET Framework 4.5 Advanced Services > ASP.NET 4.5

Next, it’s time to write our app. Start by creating a new Empty ASP.NET MVC 4 App in Visual Studio 2012. Create a new HTML page called “chat.htm” with this in the body:

   1: <form id="chatform" action="">

   2:     <input id="inputbox" />

   3: </form>

   4: <div id="messages" />

   1: $(document).ready(function () {

   2:  

   3:     var username = prompt('Please enter a username:');

   4:  

   5:     var uri = 'ws://' + window.location.hostname + window.location.pathname.replace('chat.htm', 'api/Chat') + '?username=' + username;

   6:     websocket = new WebSocket(uri);

   7:  

   8:     websocket.onopen = function () {

   9:         $('#messages').prepend('<div>Connected.</div>');

  10:  

  11:         $('#chatform').submit(function (event) {

  12:             websocket.send($('#inputbox').val());

  13:             $('#inputbox').val('');

  14:             event.preventDefault();

  15:         });

  16:     };

  17:  

  18:     websocket.onerror = function (event) {

  19:         $('#messages').prepend('<div>ERROR</div>');

  20:     };

  21:  

  22:     websocket.onmessage = function (event) {

  23:         $('#messages').prepend('<div>' + event.data + '</div>');

  24:     };

  25: });

This JavaScript depends on the JQuery library. Note how we’re sending a username in the query string for our initial web socket, and note how we’re sending messages over the websocket whenever a message is submitted, and that we display messages received over the websocket as well. Now it’s time to implement our server-side WebSocket handler.

First, let’s make sure that the right route is configured for WebAPI to receive the WebSocket upgrade request. You’ll need to run this command in your Application_Start method:

   1: routes.MapHttpRoute(

   2:     name: "DefaultApi",

   3:     routeTemplate: "api/{controller}/{id}",

   4:     defaults: new { id = RouteParameter.Optional }

   5: );

If you’re using an empty MVC project template, this should already be there for you in RouteConfig.cs. Next, let’s implement our WebAPI controller:

   1: public class ChatController : ApiController

   2: {

   3:     public HttpResponseMessage Get(string username)

   4:     {

   5:         HttpContext.Current.AcceptWebSocketRequest(new ChatWebSocketHandler(username));

   6:         return Request.CreateResponse(HttpStatusCode.SwitchingProtocols);

   7:     }

   8:  

   9:     class ChatWebSocketHandler : WebSocketHandler

  10:     {

  11:         private static WebSocketCollection _chatClients = new WebSocketCollection();

  12:         private string _username;

  13:  

  14:         public ChatWebSocketHandler(string username)

  15:         {

  16:             _username = username;

  17:         }

  18:  

  19:         public override void OnOpen()

  20:         {

  21:             _chatClients.Add(this);

  22:         }

  23:  

  24:         public override void OnMessage(string message)

  25:         {

  26:             _chatClients.Broadcast(_username + ": " + message);

  27:         }

  28:     }

  29: }

Our controller has just one method, Get, which listens for WebSocket upgrade requests. Since the initial upgrade handshake for WebSockets looks just like an HTTP request/response, this allows us to go through the entire WebAPI pipeline just as if it were any other HTTP request/response. This means for example that message handlers will run, action filters get called, and model binding lets us bind the request to action parameters. In the example above, we’ve bound the username from the query string as an action parameter. The Get action then does two things. It first accepts the web socket request and sets up a WebSocketHandler to manage the connection. It then sends back a response with HTTP status code 101, notifying the client that is has in fact agreed to switch to the WebSocket protocol. The ChatWebSocketHandler then just takes care of managing a list of chat clients and broadcasting the message to all clients when it receives a message. So we’re able to have WebAPI handle the initial WebSocket upgrade request and create a web socket handler to manage the lifetime of the connection.

You’ll need the Microsoft.WebSockets NuGet package to be able to build the controller above. Note that because of limitations of the WebSocket feature, you’ll need to deploy the app to IIS or IIS Express. This won’t work in the Visual Studio Development Server. Finally, you’ll need this in your Web.config to get WebSockets working:

   1: <configuration>

   2:   <appSettings>

   3:     <add key="aspnet:UseTaskFriendlySynchronizationContext" value="true" />

   4:   </appSettings>

   5: </configuration>

And there you go, you should be able to deploy your app to IIS and test your chat app. You can try opening multiple browser windows to see chat messages broadcast in real-time to all the chat clients.

Note: Not all of the features I mention below are part of the ASP.NET MVC 4 RC build. You may have to use our nightly Nuget packages to get access to our latest bits. You can find more information about how to do so here: https://aspnetwebstack.codeplex.com/discussions/353867.

Now that’s out of the way, let’s take a look at what a typical WebAPI error’s HTTP content looks like:

{
  "Message": "No HTTP resource was found that matches the request URI 'https://localhost/Foo'.",
  "MessageDetail": "No type was found that matches the controller named 'Foo'."
}

So the error is actually just a collection of key-value pairs that provide information about what went wrong. This collection of key-value pairs is then sent back to the client in whatever content type it asked for through HTTP content negotiation. In the example above, the content is actually JSON.

But if you had “text/xml” in your request’s Accept header for example, you might get this response instead:

<Error>
  <Message>No HTTP resource was found that matches the request URI 'https://localhost/Foo'.</Message>
  <MessageDetail>No type was found that matches the controller named 'Foo'.</MessageDetail>
< /Error>

This simple format makes it easy for clients to understand what went wrong or to extract relevant error information for error logging or reporting.

HttpError

What you just saw above is actually an instance of an HttpError being serialized to the wire by Json.NET and DataContractSerializer respectively.

The HttpError type defines a consistent and extensible way for representing error information across the framework. Effectively, it’s just a Dictionary<string, object> that provides some helpers for creating errors that contain error messages, exceptions, or invalid model states. HttpError defines the following public constructors:

   1: public HttpError();

   2: public HttpError(string message);

   3: public HttpError(Exception exception, bool includeErrorDetail);

   4: public HttpError(ModelStateDictionary modelState, bool includeErrorDetail);

Here’s what HttpErrors for Exceptions look like in JSON:

{
  "Message": "An error has occurred.",
  "ExceptionMessage": "Index was outside the bounds of the array.",
  "ExceptionType": "System.IndexOutOfRangeException",
  "StackTrace": "   at WebApiTest.TestController.Post(Uri uri) in c:\\Temp\\WebApiTest\\WebApiTest\\TestController.cs:line 18\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.<>c__DisplayClassf.<GetExecutor>b__9(Object instance, Object[] methodParameters)\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.Execute(Object instance, Object[] arguments)\r\n   at System.Threading.Tasks.TaskHelpers.RunSynchronously[TResult](Func`1 func, CancellationToken cancellationToken)"
}

And for invalid ModelStates:

{
  "Message": "The request is invalid.",
  "ModelState": {
    "s": [
      "Required property 's' not found in JSON. Path '', line 1, position 2."
    ]
  }
}

But it’s also important to note that you can create your own custom HttpErrors with your own custom error information. Here’s an example:

   1: public HttpResponseMessage Get()

   2: {

   3:     HttpError myCustomError = new HttpError("My custom error message") { { "CustomErrorCode", 37 } };

   4:     return Request.CreateErrorResponse(HttpStatusCode.BadRequest, myCustomError);

   5: }

This results in the following response:

{
  "Message": "My custom error message",
  "CustomErrorCode": 37
}

This is the first example where you’ve actually seen an action implemented that returns an error. Notice that we’re using Request.CreateErrorResponse to create an HttpResponseMessage that wraps our custom error. This is the recommended way to create response messages for errors. The following extension methods are provided to make it easy to return errors from your own code as well:

   1: public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, Exception exception);

   2: public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, HttpError error);

   3: public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, ModelStateDictionary modelState);

   4: public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, string message);

   5: public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, string message, Exception exception);

You can also choose to just throw any exception from your action. WebAPI will automatically catch the exception and convert it into an error response with status code 500 (Internal Server Error) in exactly the same format as an error response that you would have created for an exception in your own code.

HttpResponseException

Now you may be wondering: how do I return an error if my action returns a different type instead of HttpResponseMessage? This is where HttpResponseException comes in. HttpResponseException is an exception type defined for WebAPI that serves two purposes:

1. It allows you to return a specific HTTP response from actions with return types that aren’t HttpResponseMessage.
2. It allows you to short-circuit the WebAPI pipeline pretty much anywhere and return a response immediately.

Technically, HttpResponseException can be used for any kind of HTTP response, but it’s especially useful in error cases. It allows us to implement actions like this:

   1: public Person Get(int id)

   2: {

   3:     if (!_contacts.ContainsKey(id))

   4:     {

   5:         throw new HttpResponseException(Request.CreateErrorResponse(HttpStatusCode.NotFound, String.Format("Contact {0} not found.", id)));

   6:     }

   7:  

   8:     return _contacts[id];

   9: }

Notice how even though the action is declared to return a Person, we’re able to return a custom error back to the client in error cases.

Error Detail

You may have noticed the “includeErrorDetail” parameter earlier in this post on the HttpError constructor. This is because typically, servers want to send different error information depending on whether the client is just consuming the service or whether the client needs additional debugging information to understand what went wrong on the server. By default, WebAPI will not send error details to remote clients and will provide these additional error details to clients on the local machine. Returning to our first example, whereas a local client would see this:

A remote client would only see this:

The difference between Message and MessageDetail above is that MessageDetail contains error information that is WebAPI-specific that remote clients should not have to see in most cases. The exact meaning of error detail depends on the case. For exceptions, error detail includes the exception message, exception type, the stack trace, and the inner exceptions. Only a vague “An error has occurred.” message is sent back to remote clients for exceptions by default. For model states, any model error messages are sent to remote clients. Model error exceptions, however, are considered detail and will not get sent to remote clients by default.

You can choose to override when the error detail gets sent back to clients directly on your HttpConfiguration object:

   1: config.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.LocalOnly;

   2: config.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.Always;

   3: config.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.Never;

As mentioned above, the default is LocalOnly.

Applying Error Handling to Handle Invalid ModelStates

One especially common use of WebAPI’s error handling is to immediately return an error if the model state is invalid. This can be done fairly easily by implementing the following action filter:

   1: public class ValidationFilterAttribute : ActionFilterAttribute

   2: {

   3:     public override void OnActionExecuting(HttpActionContext actionContext)

   4:     {

   5:         if (!actionContext.ModelState.IsValid)

   6:         {

   7:             actionContext.Response = actionContext.Request.CreateErrorResponse(HttpStatusCode.BadRequest, actionContext.ModelState);

   8:         }

   9:     }

  10: }

You can then either mark your action with this attribute, or register the action filer globally like this:

   1: config.Filters.Add(new ValidationFilterAttribute());

This allows you to short-circuit the processing of the request and immediately return an error for the invalid model state back to the client.

As always, you can learn more about ASP.NET WebAPI here: https://www.asp.net/web-api.

Fortunately, this restriction has been lifted in WCF 4.0 with the introduction of ConfigurationChannelFactory. This new class allows you to create clients that can take in any Configuration object to configure your client. This means that you’re no longer limited to using the App.config for your executable. To demonstrate this new class, let’s say you have a client that needs to call out to a web service that returns stock information and another web service that returns weather information.

In WCF 4.0, you can do this:

Configuration stockConfiguration = ConfigurationManager.OpenMappedExeConfiguration(new ExeConfigurationFileMap { ExeConfigFilename = @"C:\Temp\StockClient.config"}, ConfigurationUserLevel.None);

ConfigurationChannelFactory<StockQuoteSoap> stockChannelFactory = new ConfigurationChannelFactory<StockQuoteSoap>("StockQuoteSoap", stockConfiguration, null);

StockQuoteSoap stockClient = stockChannelFactory.CreateChannel();

GetQuoteResponse stockResponse = stockClient.GetQuote(new GetQuoteRequest { Body = new GetQuoteRequestBody { symbol = "MSFT" } });

Console.WriteLine(stockResponse.Body.GetQuoteResult);

stockChannelFactory.Close();

Configuration weatherConfiguration = ConfigurationManager.OpenMappedExeConfiguration(new ExeConfigurationFileMap { ExeConfigFilename = @"C:\Temp\WeatherClient.config" }, ConfigurationUserLevel.None);

ConfigurationChannelFactory<GlobalWeatherSoap> weatherChannelFactory = new ConfigurationChannelFactory<GlobalWeatherSoap>("GlobalWeatherSoap", weatherConfiguration, null);

GlobalWeatherSoap weatherClient = weatherChannelFactory.CreateChannel();

GetWeatherResponse weatherResponse = weatherClient.GetWeather(new GetWeatherRequest { Body = new GetWeatherRequestBody { CityName = "Paris", CountryName = "France" } });

Console.WriteLine(weatherResponse.Body.GetWeatherResult);

weatherChannelFactory.Close();

In this example, two separate client configuration files are located at C:\Temp\StockClient.config and C:\Temp\WeatherClient.config and we’re able to use both in the very same method! For each service, we first load up a configuration object, then pass that configuration object to the constructor for ConfigurationChannelFactory, and finally call the service and print out the results. It's that easy.

Of course, I could go about manually creating XmlSerializer types that match the way the XML looks, but that’s usually unnecessary and always tedious. You could also look into the “Paste XML as Types” feature that’s part of the WCF REST starter kit as a Visual Studio add-in. But if you want to just get the job done from the command line without downloading or installing anything, this blog post is for you. We’ll make use of xsd.exe, which is part of the SDK for the .NET framework.

Suppose we’re starting out with the following snippet of XML:

<Library xmlns:i="https://www.w3.org/2001/XMLSchema-instance">

  <Books>

    <Book Rating="4">

      <Author>

        <FirstName>Kurt</FirstName>

        <LastName>Vonnegut</LastName>

        <MiddleName i:nil="true" />

      </Author>

      <Title>Welcome to the Monkey House</Title>

      <Year>1968</Year>

    </Book>

    <Book Rating="5">

      <Author>

        <FirstName>Orson</FirstName>

        <LastName>Card</LastName>

        <MiddleName>Scott</MiddleName>

      </Author>

      <Title>Ender's Game</Title>

      <Year>1985</Year>

    </Book>

  </Books>

  <Name>Library Of Congress</Name>

</Library>

That we want to turn into XmlSerializer types. First, copy this bit of XML into a file named library.xml and run the following command:

xsd.exe library.xml

This should generate an XSD for the XML we started out with. If you open library.xsd, you’ll find the following schema:

  <xs:element name="Library">

    <xs:complexType>

      <xs:sequence>

        <xs:element name="Name" type="xs:string" minOccurs="0" />

        <xs:element name="Books" minOccurs="0" maxOccurs="unbounded">

          <xs:complexType>

            <xs:sequence>

              <xs:element name="Book" minOccurs="0" maxOccurs="unbounded">

                <xs:complexType>

                  <xs:sequence>

                    <xs:element name="Title" type="xs:string" minOccurs="0" msdata:Ordinal="1" />

                    <xs:element name="Year" type="xs:string" minOccurs="0" msdata:Ordinal="2" />

                    <xs:element name="Author" minOccurs="0" maxOccurs="unbounded">

                      <xs:complexType>

                        <xs:sequence>

                          <xs:element name="FirstName" type="xs:string" minOccurs="0" />

                          <xs:element name="LastName" type="xs:string" minOccurs="0" />

                          <xs:element name="MiddleName" type="xs:string" minOccurs="0" />

                        </xs:sequence>

                      </xs:complexType>

                    </xs:element>

                  </xs:sequence>

                  <xs:attribute name="Rating" type="xs:string" />

                </xs:complexType>

              </xs:element>

            </xs:sequence>

          </xs:complexType>

        </xs:element>

      </xs:sequence>

    </xs:complexType>

  </xs:element>

Which matches our original XML perfectly. Now, we just need to generate types based off the XSD, using xsd.exe again:

xsd.exe /classes library.xsd

This will generate a C# file called library.cs which contains the XmlSerializer types for your XML. And at this point, all you have to do is to compile the classes and to start deserializing instances of XML into your newly generated types or create instances of these types and serialize them out.

A couple notes:

·         The names of the types won’t quite look natural. This happens because all of the types in the XSD are anonymous. I suggest renaming these to suit your needs.

·         You should also get a “NewDataSet” class generated. This is an artifact of the way xsd.exe generates a schema for the XML. You can safely delete the class.

static void RoundTripXmlMetadata(Type type)

{

    XmlSchemas schemas = new XmlSchemas();

    XmlSchemaExporter exporter = new XmlSchemaExporter(schemas);

    //Import the type as an XML mapping

    XmlTypeMapping mapping = new XmlReflectionImporter().ImportTypeMapping(type);

    //Export the XML mapping into schemas

    exporter.ExportTypeMapping(mapping);

    //Print out the schemas

    foreach (object schema in schemas)

    {

        ((XmlSchema)schema).Write(Console.Out);

        Console.WriteLine("\n");

    }

    Console.WriteLine("-------------------------------------------");

    //Compile the schemas into one logical schema

    schemas.Compile((o, args) => Console.WriteLine(args.Message), true);

    XmlSchemaImporter importer = new XmlSchemaImporter(schemas);

    //Import the schema element back into an XML mapping

    mapping = importer.ImportTypeMapping(new XmlQualifiedName(mapping.ElementName, mapping.Namespace));

    //Create a CompileUnit and CodeNamespace to contain the generated code

    CodeCompileUnit compileUnit = new CodeCompileUnit();

    CodeNamespace compileNs = new CodeNamespace();

    compileUnit.Namespaces.Add(compileNs);

    XmlCodeExporter codeGenerator = new XmlCodeExporter(compileNs);

    //Export the XML mapping into code

    codeGenerator.ExportTypeMapping(mapping);

    //Generate C# code for the compile unit and print it out

    CSharpCodeProvider provider = new CSharpCodeProvider();

    provider.GenerateCodeFromCompileUnit(compileUnit, Console.Out, null);

}

I’ve tried to add comments to explain what’s happening. Essentially, we go through the following process when generating the schemas:

CLR type => XML mapping => Xml Schemas

and the following process when generating code:

Xml Schemas => XML mapping => C# code

And when we try running the type Dog defined below

public class Animal

{

    public int age = 4;

    public string name = "Rusty";

}

public class Dog : Animal

{

    public DogBreed breed = DogBreed.LabradorRetriever;

}

public enum DogBreed {

    GermanShepherd,

    LabradorRetriever

}

Through the method, we get the following output:

<?xml version="1.0" encoding="IBM437"?>

<xs:schema elementFormDefault="qualified" xmlns:xs="https://www.w3.org/2001/XMLSc

hema">

  <xs:element name="Dog" nillable="true" type="Dog" />

  <xs:complexType name="Dog">

    <xs:complexContent mixed="false">

      <xs:extension base="Animal">

        <xs:sequence>

          <xs:element minOccurs="1" maxOccurs="1" name="breed" type="DogBreed" />

        </xs:sequence>

      </xs:extension>

    </xs:complexContent>

  </xs:complexType>

  <xs:complexType name="Animal">

    <xs:sequence>

      <xs:element minOccurs="1" maxOccurs="1" name="age" type="xs:int" />

      <xs:element minOccurs="0" maxOccurs="1" name="name" type="xs:string" />

    </xs:sequence>

  </xs:complexType>

  <xs:simpleType name="DogBreed">

    <xs:restriction base="xs:string">

      <xs:enumeration value="GermanShepherd" />

      <xs:enumeration value="LabradorRetriever" />

    </xs:restriction>

  </xs:simpleType>

</xs:schema>

-------------------------------------------

//------------------------------------------------------------------------------

// <auto-generated>

//     This code was generated by a tool.

//     Runtime Version:4.0.30319.1

//

//     Changes to this file may cause incorrect behavior and will be lost if

//     the code is regenerated.

// </auto-generated>

//------------------------------------------------------------------------------

/// <remarks/>

[System.CodeDom.Compiler.GeneratedCodeAttribute("Serialization", "0.0.0.0")]

[System.SerializableAttribute()]

[System.Diagnostics.DebuggerStepThroughAttribute()]

[System.ComponentModel.DesignerCategoryAttribute("code")]

[System.Xml.Serialization.XmlRootAttribute(Namespace="", IsNullable=true)]

public partial class Dog : Animal {

    private DogBreed breedField;

    /// <remarks/>

    public DogBreed breed {

        get {

            return this.breedField;

        }

        set {

            this.breedField = value;

        }

    }

}

/// <remarks/>

[System.CodeDom.Compiler.GeneratedCodeAttribute("Serialization", "0.0.0.0")]

[System.SerializableAttribute()]

public enum DogBreed {

    /// <remarks/>

    GermanShepherd,

    /// <remarks/>

    LabradorRetriever,

}

/// <remarks/>

[System.Xml.Serialization.XmlIncludeAttribute(typeof(Dog))]

[System.CodeDom.Compiler.GeneratedCodeAttribute("Serialization", "0.0.0.0")]

[System.SerializableAttribute()]

[System.Diagnostics.DebuggerStepThroughAttribute()]

[System.ComponentModel.DesignerCategoryAttribute("code")]

public partial class Animal {

    private int ageField;

    private string nameField;

    /// <remarks/>

    public int age {

        get {

            return this.ageField;

        }

        set {

            this.ageField = value;

        }

    }

    /// <remarks/>

    public string name {

        get {

            return this.nameField;

        }

        set {

            this.nameField = value;

        }

    }

}

Notice that the generated types look very similar to the types we started out with. In fact, as far as XmlSerializer is concerned, those types are equivalent. If you create an instance of your original class and an instance of the roundtripped class with the same values, you’ll get exactly the same XML output on the wire. That’s the guarantee that metadata roundtrips provide.

public class Employee

{

    public DateTime BirthDate { get; set; }

}

And you happen to be using XmlSerializer, you may be surprised to find that the schema gets exposed like this:

<xs:schema elementFormDefault="qualified" xmlns:xs="https://www.w3.org/2001/XMLSchema">

  <xs:element name="Employee" nillable="true" type="Employee" />

  <xs:complexType name="Employee">

    <xs:sequence>

      <xs:element minOccurs="1" maxOccurs="1" name="BirthDate" type="xs:dateTime" />

    </xs:sequence>

  </xs:complexType>

</xs:schema>

Here’s how to do it:

public class Employee

{

    public DateTime BirthDate { get; set; }

    [XmlIgnore]

    public bool BirthDateSpecified { get; set; }

}

The BirthDateSpecified property tells XmlSerializer whether the BirthDate is specified or not. If you exported the schema for this type, you’d get:

<xs:schema elementFormDefault="qualified" xmlns:xs="https://www.w3.org/2001/XMLSchema">

  <xs:element name="Employee" nillable="true" type="Employee" />

  <xs:complexType name="Employee">

    <xs:sequence>

      <xs:element minOccurs="0" maxOccurs="1" name="BirthDate" type="xs:dateTime" />

    </xs:sequence>

  </xs:complexType>

</xs:schema>

So you essentially create a public field or property with a Boolean type and the name of the struct member plus the string “Specified”. You should also mark it as [XmlIgnore] to make sure that this new member doesn’t get serialized out. The Boolean member then tells the serializer whether the struct member is specified or not. If the Boolean member is false, then XmlSerializer will not serialize out the struct member. So, for example, if you tried serializing this object:

o = new Employee() { BirthDate = new DateTime(1986, 11, 1), BirthDateSpecified = false };

BirthDate would not get serialized out, even though you’ve assigned it a value. A helpful tip in this kind of situation is to have BirthDateSpecified’s getter check BirthDate’s value. This way you can avoid serializing out BirthDate only if it corresponds to a certain default value. Or use Nullable<T> in this kind of pattern:

public class Employee

{

    public DateTime? BirthDate { get; set; }

    [XmlIgnore]

    public bool BirthDateSpecified { get { return BirthDate != null; } }

}