Youssef M's Blog

Paging with ASP.NET Web API OData

2013-02-19T21:38:56Z

A common requirement for web applications is to expose partial results from a larger set of data. Maybe you want your users to be able to browse through a collection of movies that they can stream. But you don't want to display all of the thousands of movie titles you have available, just the first twenty titles in the category the user is browsing through. This avoids overloading your users with information and avoids the significant performance and bandwidth costs associated with sending large chunks of data.

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:

http://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:

http://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:

http://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:

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

Here's what the response body might look like:

   1: {

   2:   "odata.metadata":"http://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":"http://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:

http://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":"http://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":"http://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);

In this case, we’d compute that since there are 799 comedies in our database and since we’re displaying 20 comedies per page, we’ll have 40 pages.

Note that server-driven paging only works by default with the OData format. Marking a Queryable action with the PageSize attribute will still limit the results for vanilla XML and JSON formatters, but it won’t add a next page link or a count. It’s possible to use the PageResult<T> class to add that information for other formats as well. You can even implement an action filter that converts a response into a PageResult to automatically enable similar functionality in other formatters. Look out for a future blog post detailing how to do that.

For more information about server-driven paging, take a look at this sample. It demonstrates implementing server-driven paging for a collection of movies with Web API’s OData support. If you’re new to writing OData services with Web API, I’ve posted a getting started guide over on the webdev blog to help get you up and running.

Writing tests for an ASP.NET Web API service

2013-01-28T23:17:00Z

It's important to test any service you write to make sure that it's behaving the way you expect it to. In this blog post, I'll go through the main ways of testing a Web API service, exploring the benefits and drawbacks of each option so that you can test your service effectively.

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, "http://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("http://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, "http://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.

Building Real-time Web Apps with ASP.NET WebAPI and WebSockets

2012-07-18T01:12:49Z

WebSocket is a recent technology that provides two-way communication over a TCP connection. This allows us to create real-time web apps where servers can push data to clients. In this blog post, I’ll demonstrate how this can be done by building a simple chat app using ASP.NET WebAPI and ASP.NET’s new support for WebSockets in .NET 4.5.

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" />

The HTML here is just a simple chat field to enter messages and a <div> to display our broadcast messages at. Next, let’s implement our client-side WebSocket functionality:

   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.

Error Handling in ASP.NET WebAPI

2012-06-28T20:38:28Z

WebAPI is a brand new framework that makes it easy to build HTTP services. As such, it provides several features that make it easy to send back useful and informative error messages in a variety of cases. In this post, I’ll go over some of these capabilities.

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: http://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 'http://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 'http://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:

It allows you to return a specific HTTP response from actions with return types that aren’t HttpResponseMessage.
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:

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

A remote client would only see this:

{
"Message": "No HTTP resource was found that matches the request URI 'http://localhost/Foo'."
}

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: http://www.asp.net/web-api.

Writing a Lightweight Web Service using WebApi Building Blocks

2012-02-25T02:21:00Z

Don’t you wish you could write a web service this easily:

LiteWebServer server = new LiteWebServer("http://localhost");

server.Get("/Hello", (r) => new HttpResponseMessage() { Content = new StringContent("Hello World!") });

server.Post("/Echo", (r) => new HttpResponseMessage() { Content = new StringContent(r.Content.ReadAsStringAsync().Result) });

server.Open();

Well, with last week’s release of the Web API beta bits, now you can. Web API is a brand new framework that makes it easy to build HTTP services. You can learn more about Web API here: http://www.asp.net/web-api.

One of the goals when designing the framework was to completely decouple how messages were received from how they were being dispatched. This allows you to plug in your own custom dispatching for requests very easily. In this post, I’ll show you how you can leverage this extensibility to have messages dispatched to your own lambda callbacks.

The key thing we’ll be using is an HttpMessageHandler. HttpMessageHandlers have the following contract:

    // Summary:

    //     A base type for HTTP message handlers.

    public abstract class HttpMessageHandler : IDisposable

//

        // Summary:

        //     Send an HTTP request as an asynchronous operation.

//

        // Parameters:

        //   request:

        //     The HTTP request message to send.

//

        //   cancellationToken:

        //     The cancellation token to cancel operation.

//

        // Returns:

        //     Returns System.Threading.Tasks.Task<TResult>.The task object representing

        //     the asynchronous operation.

        protected internal abstract Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken);

SendAsync here allows you to asynchronously handle a request, and return a Task that may eventually complete with a response. Now all we need is something to actually call our message handlers. In Web API, these are called HttpServers. They’re in charge of listening for requests and pumping them through the HttpMessageHandler when they receive them. Notice how LiteWebServer below delegates to its inner HttpSelfHostServer.

public delegate HttpResponseMessage LiteMessageHandler(HttpRequestMessage request);

public class LiteWebServer

    HttpSelfHostServer server;

    HttpSelfHostConfiguration configuration;

    LiteWebMessageHandler messageHandler = new LiteWebMessageHandler();

    public LiteWebServer(string baseAddress)

        configuration = new HttpSelfHostConfiguration(baseAddress);

        server = new HttpSelfHostServer(configuration, messageHandler);

    public void Get(string subPath, LiteMessageHandler handler)

        RegisterHandler(HttpMethod.Get, subPath, handler);

    public void Put(string subPath, LiteMessageHandler handler)

        RegisterHandler(HttpMethod.Put, subPath, handler);

    public void Post(string subPath, LiteMessageHandler handler)

        RegisterHandler(HttpMethod.Post, subPath, handler);

    public void Delete(string subPath, LiteMessageHandler handler)

        RegisterHandler(HttpMethod.Delete, subPath, handler);

    private void RegisterHandler(HttpMethod method, string subPath, LiteMessageHandler handler)

        messageHandler.Handlers[method].Add(new Uri(configuration.BaseAddress, subPath).ToString(), handler);

    public void Open()

        server.OpenAsync().Wait();

    public void Close()

        server.CloseAsync().Wait();

    private class LiteWebMessageHandler : HttpMessageHandler

        public Dictionary<HttpMethod, RoutingMap> Handlers = new Dictionary<HttpMethod, RoutingMap>()

            { HttpMethod.Delete, new RoutingMap() },

            { HttpMethod.Get, new RoutingMap() },

            { HttpMethod.Head, new RoutingMap() },

            { HttpMethod.Options, new RoutingMap() },

            { HttpMethod.Post, new RoutingMap() },

            { HttpMethod.Put, new RoutingMap() },

            { HttpMethod.Trace, new RoutingMap() }

};

        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)

            LiteMessageHandler handler;

            RoutingMap routingMap = Handlers[request.Method];

            HttpResponseMessage response = routingMap.TryGetValue(request.RequestUri.AbsoluteUri, out handler) ?

                handler(request) :

                new HttpResponseMessage(HttpStatusCode.NotFound);

            return FromResult(response);

        private static Task<T> FromResult<T>(T t)

            TaskCompletionSource<T> tcs = new TaskCompletionSource<T>();

            tcs.SetResult(t);

            return tcs.Task;

    private class RoutingMap : Dictionary<string, LiteMessageHandler>

And that lets us write our web service in just a few lines of code:

// Set up server

LiteWebServer server = new LiteWebServer("http://localhost");

server.Get("/Hello", (r) => new HttpResponseMessage() { Content = new StringContent("Hello World!") });

server.Post("/Echo", (r) => new HttpResponseMessage() { Content = new StringContent(r.Content.ReadAsStringAsync().Result) });

server.Open();

// Client call - Hello World

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, "http://localhost/Hello");

HttpResponseMessage response = new HttpClient().SendAsync(request).Result;

Console.WriteLine(response);

Console.WriteLine(response.Content.ReadAsStringAsync().Result);

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

// Client call - Echo

request = new HttpRequestMessage(HttpMethod.Post, "http://localhost/Echo") { Content = new StringContent("This is pretty neat!") };

response = new HttpClient().SendAsync(request).Result;

Console.WriteLine(response);

Console.WriteLine(response.Content.ReadAsStringAsync().Result);

server.Close();

There are plenty more things you can do with Web API. I’ll be repurposing this blog to discuss more about how Web API works and how it can help you write HTTP services.

In the meantime, I encourage you to download the bits today!

Using the [ContractNamespace] attribute to customize the namespace for POCO types

2011-06-30T19:21:00Z

In .NET 3.5 SP1, DataContractSerializer was enhanced to support POCO types that weren’t marked with any serialization attributes at all. You can find my previous post about serializing POCO types here. But in some cases, you may want to customize the XML namespace of your POCO types without necessarily having to fall back to the [DataContract]/[DataMember] model. The way to do this is by using an assembly-level attribute called [ContractNamespace]. This attribute allows you to either set an XML namespace for DataContractSerializer for all the types in your assembly, or to set an XML namespace for specific CLR namespaces within your assembly.

So for example, the following POCO type:

namespace MyNs
{
    public class POCO
    {
        public string Data { get; set; }
    }
}

Would traditionally get serialized with a default XML namespace:

</POCO>

But if you happen to have the assembly level attribute:

[assembly:ContractNamespace("http://myXmlNamespace")]

Or:

[assembly:ContractNamespace("http://myXmlNamespace", ClrNamespace="MyNs")]

, then "http://myXmlNamespace" will be used for the POCO type’s serialization:

</POCO>

So the ContractNamespaceAttribute allows you to either choose a default XML namespace for the entire assembly, or map the types in a specific CLR namespace to the XML namespace of your choosing.

Note that ContractNamespaceAttribute applies not only to POCO types, but to all other serializable types as well. So,

namespace MyNs
{
    [DataContract
    public class POCO
    {
        [DataMember]
        public string Data { get; set; }
    }
}

Would also be serialized as:

</POCO>

If the [ContractNamespace] attribute were present. However, DataContracts can override the ContractNamespace default by setting their own namespace on the type itself. So,

namespace MyNs
{
    [DataContract(Namespace="http://POCONamespace")]
    public class POCO
    {
        [DataMember]
        public string Data { get; set; }
    }
}

Would get serialized as:

Regardless of any [ContractNamespace] attributes.

Loading WCF Client Configuration from Different Files with ConfigurationChannelFactory

2010-09-02T23:59:00Z

One pain point with configuration that WCF developers have run into in previous versions of the framework is the limitation that WCF clients can only use the hosting executable’s configuration file. This can be problematic for clients that need to call multiple services because the configuration for all of these services would have to be mashed together in one big configuration file. This can also be a problem for client libraries: since libraries don’t have configuration files, every executable that uses the library needs to provide it with the right configuration in its own configuration file.

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.

Turning XML into XmlSerializer CLR Types with xsd.exe

2010-06-01T22:22:00Z

Here’s a common dilemma .NET developers encounter when working with XML: I have some XML that I want to represent in a strongly typed way, but I don’t have any XSDs to represent that XML. How do I turn that XML into CLR types that I can serialize?

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:

<Books>

<LastName>Vonnegut</LastName>

</Author>

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

</Book>

<FirstName>Orson</FirstName>

<MiddleName>Scott</MiddleName>

</Author>

<Title>Ender's Game</Title>

</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.

Using XML Schema Import and Export for XmlSerializer

2010-05-13T20:51:00Z

In a previous post, I outlined how you could import and export the XML schema for a type that you’re serializing with DataContractSerializer. Here’s how to do the same thing if you’re serializing objects with XmlSerializer:

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="http://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.

How to get minOccurs = 0 in the schema for XmlSerializer struct members

2010-03-22T23:52:00Z

If you try exporting the following type into an XML schema:

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="http://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>

Notice that minOccurs gets set to 1. This means that every Employee should have a BirthDate. The reason XmlSerializer does this is because structs cannot be set to null. They must have a value. So XmlSerializer tries to represent this by always setting minOccurs to 1 by default. This prevents miscommunication if the serializer and deserializer have different defaults for a certain type. For example, DateTime’s default constructor set its value to January 1st, Year 1. If a different stack used the Year 2000 as the default value for DateTimes, how would XmlSerializer know how to interpret the value of an Employee that doesn’t have a BirthDate? The serializer would think it was sending a DateTime for Year 2000, and the deserializer would think it was reading a DateTime for Year 1. And XmlSerializer can’t set DateTime to null to indicate that it wasn’t specified. With that said, you may want to force XmlSerializer to emit minOccurs = 0 if you know for a fact that the serializer and deserializer have the same defaults for that type.

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="http://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; } }

}

How to Change .NET Configuration Files at Runtime (including for WCF)

2010-01-22T01:05:00Z

One of the most common issues people run into with WCF configuration, and .NET applications in general, is that configuration files appear to be fixed. You only have one configuration file for an executable, and you can’t use different configuration files as your exe.config while the application is running. Of course, you can always shut down the application, change the configuration, and then restart it with the new configuration file, but that’s tedious and oftentimes undesirable. In this blog post, I’ll show you how to easily get around this limitation.

Suppose you have the following simple configuration file:

</appSettings>

</configuration>

And let’s say you have the following code:

public static void Main()

{

Console.WriteLine(ConfigurationManager.AppSettings["name"]);

ChangeConfiguration();

Console.WriteLine(ConfigurationManager.AppSettings["name"]);

}

static void ChangeConfiguration()

{

Configuration config = ConfigurationManager.OpenExeConfiguration(Assembly.GetEntryAssembly().Location);

AppSettingsSection appSettings = (AppSettingsSection)config.GetSection("appSettings");

appSettings.Settings.Clear();

appSettings.Settings.Add("name", "bar");

config.Save();

}

The ChangeConfiguration method above opens up the configuration for the currently running executable, clears the appSettings dictionary, and then adds a new entry with value “bar” instead of “foo”. The main method simply checks the value of name before and after changing the configuration. If you run this code as is you’ll get the following output:

foo

So even though you changed the configuration file, you’re not picking up on the appSetting’s new value. This is because the AppSettings section was cached when you first asked for it, and subsequent calls just use the cached version instead of reading from disk.

But now, if you add the following line of code to your Main method:

public static void Main()

{

Console.WriteLine(ConfigurationManager.AppSettings["name"]);

ChangeConfiguration();

ConfigurationManager.RefreshSection("appSettings");

Console.WriteLine(ConfigurationManager.AppSettings["name"]);

}

Making sure to revert the configuration file to its original value “foo”, you get the following output:

foo

bar

So by calling RefreshSection, you’re telling the configuration API that it should invalidate the cached AppSettings section and instead read from disk on the next configuration call.

This is very useful in particular for WCF because it allows you to use different configuration files for different services or clients, and then just have the same application use all of those configuration files. In this way, you avoid having large configuration files that merge together the information for very many services or clients. Unfortunately, you can’t RefreshSection on a section group, only a section, so you’ll typically have to use the following calls to refresh WCF sections:

ConfigurationManager.RefreshSection("system.serviceModel/behaviors");

ConfigurationManager.RefreshSection("system.serviceModel/bindings");

ConfigurationManager.RefreshSection("system.serviceModel/client");

ConfigurationManager.RefreshSection("system.serviceModel/services");

You may have to refresh other sections as well if you’re using some of the more advanced configuration sections.

Also worth noting: you don’t have to use Configuration.Save() to edit a configuration file, like I did above. You can change the file in any way you’d like, including changing the config file manually or using File.Copy().

Behavior Merge in WCF 4.0 Configuration

2009-12-22T22:32:00Z

One of the brand new configuration features you can find in the Beta 2 release of .NET 4.0 is the ability to merge behaviors in the configuration hierarchy. This should make it easier to manage behaviors when you want a set of common behaviors to be used consistently. To illustrate how this works, let’s say you have the following virtual directory layout hosted in IIS:

~\Web.config

~\Service.svc

~\Child\Web.config

~\Child\Service.svc

And let’s say your ~\Web.config looks like this:

<system.serviceModel>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

And that your child Web.config at ~\Child\Web.config looks like this:

<system.serviceModel>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

Then, the service at ~\Child\Service.svc will behave as though it had both the serviceDebug and the serviceMetadata behaviors. The service at ~\Service.svc will only have the serviceDebug behavior though. What has happened is that the two behavior collections with the same name (in this case the empty string) have had their behavior elements merged.

Apart from adding behaviors to a behavior collection, you can also clear behavior collections by using the <clear> tag, and remove individual behaviors from the collection by using the <remove> tag. So both of these ~\Child\Web.config files:

<system.serviceModel>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

And

<system.serviceModel>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

Would result in the child service having only the serviceMetadata behavior, and not the serviceDebug behavior.

A few notes:

· This works not only for nameless behavior collections as shown above, but also for named behavior collections. So if you had:

At both the root Web.config and the child Web.config, the child service would have the behaviors merged for both of the behavior collections named “Foo”.

· Behavior merge works in the IIS hosting environment, in which Web.config files merge hierarchically with the root Web.config file and machine.config. But it also works in the application environment, where machine.config can merge with the App.config file.

· Behavior merge applies to both endpoint behaviors and service behaviors in configuration.

· If a child behavior collection contains a behavior that’s already present in the parent behavior collection, the child behavior overrides the parent one. So if a parent behavior collection had <serviceMetadata httpGetEnabled="False" /> and a child behavior collection had <serviceMetadata httpGetEnabled="True" />, the child behavior would override the parent behavior in the behavior collection and httpGetEnabled would be “true”.

Separating out WCF Configuration Into Multiple Files with configSource

2009-11-04T01:36:00Z

WCF configuration files can sometimes be very, very long. And there’s a good reason for that too: WCF makes heavy use of configuration so that you can do just about anything you can do with code in a config file. I recently decided to estimate how much of the entire framework’s configuration belongs to WCF by looking at what percentage of the framework’s schema is under system.serviceModel, system.runtime.serialization, and system.serviceModel.activation. It turns out those section groups alone account for more than 70% of the entire framework’s configuration schema.

So even more so than for other section groups, it’s useful to be able to break up a long WCF configuration file into smaller, more manageable files. You can do this using the “configSource” attribute. It allows you to reference another file that contains the configuration section you declared.

So instead of having the following in your App.config:

<system.serviceModel>

</service>

</services>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

You could have the following in your App.config:

<system.serviceModel>

</service>

</services>

</system.serviceModel>

</configuration>

And this in behaviors.config:

</behavior>

</serviceBehaviors>

</behaviors>

If you wanted you could separate out your entire system.serviceModel section group into smaller files:

<system.serviceModel>

</system.serviceModel>

</configuration>

Note, however, that you can only use this for sections. This technique can’t be used for the system.serviceModel section group or for any config elements. Also note that the referenced files should contain only one section, and that you won’t need a <configuration> or <system.serviceModel> tag in them, just the section being referenced.

WCF 101: The Simplest WCF Example You'll Ever See

2009-11-02T23:36:00Z

Every once in a while, I’ll encounter a developer that thinks that WCF is too complicated to use. Whereas in fact, the basics of WCF are incredibly simple. MSDN’s tutorial hides this fact by making their introduction to WCF a fairly long and painful 6-step process, but you need much less to write your first WCF application. In fact, you don’t need Visual Studio and you don’t even need svcutil. All you need is notepad, and an install of .NET 3.0.

I have three steps for you:

1. Copy the following code into a file called “WCF.cs” using your text editor of choice:

using System;

using System.ServiceModel;

class Program

{

static void Main()

{

ServiceHost host = new ServiceHost(typeof(Echo));

host.AddServiceEndpoint(typeof(IEcho), new BasicHttpBinding(), "http://localhost/Service");

host.Open();

ChannelFactory<IEcho> client = new ChannelFactory<IEcho>(new BasicHttpBinding(), "http://localhost/Service");

Console.WriteLine(client.CreateChannel().Echo("hello"));

}

[ServiceContract]

interface IEcho

{

[OperationContract]

string Echo(string s);

}

class Echo : IEcho

{

string IEcho.Echo(string s) { return s + " echoooOOooo"; }

}

2. Compile the code by running the C# compiler csc.exe against your new WCF.cs file. You can usually just run this in a command prompt:

C:\Windows\Microsoft.NET\Framework\v2.0.50727\csc.exe WCF.cs

3. Still in the command prompt, run WCF.exe. You should get the output:

hello echoooOOooo

indicating that you started a service, created a client, and made a call to your service’s “Echo” method.

Voila! That’s all you need to use WCF. Not too bad, right?

Beta 2's out!

2009-11-02T21:26:00Z

Ok, so a bit late, but the Beta 2 release of Visual Studio 2010 was released two weeks ago. With Beta 2 come a number of changes to the DataContractResolver, so I’ve finally found the time to update my previous post. For those that have read the post during Beta 1, ResolveType has become TryResolveType and returns a bool indicating whether the resolution was handled or not, both resolution methods now take a declared type parameter, and you can return true from TryResolveType and set typeName and typeNamespace to null to indicate that you do not want any xsi:type written out on the wire, enabling you to serialize a type as the declared type.

Also new with Beta 2, I’m in love with the new Lightweight Beta view for MSDN documentation. Try this out: http://msdn.microsoft.com/en-us/library/system(lightweight).aspx. It loads much faster, it’s cleaner, and it still lets you filter out the language you want (unlike the ScriptFree view).

I’ll be adding more posts about the other new WCF-related features in Beta 2, so stay tuned.

Reusing Types in Referenced Assemblies with svcutil's /r Switch

2009-10-09T22:37:00Z

Everyone’s entitled to their own personal favorite svcutil switch, but mine is the “/reference” switch, or “/r” for short. It allows you to avoid generating a type again if it’s already present in a referenced assembly. Here’s how it works:

Let’s say you have an assembly Foo.dll that already contains a type Foo:

[DataContract(Name="Blah", Namespace="http://www.myNamespace.org/")]

public class Foo

{

[DataMember(Name="theSMember")]

public string s;

}

Now, if you run “svcutil /reference:Foo.dll http://www.awesomeServices.com/FooService?wsdl” , and if FooService happens to reference a type that matches Foo’s data contract in its metadata, like here:

<xs:schema xmlns:tns="http://www.myNamespace.org/" elementFormDefault="qualified" targetNamespace="http://www.myNamespace.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:complexType name="Blah">

<xs:sequence>

<xs:element minOccurs="0" name="theSMember" nillable="true" type="xs:string" />

</xs:sequence>

</xs:complexType>

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

</xs:schema>

Instead of generating a client-side class definition for this type that you might expect:

[System.Diagnostics.DebuggerStepThroughAttribute()]

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

[System.Runtime.Serialization.DataContractAttribute(Name="Blah", Namespace="http://www.myNamespace.org/")]

public partial class Blah : object, System.Runtime.Serialization.IExtensibleDataObject {

private System.Runtime.Serialization.ExtensionDataObject extensionDataField;

private string theSMemberField;

public System.Runtime.Serialization.ExtensionDataObject ExtensionData {

get {

return this.extensionDataField;

}

set {

this.extensionDataField = value;

}

[System.Runtime.Serialization.DataMemberAttribute()]

public string theSMember {

get {

return this.theSMemberField;

}

set {

this.theSMemberField = value;

}

Svcutil will just reference the type Foo from the assembly that you provided. So you’re able to avoid having ugly-looking generated data types on your client when you already have access to those types.

This can be useful in a number of cases:

· Your client and server share an assembly of common types, so that the very same types can be used on the server and on the client.

· You need to import metadata for two different services that happen to share the same type and don’t want to get two copies of the same type. In this case, you can generate proxy for the first service, compile it, and then reference the assembly when generating proxy for the second service.

· You already have client-side types that are similar to the types that are being imported and you want WCF to use these types directly instead of having to copy over data from the auto-generated class into your own type or vice versa

I should note that by default, Visual Studio’s “Add Service Reference” will use all of the referenced assemblies in your project as references for proxy generation purposes as well. Also, mscorlib and System.ServiceModel are always considered referenced assemblies unless you use the flag “noStdLib”. Finally, the /r switch only works for DataContract types. It does not work for XmlSerializer types. So if your types can't be imported as data contracts, /r won't do anything for you.

Serializing Plain Old CLR Object (POCO) types with DataContractSerializer

2009-08-10T22:24:00Z

When version 3.0 of the .NET framework shipped, DataContractSerializer could only support a few categories of CLR types. Sowmy has a good list of these that you can find here. The recommended model was to use DataContractAttributes on classes and structs along with DataMemberAttributes on fields and properties to customize the serialization of types. I really like that model because it forces users to think about the data they’re passing on the wire. However, adding attributes to every class and every member can be very tedious. It also meant that types that could be serialized by XmlSerializer couldn’t be serialized at all by DataContractSerializer.

To remedy the issue, POCO serialization was introduced in .NET 3.5 SP1. What this means is that you can still serialize custom types without attributes with DataContractSerializer provided the type is public and has a parameterless constructor. Remember though that the C# compiler provides you with a default parameterless constructor if you don’t specify one, so you may not need to explicitly write a constructor for a class to make it POCO-serializable. The visibility of the parameterless constructor doesn't matter so it can be public/internal/private, just as long as there is one. If this rule sounds familiar, it’s because that’s exactly how XmlSerializer works.

So whereas the type:

public class POCOBook

{

public string Title { get; set; }

public int Year { get; set; }

}

Couldn’t be serialized out in 3.0, it can be serialized with DataContractSerializer in 3.5 SP1. However, if you removed the default constructor the C# compiler gives you by adding another constructor:

public class POCOBook

{

public POCOBook(string s) { }

public string Title { get; set; }

public int Year { get; set; }

}

Then you get the familiar exception string:

Type 'POCOBook' cannot be serialized. Consider marking it with the DataContractAttribute attribute, and marking all of its members you want serialized with theDataMemberAttribute attribute. See the Microsoft .NETFramework documentation for other supported types.

When you try serializing it out. You would also get the same exception if you made the POCOBook class internal. So how does the serializer decide which members to serialize out? Well again, this works just like XmlSerializer. All public fields and properties will be serialized out. POCOBook on the wire looks like this:

<Title>Ender's Game</Title>

</POCOBook>

Notice how both Title and Year were serialized out. It’s also possible to slightly tweak this by using the IgnoreDataMemberAttribute to opt out a particular member from being serialized. Rewriting POCOBook to look like this:

public class POCOBook

{

public string Title { get; set; }

[IgnoreDataMember]

public int Year { get; set; }

}

Would mean that only Title would be serialized out.

There are a couple important notes that need to be made about POCO serialization:

POCO serialization will only kick in as a last resort for the serializer. So if a type is marked with DataContractAttribute or CollectionDataContractAttribute, it will be serialized according to data contract rules. If the type is marked with SerializableAttribute, it will be serialized as a serializable type. If the type implements IXmlSerializable or ISerializable, those custom serialization implementations will be used instead. And if the type is a collection, instances will be serialized as collections according to these rules.

Also, one significant feature of POCO serialization is that the parameterless constructor is called when you deserialize an instance of the type. This is not the case for DataContract types or Serializable types. It is the case though for IXmlSerializable types, and ISerializable types do call the special (SerializationInfo information, StreamingContext context) constructor.

Optimizing Away Repeat XML Namespace Declarations with DataContractSerializer

2009-07-24T23:51:00Z

For performance reasons, DataContractSerializer can’t always figure out what namespaces will be used in a serialized instance ahead of time. And so, you may sometimes end up having a certain XML namespace defined over and over again when it only has to be declared once. This can be particularly painful because XML namespaces tend to be very long. In the worst cases, namespace declarations can end up representing a majority of the serialized instance and significantly hinder your performance. So here’s a way to make sure that doesn’t happen to you, although it does take a little bit of tinkering.

Suppose you have the following DataContracts:

[DataContract(Namespace="http://www.some-reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaally-long-namespace.com/")]

public class A

{

[DataMember]

public B B;

public A() {

B = new B();

}

[DataContract(Namespace = "http://www.some-other-reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaally-long-namespace.com/")]

public class B

{

[DataMember]

public string s = "foo";

}

If you try serializing an array of five A’s like this:

var o = new A[5];

for (int i = 0; i < 5; i++)

{

o[i] = new A();

}

var ser = new DataContractSerializer(o.GetType());

var writer = new XmlTextWriter(Console.Out) { Formatting = Formatting.Indented };

ser.WriteObject(writer, o);

you’ll get the following XML:

<ArrayOfProgram.A xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.some-reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaally-long-namespace.com/">

<Program.A>

<d3p1:s>foo</d3p1:s>

</Program.A>

<Program.A>

<d3p1:s>foo</d3p1:s>

</Program.A>

<Program.A>

<d3p1:s>foo</d3p1:s>

</Program.A>

<Program.A>

<d3p1:s>foo</d3p1:s>

</Program.A>

<Program.A>

<d3p1:s>foo</d3p1:s>

</Program.A>

</ArrayOfProgram.A>

Notice how the highlighted namespace was defined five times, creating a lot of bloat when it could just be defined once at the top-level. To fix this issue, you can use the following code:

ser.WriteStartObject(writer, o);

writer.WriteAttributeString("xmlns", "p", null, "http://www.some-other-reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaally-long-namespace.com/");

ser.WriteObjectContent(writer, o);

ser.WriteEndObject(writer);

instead of

ser.WriteObject(writer, o);

We first write the start of the object, then register the long namespace with the prefix “p” at the top level, write the object itself, and finally the end of the object. This results in a much more compact XML on the wire that’s equivalent to the XML we generated earlier:

<ArrayOfProgram.A xmlns:p="http://www.some-other-reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaally-long-namespace.com/" xmlns:i="http://www.w3.org/2001/XMLSchema-

instance" xmlns="http://www.some-reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaally-long-namespace.com/">

<Program.A>

<p:s>foo</p:s>

</Program.A>

<Program.A>

<p:s>foo</p:s>

</Program.A>

<Program.A>

<p:s>foo</p:s>

</Program.A>

<Program.A>

<p:s>foo</p:s>

</Program.A>

<Program.A>

<p:s>foo</p:s>

</Program.A>

</ArrayOfProgram.A>

All of the repeat namespace declarations are gone, in favor of just one namespace definition at the top. Of course, it’s also possible to integrate this type of serialization into WCF. Just create a serializer that inherits from XmlObjectSerializer that uses a DataContractSerializer for all of its methods, except for the fact that it registers additional namespaces at the top level. Then create a behavior that derives from DataContractSerializerOperationBehavior with a CreateSerializer method that returns the XmlObjectSerializer you just created and plug in the behavior.

Oh, and if you get a chance, take a look at the trailer for the Office 2010 movie everyone's so excited about.

Comparing the Performance of .NET Serializers

2009-07-10T22:14:00Z

The .NET framework comes with a variety of different serializers. Hopefully, my overview of these serializers will have provided some insight into the differences between them and the various advantages and disadvantages of using different serializers. But there are not only great differences in functionality between the serializers, but there are also vast differences in performance. This is an attempt to provide a rough idea of how serializers stack up against each other as far as performance (speed) is concerned and as far as the size of the serialized instances.

Disclaimer

Serialization performance can vary a lot between different machines, and depends heavily on the object being serialized, the serializer features being used, and the stream or writer to which the serialized instance is being written to. This is only meant to give you a glimpse into how fast or slow serializers might be. If you’re concerned with serialization performance in your scenarios, the best thing you can do is run your own performance tests with the types and functionality you care about.

Setup

I decided to serialize out and deserialize the following object:

object o = new Library()

{

Name = "Library Of Congress",

Books = new List<Book>() { new Book() { Author = new Person(){ FirstName = "Barack", LastName = "Obama"}, Title = "Dreams from My Father: A Story of Race and Inheritance", Year = 1995},

new Book() { Author = new Person(){ FirstName = "Lewis", LastName = "Caroll"}, Title = "Alice's Adventures in Wonderland", Year = 1865},

new Book() { Author = new Person(){ FirstName = "Kurt", LastName = "Vonnegut"}, Title = "Welcome to the Monkey House", Year = 1968},

new Book() { Author = new Person(){ FirstName = "Orson", MiddleName = "Scott", LastName = "Card"}, Title = "Ender's Game", Year = 1985}}

};

Using each of the serializers. This object contains lists, strings, ints, and several classes. It is meant to represent a “typical” object. I used a MemoryStream to write to and read from for all five serializers, and then used XmlDictionaryWriter/Reader.CreateBinaryWriter/Reader to create binary writers for testing the Binary XML performance for DataContractSerializer, NetDataContractSerializer, and XmlSerializer. All of these serializers were used without any particular switches, and no customizations were made to the format of the serialized string. Only parameterless DataContract, DataMember, and Serializable attributes were added. Serialization and deserialization throughputs were measured directly, while roundtrip throughput was calculated using the formula: roundtrip throughput = 1/((1/serialization throughput) + (1/deserialization throughput)).

Results

There are several things we can infer from the data:

· The serializers seem to perform in roughly the following order: DataContractSerializer, XmlSerializer, DataContractJsonSerializer, NetDataContractSerializer, BinaryFormatter

· Using binary XML writers and readers seems to improve speed by ~5-40% and decreases message size by ~30-50% depending on the serializer

· DataContractJsonSerializer produces the smallest serialized instances, followed by DataContractSerializer, BinaryFormatter, XmlSerializer, and NetDataContractSerializer

Overall, DataContractSerializer comes out as the winner of this perf-off with the fastest speed and the second smallest serialized instance size.

Setting Configuration Defaults with Nameless Elements in WCF 4

2009-06-27T00:58:00Z

This is my second post about Beta 1 features in WCF 4.0 after introducing the DataContractResolver.

Beta 1 introduces a new way of using WCF configuration. It’s now possible to specify a default for bindings, service behaviors, endpoint behaviors, and standard endpoints.

Here’s a concrete example to illustrate my point. Suppose you have the following configuration:

<system.serviceModel>

</service>

</service>

</services>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

Notice how you have two services referencing the same service behavior. Well, this is now equivalent to the following:

<system.serviceModel>

</service>

</service>

</services>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

Both services got the serviceMetadata behavior, even though neither one specified a behavior Configuration. Services that do not specify a behaviorConfiguration now receive the behavior element that is specified without a name. In these cases, not having a name specified or not having a behaviorConfiguration specified is semantically equivalent to having both assigned to the empty string. So again, both of the configurations listed above are equivalent to:

<system.serviceModel>

</service>

</service>

</services>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

This works in pretty much the same way for bindings, endpoint behaviors, and standard endpoints as well. So,

<system.serviceModel>

...

</basicHttpBinding>

</bindings>

</system.serviceModel>

</configuration>

Would mean that any endpoint that is specified with binding="basicHttpBinding" bindingConfiguration="" or just binding="basicHttpBinding" would get a maxReceivedMessageSize of 16 MB by default.

Note that defaults entirely stop applying if you specify your behaviorConfiguration, bindingConfiguration, or endpointConfiguration as being anything other than the empty string. It is possible, however, to inherit defaults from a configuration that is higher up in the configuration hierarchy. So a default set at the machine.config level would apply to all relevant, unspecified configuration elements on that machine.

While this may seem like a minor feature, it significantly increases the potential of another new configuration feature in WCF 4.0: services configured without a <service> tag. I’ll discuss that in more depth in a future post.

Customizing the XML for collections with XmlSerializer and DataContractSerializer

2009-06-13T02:19:00Z

One of the most common requests I get about serialization is to explain how to get collections to serialize out one way or another to XML. Specifically, developers are interested in being able to manipulate the hierarchy level of the collection within their XML and the names of the various XML elements. In today’s post, I’ll go over how to do these things with these two XML serializers.

First, let’s define a simple collection type:

public class Library

{

public string Librarian { get; set; }

public List<Book> Books { get; set; }

}

public class Book

{

public string Title { get; set; }

}

Now, by default, you should be able to serialize this type out with XmlSerializer and DataContractSerializer to get XML that looks something like this:

<Books>

<Book>

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

</Book>

<Book>

<Title>American Gods</Title>

</Book>

<Book>

<Title>Bel Canto</Title>

</Book>

</Books>

<Librarian>Kelly</Librarian>

</Library>

Notice that you have two levels of hierarchy to represent the List<Book> collection. You have the <Books> tag and then you have a <Book> tag for every book in the collection.

Changing the level of hierarchy

In some cases though, you may not want the extra <Books> tag. To eliminate the tag with XmlSerializer, simply update the Books member with an XmlElementAttribute that specifies the name you want to use for each item:

public class Library

{

public string Librarian { get; set; }

[XmlElement("Book")]

public List<Book> Books { get; set; }

}

public class Book

{

public string Title { get; set; }

}

You should now notice that the instance is being serializer differently without the extra <Books> tag:

<Librarian>Kelly</Librarian>

<Book>

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

</Book>

<Book>

<Title>American Gods</Title>

</Book>

<Book>

<Title>Bel Canto</Title>

</Book>

</Library>

Note, however, that this is only an option with XmlSerializer. DataContractSerializer does not support serializing out a collection as an unwrapped list of elements. In my first post, I indicated that XmlSerializer allows for more flexible XML than DataContractSerializer. This is just one of the numerous ways in which XmlSerializer can produce XML that DataContractSerializer simply cannot.

Changing the names of the XML tags

If you are happy with keeping your collection wrapped within an element, then you still may want to change the names of the XML tags. To do so with XmlSerializer, you can use XmlArrayAttribute and XmlArrayItemAttribute to configure the names. XmlArray defines the wrapper name and XmlArrayItem defines the item name:

public class Library

{

public string Librarian { get; set; }

[XmlArray("FavoriteBooks")]

[XmlArrayItem("FavoriteBook")]

public List<Book> Books { get; set; }

}

public class Book

{

public string Title { get; set; }

}

To change the names with DataContractSerializer, you will need to define a new type that derives from List<Book> and is marked with a CollectionDataContractAttribute. The DataMember name defines the wrapper name and the ItemName on the CollectionDataContract defines the item name:

[DataContract]

public class Library

{

[DataMember]

public string Librarian { get; set; }

[DataMember(Name="FavoriteBooks")]

public BookList Books { get; set; }

}

public class Book

{

public string Title { get; set; }

}

[CollectionDataContract(ItemName="FavoriteBook")]

public class BookList : List<Book> { }

In both of these cases, the XML that’s serialized out should look something like this:

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

</FavoriteBook>

<Title>American Gods</Title>

</FavoriteBook>

<Title>Bel Canto</Title>

</FavoriteBook>

</FavoriteBooks>

<Librarian>Kelly</Librarian>

</Library>

Configuring Known Types Dynamically - Introducing the DataContractResolver

2009-06-05T23:07:00Z

This post has been updated to account for the changes to the DataContractResolver in the Beta 2 release of .NET 4.0.

This will be my first of several posts about new features that are showing up in the Beta 1 release of .NET 4.0. Beta 1 was released just a few weeks ago and you can download it today here. The most important addition to DataContract Serialization in this release is the addition of the DataContractResolver.

In previous posts, I’ve talked about known types: why they’re needed in some situations and how to use them. Up to now though, it’s only been possible to define known types statically. That is, you have to know ahead of time what types you want to register as known types. So in previous examples, you had to know that Dog would be a known type and then register it as such. This is a problem though if you don’t know the types ahead of time. What if you wanted all types to be serialized out to the wire, regardless of whether they were listed as known types? In that case, you would need a callback mechanism to serialize known types and then resolve them on deserialization. That is exactly what DataContractResolver can do for you. Users can inherit from DataContractResolver, implement the callbacks, and then plug their resolvers into a serializer or into WCF.

But first let’s go through the basics of how the resolver works:

DataContractResolver defines two methods that you can override:

bool TryResolveType(Type dataContractType, Type declaredType, DataContractResolver knownTypeResolver, out XmlDictionaryString typeName, out XmlDictionaryString typeNamespace)

Type ResolveName(string typeName, string typeNamespace, Type declaredType, DataContractResolver knownTypeResolver)

TryResolveType is called on serialization to map a type into the name and namespace used to define the xsi:type, while ResolveName is called on deserialization to map the xsi:type name and namespace back into a type.

TryResolveType takes the type of the object being serialized, a declared type (more on these later), and a DataContractResolver. That resolver is the known type DataContractResolver. It mimics the behavior of the static known type resolution logic. So you can always call the known type resolver to get the same behavior you would have gotten without your resolver. The TryResolveType method returns a boolean indicating whether the resolver is able to resolve the type that was passed in, and two XmlDictionaryStrings which will be used to write the resolved name and namespace on the wire. If you’d rather deal with strings instead, it’s very easy to go from strings to XmlDictionaryStrings. Simply create an XmlDictionary and use the return value of the Add method:

XmlDictionary dictionary = new XmlDictionary();

typeName = dictionary.Add("string");

ResolveName also takes a declared type and a known type resolver, but it works the opposite way. It takes two strings which represent the name and namespace and returns a type.

To demonstrate how this class works, let’s play around with a couple types:

[DataContract]

public class Animal

{

[DataMember]

public int age = 4;

[DataMember]

public string name = "Rusty";

}

[DataContract]

public class Dog : Animal

{

[DataMember]

public DogBreed breed = DogBreed.LabradorRetriever;

}

public enum DogBreed {

GermanShepherd,

LabradorRetriever

}

Notice that I specifically haven’t referenced Dog as a known type. So if you try the following right now:

XmlObjectSerializer serializer = new DataContractSerializer(typeof(Animal));

serializer.WriteObject(new XmlTextWriter(Console.Out) { Formatting = Formatting.Indented }, new Dog());

You get the familiar known type exception string with a twist:

Unhandled Exception: System.Runtime.Serialization.SerializationException: Type 'Serialization.Dog' with data contract name 'Dog:http://schemas.datacontract.org/2004/07/Serialization' is not expected. Consider using a DataContractResolver or add any types not known statically to the list of known types - for example, by using the KnownTypeAttribute attribute or by adding them to the list of known types passed to DataContractSerializer.

Since the exception message told us to, let’s go ahead and do just that. I’m going to implement a simple resolver:

public class DogResolver : DataContractResolver

{

public override bool TryResolveType(Type dataContractType, Type declaredType, DataContractResolver knownTypeResolver, out XmlDictionaryString typeName, out XmlDictionaryString typeNamespace)

{

if (dataContractType == typeof(Dog))

{

XmlDictionary dictionary = new XmlDictionary();

typeName = dictionary.Add("WOOF");

typeNamespace = dictionary.Add("http://www.myAnimals.com");

return true; // indicating that this resolver knows how to handle "Dog"

}

else

{

// Defer to the known type resolver

return knownTypeResolver.TryResolveType(dataContractType, declaredType, null, out typeName, out typeNamespace);

}

public override Type ResolveName(string typeName, string typeNamespace, DataContractResolver knownTypeResolver)

{

if (typeName == "WOOF" && typeNamespace == "http://www.myAnimals.com")

{

return typeof(Dog);

}

else

{

// Defer to the known type resolver

return knownTypeResolver.ResolveName(typeName, typeNamespace, null);

}

This implementation essentially says “Map Dog to http://www.myAnimals.com:WOOF and map http://www.myAnimals.com:WOOF back to Dog”. When you don’t know how to handle a type, you should defer to the known type resolver. Now if you try the following code, plugging in your custom resolver in the DataContractSerializer constructor:

XmlObjectSerializer serializer = new DataContractSerializer(typeof(Animal), null, Int32.MaxValue, false, false, null, new DogResolver());

serializer.WriteObject(new XmlTextWriter(Console.Out) { Formatting = Formatting.Indented }, new Dog());

Not only do you not get an exception, but you should get the following XML:

<name>Rusty</name>

<breed>LabradorRetriever</breed>

</Animal>

Notice how the type showed up on the wire with xsi:type = http://www.myAnimals.com:WOOF.

It’s a good thing that serialization works, but your deserialization roundtrip works as well:

MemoryStream ms = new MemoryStream();

XmlObjectSerializer serializer = new DataContractSerializer(typeof(Animal), null, Int32.MaxValue, false, false, null, new DogResolver());

serializer.WriteObject(ms, new Dog());

ms.Position = 0;

Console.WriteLine(((Dog)serializer.ReadObject(ms)).breed);

Should print out LabradorRetriever.

The Declared Type parameter

As an input to both DataContractResolver methods, you’ll find a parameter called “declaredType”. What this corresponds to is the type that the serializer “expects” based on the contract. So, above, the serializer expected an Animal but got a Dog instead. So the declaredType for both methods would be the Animal type. Declared types are useful to have because they allow you to create a resolver like this:

public class DeserializeAsBaseResolver : DataContractResolver

{

public override bool TryResolveType(Type type, Type declaredType, DataContractResolver knownTypeResolver, out XmlDictionaryString typeName, out XmlDictionaryString typeNamespace)

{

return knownTypeResolver.TryResolveType(type, declaredType, null, out typeName, out typeNamespace);

}

public override Type ResolveName(string typeName, string typeNamespace, Type declaredType, DataContractResolver knownTypeResolver)

{

return knownTypeResolver.ResolveName(typeName, typeNamespace, declaredType, null) ?? declaredType;

}

This resolver first calls the knownTypeResolver, and if that fails, allows you to always deserialize as the type of the contract, effectively disregarding the xsi:type name on the wire. This is useful in a situation where you can receive any number of types that derive from one base class, but all you care about are the members on the base class. The resolver above would allow you to deserialize all instances of derived classes as the base class itself.

How to register a DataContractResolver

You’ve already seen how to plug in a DataContractResolver in the serializer’s constructor, but there are two other ways of registering your custom DataContractResolver:

You can plug it in on DataContractSerializer’s ReadObject and WriteObject methods:

MemoryStream ms = new MemoryStream();

DataContractSerializer serializer = new DataContractSerializer(typeof(Animal));

XmlDictionaryWriter writer = XmlDictionaryWriter.CreateDictionaryWriter(XmlWriter.Create(ms));

serializer.WriteObject(writer, new Dog(), new DogResolver());

writer.Flush();

ms.Position = 0;

Console.WriteLine(((Dog)serializer.ReadObject(XmlDictionaryReader.CreateDictionaryReader(XmlReader.Create(ms)), false, new DogResolver())).breed);

Note that this overload currently only works for XmlDictionaryReader/XmlDictionaryWriter and not for Stream or XmlReader/Writer.

Finally, you can also plug it into WCF by setting it on the DataContractSerializerOperationBehavior:

ServiceHost host = new ServiceHost(typeof(MyService));

ContractDescription cd = host.Description.Endpoints[0].Contract;

OperationDescription myOperationDescription = cd.Operations.Find("Echo");

DataContractSerializerOperationBehavior serializerBehavior = myOperationDescription.Behaviors.Find<DataContractSerializerOperationBehavior>();

if (serializerBehavior == null)

{

serializerBehavior = new DataContractSerializerOperationBehavior(myOperationDescription);

myOperationDescription.Behaviors.Add(serializerBehavior);

}

serializerBehavior.DataContractResolver = new DogResolver();

host.Open();

Console.WriteLine("Service started successfully");

Console.ReadKey();

host.Close();

Useful resolvers

Hopefully, you can see the use of the DataContractResolver. But if you still need help with that, here are a couple of resolvers you may find useful:

public class SharedTypeResolver : DataContractResolver

{

public override bool TryResolveType(Type dataContractType, Type declaredType, DataContractResolver knownTypeResolver, out XmlDictionaryString typeName, out XmlDictionaryString typeNamespace)

{

if (!knownTypeResolver.TryResolveType(dataContractType, declaredType, null, out typeName, out typeNamespace))

{

XmlDictionary dictionary = new XmlDictionary();

typeName = dictionary.Add(dataContractType.FullName);

typeNamespace = dictionary.Add(dataContractType.Assembly.FullName);

}

return true;

}

public override Type ResolveName(string typeName, string typeNamespace, Type declaredType, DataContractResolver knownTypeResolver)

{

return knownTypeResolver.ResolveName(typeName, typeNamespace, declaredType, null) ?? Type.GetType(typeName + ", " + typeNamespace);

}

This resolver gives the knownTypeResolver a chance to resolve a type or a name statically, and if that fails it uses the type and assembly name of the type on the wire instead. Note that this would only work on the .NET framework for tightly coupled scenarios. You’re basically getting DataContractSerializer behavior most of the type, and NetDataContractSerializer behavior for known types without ever having to specify a known type yourself.

For our last resolver, here’s something a bit more involved:

public class CachingResolver : DataContractResolver

{

Dictionary<string, int> serializationDictionary;

Dictionary<int, string> deserializationDictionary;

int serializationIndex = 0;

XmlDictionary dic;

public CachingResolver()

{

serializationDictionary = new Dictionary<string, int>();

deserializationDictionary = new Dictionary<int, string>();

dic = new XmlDictionary();

}

public override bool TryResolveType(Type dataContractType, Type declaredType, DataContractResolver knownTypeResolver, out XmlDictionaryString typeName, out XmlDictionaryString typeNamespace)

{

if (!knownTypeResolver.TryResolveType(dataContractType, declaredType, null, out typeName, out typeNamespace))

{

return false;

}

int index;

if (serializationDictionary.TryGetValue(typeNamespace.Value, out index))

{

typeNamespace = dic.Add(index.ToString());

}

else

{

serializationDictionary.Add(typeNamespace.Value, serializationIndex);

typeNamespace = dic.Add(serializationIndex++ + "#" + typeNamespace);

}

return true;

}

public override Type ResolveName(string typeName, string typeNamespace, Type declaredType, DataContractResolver knownTypeResolver)

{

Type type;

int deserializationIndex;

int poundIndex = typeNamespace.IndexOf("#");

if (poundIndex < 0)

{

if (Int32.TryParse(typeNamespace, out deserializationIndex))

{

deserializationDictionary.TryGetValue(deserializationIndex, out typeNamespace);

}

type = knownTypeResolver.ResolveName(typeName, typeNamespace, declaredType, null);

}

else

{

if (Int32.TryParse(typeNamespace.Substring(0, poundIndex), out deserializationIndex))

{

typeNamespace = typeNamespace.Substring(poundIndex + 1, typeNamespace.Length - poundIndex - 1);

deserializationDictionary.Add(deserializationIndex, typeNamespace);

}

type = knownTypeResolver.ResolveName(typeName, typeNamespace, declaredType, null);

}

return type;

}

This resolver allows you to cache namespaces. Since namespaces tend to be reused a lot and are usually very long, this improves sizes of known type namespaces by giving them a caching index: 0, 1, 2, …. It defines a namespace by using the # sign, so for example: "0#http://schemas.datacontract.org/2004/07/Serialization" and then whenever that namespace is reused in the future, it simply uses “0” as the namespace. The deserializer recognizes this syntax and maintains a dictionary of indices to namespaces.

Note however that this resolver makes several assumptions: notably that the serializer only talks to one deserializer and that instances are received in order.

So, as you can see, there are multiple uses for the DataContractResolver. But the main idea is the following: dynamic known type resolution. Hopefully this feature will make known types more powerful and a little bit less confusing to use.

You can find the full Beta 2 MSDN documentation for the DataContractResolver class at: http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractresolver(VS.100).aspx.

Configuring the Client Endpoint for svcutil

2009-05-12T23:01:00Z

One of the more common questions I get is along these lines:

I want to configure svcutil to use a particular binding. How do I do that?

Usually, this happens for one of two reasons:

1) You’ve exposed your metadata with a secure binding, and need a way to generate proxy from it.

2) The size of your metadata is too large for svcutil’s defaults.

In both these cases, you usually get a non-descript error message from svcutil:

Error: Cannot obtain Metadata from http://localhost/

If this is a Windows (R) Communication Foundation service to which you have access, please check that you have enabled metadata publishing at the specified address. For help enabling metadata publishing, please refer to the MSDN documentation at http://go.microsoft.com/fwlink/?LinkId=65455.

WS-Metadata Exchange Error

URI: http://localhost/

Metadata contains a reference that cannot be resolved: 'http://localhost/mex.

There is an error in XML document (1, 120595).

The maximum nametable character count quota (16384) has been exceeded while reading XML data. The nametable is a data structure used to store strings encountered during XML processing - long XML documents with non-repeating element names, attribute names and attribute values may trigger this quota. This quota may be increased by changing the MaxNameTableCharCount property on the XmlDictionaryReaderQuotas object used when creating the XML reader. Line 1, position 120595.

The way to fix these issues is to locate your copy of svcutil.exe (usually under C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin), create a file called svcutil.exe.config and add configuration just like you would configure a client endpoint.

For example, to use an http binding that has the maximum value for each quota, copy the following XML into your svcutil.exe.config

<?xml version="1.0" encoding="utf-8"?>

<system.serviceModel>

</textMessageEncoding>

</binding>

</customBinding>

</bindings>

</client>

</system.serviceModel>

</configuration>

Of course, the same method can be used to change the type of binding you want to use (named pipes, tcp, etc…) and to configure your binding with security.

Using XML Schema Import and Export for DataContractSerializer

2009-04-29T21:41:00Z

For many WCF developers, service metadata import and export is a magical thing. You start your service with a serviceMetadataBehavior, set httpGetEnabled to true or add an IMetadataExchange endpoint, and metadata gets automatically generated for you. Then you run svcutil or use Add Service Reference, and you get proxy code that just works without you having to delve into the details of how or why it even works to begin with. But it’s always worth going into details of how a framework does what it does. It allows you to customize WCF to suit your needs, and gives you a better understanding of your own software. I’ll attempt to demystify an important part of how metadata import and export works in today’s blog post.

SOA Metadata: WSDLs and XSDs

Metadata can be divided up into two different types:

1) The metadata for your service, describing everything about the service: its operations, messages, binding, etc…

2) The metadata that describes the data types you’ll be sending over the wire as XML schemas.

While it is possible to include XML schemas in a WSDL file through the <wsdl:types> section of a wsdl, WCF makes the distinction very clear by instead referencing separate schemas by using the <xs:import> tag. Using “svcutil /t:metadata” for example, you’ll see that you get exactly one wsdl file for a service, and multiple xsd files for each targetNamespace that needs to be defined.

I’ll be playing around with the second type of metadata in this post, and showing specifically how it can be used for DataContractSerializer.

Metadata Import

Let’s reuse the type I happened to use in my last post:

[DataContract]

public class Animal

{

[DataMember]

public int age = 4;

[DataMember]

public string name = "Rusty";

}

[DataContract]

public class Dog : Animal

{

[DataMember]

public DogBreed breed = DogBreed.LabradorRetriever;

}

public enum DogBreed {

GermanShepherd,

LabradorRetriever

}

Now, you have a DataContract that you’d like to see the XSDs for. How do you do that? It’s actually very simple:

XsdDataContractExporter exporter = new XsdDataContractExporter();

exporter.Export(typeof(Dog));

foreach (XmlSchema schema in exporter.Schemas.Schemas())

{

schema.Write(Console.Out);

Console.WriteLine("\n");

}

You should find three schemas in the output. Let’s go through them:

Schema 1:

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

<xs:schema xmlns:tns="http://schemas.microsoft.com/2003/10/Serialization/" attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/2003/10/Serialization/" xmlns:xs="http://www.w3.org/2001/XMLSchema">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<xs:simpleType name="char">

<xs:restriction base="xs:int" />

</xs:simpleType>

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

<xs:simpleType name="duration">

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

<xs:pattern value="\-?P(\d*D)?(T(\d*H)?(\d*M)?(\d*(\.\d*)?S)?)?" />

<xs:minInclusive value="-P10675199DT2H48M5.4775808S" />

<xs:maxInclusive value="P10675199DT2H48M5.4775807S" />

</xs:restriction>

</xs:simpleType>

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

<xs:simpleType name="guid">

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

<xs:pattern value="[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12}" />

</xs:restriction>

</xs:simpleType>

<xs:attribute name="FactoryType" type="xs:QName" />

<xs:attribute name="Id" type="xs:ID" />

<xs:attribute name="Ref" type="xs:IDREF" />

</xs:schema>

This is the WCF DataContractSerializer schema. It should be included in the metadata for any DataContract, or for any service that uses DataContratSerializer. As you can see, it maps various DataContractSerializer primitives into XML primitives, or into XML data types. The second schema is more interesting:

Schema 2:

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

<xs:schema xmlns:tns="http://schemas.datacontract.org/2004/07/" elementFormDefault="qualified" targetNamespace="http://schemas.datacontract.org/2004/07/" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:complexType name="Dog">

<xs:complexContent mixed="false">

<xs:extension base="tns:Animal">

<xs:sequence>

<xs:element minOccurs="0" name="breed" type="tns:DogBreed" />

</xs:sequence>

</xs:extension>

</xs:complexContent>

</xs:complexType>

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

<xs:complexType name="Animal">

<xs:sequence>

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

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

</xs:sequence>

</xs:complexType>

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

<xs:simpleType name="DogBreed">

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

<xs:enumeration value="GermanShepherd" />

<xs:enumeration value="LabradorRetriever" />

</xs:restriction>

</xs:simpleType>

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

</xs:schema>

This is the schema for our types. I’ve highlighted some interesting parts. Notice how xs:extension is used to indicate that Dog inherits from Animal. And notice how the DogBreed enum is mapped into a simpleType restriction with xs:enumeration values.

And finally, we have one last small schema that defines the “schema” element.

Schema 3:

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

<xs:schema targetNamespace="http://www.w3.org/2001/XMLSchema" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="schema">

<xs:complexType />

</xs:element>

</xs:schema>

Metadata Export

Now that your DataContract has been turned into an XML schema definition, you might be wondering “Well, how do I get my DataContract back?”. And the answer to that is pretty simple as well. You use XsdDataContractImporter to get a CodeCompileUnit out of the schemas. And then use your CodeProvider of choice (we’ll use the C# provider in this case) to get the code for your DataContract back from the XSD.

Add the following to your code:

XsdDataContractExporter exporter = new XsdDataContractExporter();

exporter.Export(typeof(Dog));

foreach (XmlSchema schema in exporter.Schemas.Schemas())

{

schema.Write(Console.Out);

Console.WriteLine("\n");

}

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

XsdDataContractImporter importer = new XsdDataContractImporter();

importer.Import(exporter.Schemas);

CSharpCodeProvider provider = new CSharpCodeProvider();

provider.GenerateCodeFromCompileUnit(importer.CodeCompileUnit, Console.Out, null);

Now you get:

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

// <auto-generated>

// This code was generated by a tool.

// Runtime Version:2.0.50727.3074

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

// the code is regenerated.

// </auto-generated>

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

using System.Runtime.Serialization;

[System.Diagnostics.DebuggerStepThroughAttribute()]

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

[System.Runtime.Serialization.DataContractAttribute(Name="Animal", Namespace="http://schemas.datacontract.org/2004/07/")]

[System.Runtime.Serialization.KnownTypeAttribute(typeof(Dog))]

public partial class Animal : object, System.Runtime.Serialization.IExtensibleDataObject {

private System.Runtime.Serialization.ExtensionDataObject extensionDataField;

private int ageField;

private string nameField;

public System.Runtime.Serialization.ExtensionDataObject ExtensionData {

get {

return this.extensionDataField;

}

set {

this.extensionDataField = value;

}

[System.Runtime.Serialization.DataMemberAttribute()]

public int age {

get {

return this.ageField;

}

set {

this.ageField = value;

}

[System.Runtime.Serialization.DataMemberAttribute()]

public string name {

get {

return this.nameField;

}

set {

this.nameField = value;

}

[System.Diagnostics.DebuggerStepThroughAttribute()]

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

[System.Runtime.Serialization.DataContractAttribute(Name="Dog", Namespace="http://schemas.datacontract.org/2004/07/")]

public partial class Dog : Animal {

private DogBreed breedField;

[System.Runtime.Serialization.DataMemberAttribute()]

public DogBreed breed {

get {

return this.breedField;

}

set {

this.breedField = value;

}

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

[System.Runtime.Serialization.DataContractAttribute(Name="DogBreed", Namespace="http://schemas.datacontract.org/2004/07/")]

public enum DogBreed : int {

[System.Runtime.Serialization.EnumMemberAttribute()]

GermanShepherd = 0,

[System.Runtime.Serialization.EnumMemberAttribute()]

LabradorRetriever = 1,

}

This generated DataContract is exactly equivalent to the DataContract you started off with! Dog inherits from Animal, and the same members are still there. All the fields have been wrapped with properties, but the property name is still the same as the original field name. Finally, you might also notice a member of type ExtensionDataObject on Animal. This is a member used for the deserialization of versioning information. If the serializer doesn’t recognize a member that’s being sent on the wire , it gets added to the ExtensionDataObject.

I hope I’ve helped to clarify what happens when you generate or consume metadata from a WCF service. It should be pretty obvious how WCF makes use of XsdDataContractExporter and XsdDataContractImporter after this.

Finally, if you'd like to learn how to import and export schemas for types you'll be serializing with XmlSerializer, please take a look at this post.

Testing the performance of known types

2009-04-24T23:19:00Z

In my last post, I claimed that one of the reasons you should try to avoid known types is that it significantly degrades performance. But you should never take anyone’s word about performance, so here’s an actual test comparing the performance of using known types and not using known types:

Setup

The test measures serialization and deserialization of a type using known types and without known types. Without known types, we try serializing and deserializing the following DogContainer class:

[DataContract]

public class DogContainer

{

public DogContainer(Dog dog)

{

this.animal = dog;

}

[DataMember]

public Dog animal;

}

[DataContract]

public class Animal

{

[DataMember]

public int age = 4;

[DataMember]

public string name = "Rusty";

}

[DataContract]

public class Dog : Animal

{

[DataMember]

public DogBreed breed = DogBreed.LabradorRetriever;

}

public enum DogBreed {

GermanShepherd,

LabradorRetriever

}

In the known types case, the only difference is that we use the following AnimalContainer class instead:

[DataContract]

[KnownType(typeof(Dog))]

public class AnimalContainer

{

public AnimalContainer(Animal animal)

{

this.animal = animal;

}

[DataMember]

public Animal animal;

}

We’ll be serializing two instances of AnimalContainer/DogContainer:

new DogContainer(new Dog())

new AnimalContainer(new Dog())

Now, serializing these instances produces very similar XML:

<name>Rusty</name>

<breed>LabradorRetriever</breed>

</animal>

</DogContainer>

<name>Rusty</name>

<breed>LabradorRetriever</breed>

</animal>

</AnimalContainer>

The only differences are that the class names are slightly different and AnimalContainer uses xsi:type. This is expected because that instance uses known types, and as I showed in the last post, this is the mechanism by which known types can be resolved correctly.

Test

For serialization, I used the following code:

XmlObjectSerializer serializer = new DataContractSerializer(graph.GetType());

MemoryStream ms = new MemoryStream();

for (int i = 0; i < 1000000; i++)

{

serializer.WriteObject(ms, graph);

}

And for deserialization I used:

XmlObjectSerializer serializer = new DataContractSerializer(graph.GetType());

MemoryStream ms = new MemoryStream();

serializer.WriteObject(ms, graph);

ms.Flush();

for (int i = 0; i < 1000000; i++)

{

ms.Position = 0;

serializer.ReadObject(ms);

}

In both cases, graph corresponds to the instance we’re serializing (either AnimalContainer or DogContainer) and I only measured the time spent in the for loop.

Results

As it turns out, using known types in this situation reduced the serialization throughput by 31% and the deserialization throughput by 24%. So using known types can in fact have a significant impact on your serialization performance.