Development

Getting Started with WCF Part 8 – REST Services: the Basics and Building Your First REST Service

James Bender — Wed, 07 Dec 2011 00:20:18 GMT

Previous posts in this series:

… annnnnnd we’re back.

Based on the strengths of REST outlined in my last post in this series, it would be a good tool to add to our WCF service arsenal. Our web-based bagel bakery has been very successful, prompting the opening of new locations. Some of these locations are the traditional “counter service” type of bagel store that people are more accustomed to. Others are a café style with an expanded menu, fancy coffee and Internet access.

Our web page has a list of these locations, but as anyone invested in mobile development will tell you, you can’t have a successful business these days without having a smartphone application.A feature we would like for our smart phone application is a store locator. For now, we just want to provide a list of stores that the application can consume, but we don’t want this information hard-coded into the application, as it’s possible that any day now a large amount of venture capital will fall into our lap and we’ll want to open more stores

The best solution is to provide a web service that allows the application to access a current list of open stores at any time. To keep this service light weight and ensure that it is open to any smart phone platform we have decided to make this a REST based service. With WCF this is very easy.

Step One: The Service Contract

SOAP and REST based services are very different. The fact is that WCF was built on the idea of building SOAP based services and that is the focus of the classes in the System.ServiceModel assembly. In .NET 3.5 Microsoft added REST functionality to WCF in the form of the System.ServiceModel.Web assembly. This new assembly added some pieces that we will need to create our REST service.

Consider this service contract:

By now you should be able to easily determine that any service that implements this IStoreLocatorService contract must expose an action method called GetStores that returns a list of some Store objects. As is this is a standard WCF service an action that responds to an HTTP POST and returns a list of Stores in a SOAP message is created.

In order to tell WCF that we want this to be a REST based service we need to add an additional attribute to our operation:

The inclusion of the WebGet attribute in our service contract tells WCF that, depending on some configuration details, a service that implements this contract must be able to respond to an HTTP call with the GET verb (hence the “Get” in “WebGet”). For now don’t worry about the other verbs, we’ll get to them later.

There are several arguments we can pass into the WebGet attribute to change how this method behaves, but for now we’re just using the UriTemplate option. The UriTemplate tells WCF what the URI that access this service should look like. In this case we’re telling WCF that if the base address of our service is “www.WebBagels.com” and the client uses that as it’s URI it will access this method via a pattern match. If we were to make a small change to the UriTemplate for our service….

… our service will now be called if the client attempts to access the www.WebBagles.com/Stores URI.

That’s pretty nifty, but what happens if a user is specifically looking for one of our “café” stores? Users are going to want a way to filter this list. And besides, one of the big benefits of REST is supposed to be the cacheable, easy to understand hierarchical way of representing data, right?

WCF makes if very easy, again using a simple pattern matching algorithm to enable us to have dynamic arguments embedded in our URI. We’ll add a new method to our service contract that enables users to search for specific store types:

Our new method still responds to an HTTP GET, but we’ve added a second UriTemplate with a different patters to match. In our GetStoresByStoreType method we are now looking for a URI that includes the store type of the stores we are searching for.

The first thing I had to do was create a new method called GetStoresByStoreType that took a string parameter of storeType. It’s important to note that when you are using parameterized URI’s like we are here, the arguments for your method MUST all be strings; no other types are allowed. The reason is that the URI itself is a string and all constituent parts of it must be treated as strings as well. You can cast them all you want once they are passed into your method, but the method prototype must define these as strings. Aside from that you need to make sure that the token you are using in the UriTemplate (in this case {storeType}) matches the name of the parameter you want to map it to, including capitalization. Order is unimportant and if the URI has a token that does not map to a parameter on your method WCF will just ignore it. On the other hand if you have a parameter for your method that does not map to a token in your UriTemplate .NET will throw an error since it is missing parameters for the method call.

Based on this service contract we will have two URI’s that our service is able to respond to:

www.WebBagles.com/Stores – Results in a call to the GetStores method, returns a list of all stores.
www.WebBagles.com/Stores/{storeType} – Results in a call to the GetStoresByStoreType method, returns a filtered list of stores.

One last thing to notice here: The names of the .NET methods in our service contract has no bearing on or relationship to our URI’s. We could call those two methods anything we want (provided it’s a name .NET deems legal) and as long as our URI templates don’t change our clients would never know. This means that once we expose an API we can refactor internally all we want so long as we don’t change (mess up) those UriTemplates and break the API.

By default WCF returns POX (Plain Ol’ XML) for it’s REST methods. Most users, myself included, would rather consume this information as JSON (JavaScript Object Notation) in many, if not most situations. For one thing as a web developer I find myself taking more and more advantage of AJAX calls from the browser. In these cases I would much rather consume the native JSON object than futz with the JavaScript XML parser.

Having said that there are a lot of applications that consume REST services from C# or VB.NET and XML seems to be the more popular choice in those languages. As a result I like to write my REST services in a way that enables the users to determine how they get the data back (POX or JSON). For this service I’ll do that by adding a two new operation contracts to my IStoreLocatorService service contract; one to return all stores as a list of JSON objects and another to return list of stores filtered by store type as JSON objects:

First let’s compare the contract for GetStores to the one for GetStoresInJson. The UriTemplate for GetStoresInJson is the same as the UriTemplate for the GetStores contract, except that I’ve added “/js” to the end. When WCF sees a request for a URI that looks like “~/Stores/js” it knows to route that action to the GetStoresInJson method since the incoming URI matches the pattern defined in the WebGet attribute of the GetStoresInJson method. Similarly, the GetStoresByStoreTypeInJson method is able to respond to requests that have URI’s with the pattern of “~/Stores/{storeType}/js” as opposed to “~/Stores/{storeType}” mapping those actions to the GetStoresByStoreType method which returns POX.

The other change to note is that unlike the previous methods we worked with (GetStores and GetStoresByStoreType) we’ve added a new parameter to the WebGet attribute; ResponseFormat. As you can probably infer from it’s name, it’s used to tell WCF how you want the response from the service formatted. As I mentioned before the default is POX, but by specifying a value for the ResponseFormat (in this case WebMessageFormat.Json) we can change how the data is returned. As you may guess there is a corollary parameter, RequestFormat that specifies how the service should expect incoming request data to be formatted, but I’ll get into that in a future post.

I’ve talked quite a bit about the service contact side of building these REST based services, but I haven’t touched on the implementation. That’s because the vast majority of the work to make these WCF services RESTful is done in the service contract. Here are the implementations for GetStores and GetStoresInJson:

As you can see, there isn’t really much to these implementations. The methods just return a list of Store objects. The GetStoresByStoreType and GetStoresByStoreTypeInJson just use a LINQ query to get the specific stores that match the store type out of the ListOfStores list. WCF, via the definition in the service contract will serialize this as either POX or JSON when it’s returned.

Step Two: The Data Contract

So how about that Store object? Like all complex structures that are sent received via WCF services, the easiest way to deal with it is to create a Data Contract. The Data Contract for our REST based service is very similar to the data contracts we’ve created for the other services in this series:

Like the previous data contracts this one has a class level attribute of DataContract and each property that I want to expose via the service is decorated with a DataMember attribute. In this case I have added a Namespace parameter to the DataContract attribute at the class level. I’ll explain why and more about namespaces in a future post.

Step Three: Updating the Host

The previous services in this series were all SOAP services. As a result we were able to use the ServiceHost class to host those services. Since REST services live by a different set of rules than SOAP services, particularly the use of parameterized URI’s REST services needs a host with slightly different capabilities than the one used for SOAP services.

WCF provides the WebServiceHost class for hosting REST based web services. As you can see from this code snippet, it’s just as easy to use as the ServiceHost class:

Now that we have our hosting situation sorted out, it’s time to look as our configuration.

Step: Four: Updating the configuration

Since we’ve added a new service to our solutions, we need to add a new service section to our configuration. We already did this for our SOAP service and our REST service is actually pretty easy by comparison:

The address attribute identifies the base address for our service. The URI Template from our service contract is appended to this base URI in the configuration. This means that the URI we will use to get to the list of stores is http://localhost:8733/Stores. To search by store type the URI would be http://localhost:8733/Stores/<store type being searched>.

For binding we’ll need to use the webHttpBinding. This is a REST specific binding and will tell WCF to build a channel stack that includes the serializers for POS and JSON messages. Contract behaves exactly the same way it has for our SOAP services.

This configuration works for our self-hosted service. For hosting REST based WCF services in IIS you will need to make a couple more small changes. I’ll cover those configuration changes in a few posts when I cover deployment.

Step Five: Testing and Profit

To test our SOAP services we either had to use the WCF test client of write an application that created a proxy object that would serialize and send SOAP messages as POST actions and deserialzie the SOAP messages that were returned. Since REST based services are HTTP based and don’t reply with complex SOAP messages we can easily test our service in any web browser. To test our service I’ll start by launching the hosting application:

I’ll fire up Chrome (I prefer Chrome over IE for this, you’ll see why in a minute) and put the URI for our Stores REST service into the address bar (this is the base address from the configuration of the endpoint plus the URI template from the service contract) and hit Enter. Since our service just returns POX, we have not problem being able to view the message in Chrome (or any browser for that matter) without our faces melting:

To filter this down by store type we can add the store type to the URI as proscribed by the URI template in the operation contract for the GetStoresByStoreType method of our Service Contract:

WCF mapped the URI with the store type data to the correct method that filtered the store data by store type. What happens if we supply a store type that has no stores:

We simply got an empty list back. This is the preferred way REST services should handle this type of situation; if there is no data that satisfies the query then return an empty result.

Say we want JSON. As we provided additional Operation Contracts that specified JSON as the response format when “/js” was added to our URI we simply need to add that to our current URI to change the format of the response data:

Line-breaks aside, JSON is a pretty easy format to understand and digest. Incidentally, JSON services are why I prefer to use Chrome for this kind of testing as opposed to Internet Explorer. For whatever reason IE does not want to render JSON and instead will make you save it to a file which you then will have to open in a text editor:

The end result is the same, but I appreciate that Chrome doesn’t make me go through this extra step to see my data.

You may have noticed that we didn’t work much with query strings here. That will be covered in a future post.

In the next post we’ll see how to send data to our service with the POST verb and lean how to test our services with one of my favorite all time developer tools.

Code on!

You Never Forget Your First….

James Bender — Tue, 10 May 2011 17:48:41 GMT

For the one or two people out there who probably haven’t heard yet, I’ve spend the past year writing a book. Well, not completely by myself; I had a lot of help from Jeff McWherter and Mike Eaton. I’m happy to say that after almost a year of hard work, late nights missed social engagements and infinite patience from Gayle, the book is officially released!

For those of you who have received your copy already via Amazon, I hope you are enjoying it. The Kindle version is available today. For those of you who didn’t pre-order, the book should (I hope) now be available at your local book store. Please take a look and visit the Facebook page to tell me what you think.

I’m also happy to report that I’ll be writing another book. This one will still be for Wiley publishing, but will probably not be on the Wrox imprint. More details to follow.

Working with WCF returns from hiatus next week!

DevLink 2010 Slides and Demo

James Bender — Mon, 09 Aug 2010 22:01:50 GMT

I had a great time speaking, learning and just generally hanging out at DevLink as always. It’s quickly becoming one of my most eagerly anticipated events of the year. I was honored to be allowed to speak at this years event, and as promised here are all my slide decks and demos.

See you next year!

Working with WCF: Part Six – Fault Contracts

James Bender — Wed, 23 Jun 2010 15:38:13 GMT

Previous posts in this series:

There are four “major” contract types in WCF and at this point we’ve covered three of them; the Service Contract, Data Contract and Message Contract. The last one to cover is the Fault Contract. I began writing a post on how to work with Fault Contracts, and I immediately got a distinct feeling of déjà vu. It was as if I had somehow written this post before. Turns out there was a good reason for this, I had written it before. Twice in fact. Being a developer who values the concept of keeping your code DRY (Don’t Repeat Yourself) I’ve decided to re-publish these original posts (with a few tweaks) here. Obviously this will not be keeping with our “Bagel Factory” analogy, so think of it as having a substitute teacher.

Before That Though…

What is and why do we need a Fault Contract? Well, if the days of ASMX based web services there was no built-in way to report exceptions back to the client. For the most part, the only way a client found out something was wrong was that the call to the web service timed out. There was no other explanation. This was a tremendous source of frustration for client developers, and also prompted many a developer and architect to pull their hair out over the prospect of reporting some sort of exception information back to the client. A lot of developers, myself included, broke out the duct tape, chewing gum and bailing wire and attempted to build some sort of notification mechanism that would not leave the clients hanging (no pun intended). These solutions ranged from complicated to outrageously complicated. All met with limited success.

WCF introduced the concept of a Fault Contract. As you’ll see below, a Fault Contract is simply a Data Contract that contains some information (as much or as little as you decide) about what happened that caused the call to fail. When you specify a Fault Contract for an operation what you’re doing is telling WCF that in addition to whatever your return type for that action is, it may also send back a FaultException, which is really just a wrapper for the instance of the Fault Contract you specified. This allows you to wrap your service calls in a Try/Catch block and catch meaningful exceptions.

Your Substitute Teachers (Be Nice!)

First off, Scott Hanselman wrote a terrific blog post on exceptions. It’s a great place to start and if you haven’t read it you should.

Using Fault Contracts is very easy. In fact, you can do it in four steps...

Step 1: Admit your faults

The first thing we need to do is determine what kind of information we want to return back to the client and create a Data Contract that contains that information. You may have several kinds of fault classes, and you should so that you can return specific types of information for specific faults. Kinda like why there isn't just one Exception class in .NET. Although these are data contracts, you should not use them for anything other than sending faults back to the client. Here's a sample fault class:

[DataContract]
    public class MyFault
    {
        private string _message = string.Empty;
 
        public MyFault(string message)
        {
            _message = message;
        }
 
        [DataMember]
        public string Message
        {
            get
            {
                return _message;
            }
            set
            {
                _message = value;
            }
        }
    }

Like any .NET class, you can create a fault class the inherits from another .NET class, BUT that class also needs to be a data contract and be a known type.

Step 2: Find where you may go wrong

Next, we need to let WCF know where these faults might be coming from. This is done at the operation in the service contract. You simply use a FaultContract attribute which lets WCF know what kind of possible fault class to expect:

[ServiceContract]
public interface IFaultyService
{
    [OperationContract]
    [FaultContract(typeof(MyFault))]
    void ThrowMeAnError();
}

You can specify as many faults for the operation as you like, simply add more FaultContract attributes:

[ServiceContract]
public interface IFaultyService
{
    [OperationContract]
    [FaultContract(typeof(MyFault))]
    [FaultContract(typeof(MyOtherFault))]
    [FaultContract(typeof(YetAnotherFault))]
    void ThrowMeAnError();
}

Step 3: The throw...

Throwing faults from a service is a little different than throwing them from C# or VB code. We need to enclose our fault class in a FaultException<T>, which represents a SOAP exception. This is just as easy as the other steps:

throw new FaultException<MyFault>(new MyFault("This is a fault"), "Demonstration");

The second argument, in this case "Demonstration" is the reason for the fault. And yes, "reason" is the attribute name of the fault too. This can either be a string or a FaultReason object which allows you to send more detailed information about the exception.

Step 4: ... and the catch

If you've done everything correctly, when you generate a reference to your service, in addition to the normal proxy information, you should have a class representing the data contract you created for your fault class. Catching this exception on the client side is similar to throwing it on the server side. It will come wrapped in a FaultException<T> and you will need to specify that to catch it correctly:

.
.
.
catch(FaultException<MyFault> itsMyFault)
{
    Console.WriteLine("MyFault was caught");
    Console.WriteLine(string.Format(@"Message: {0}", itsMyFault.Detail.Message));
    Console.WriteLine(string.Format(@"Reason: {0}", itsMyFault.Reason));
}
.
.
.

As you can see, getting the reason is pretty straight forward. Our message, and any other field me might have added, will be accessible as a member of the Detail child object of our fault.

That's it. See, nothing to it.

Actually, this rabbit hole does go a little deeper…

When you use WCF on the client side, and your service back-end is not necessarily WCF, then you may not necessarily get a WCF-style Fault Contract. Even WCF, being a close cousin of ASP.NET, can send non-service friendly messages down the pipe (sort of it’s version of the “yellow screen of death”). Lets look a little more closely at how exceptions get received by a WCF client and how the WCF channel reacts to exceptions. We’ll start with what happens if you just throw a normal .NET exception. For this example we’ll be looking at a mock up of a service to return prices for stocks based on a ticker symbol.

The service contact:

   1:      [ServiceContract]

   2:      public interface IMyWcfService

   3:      {

   4:          [OperationContract]

   5:          decimal GetStockPrice(string symbol);

   6:      }

And the implementation:

   1:      public class MyWcfService : IMyWcfService

   2:      {

   3:          public decimal GetStockPrice(string symbol)

   4:          {

   5:              switch (symbol)

   6:              {

   7:                  case "MSFT":

   8:                      return (decimal) 1.41;

   9:                  case "IBM":

  10:                      return (decimal).89;

  11:                  case "JAVA":

  12:                      return (decimal).10;

  13:                  default:

  14:                      throw new ArgumentOutOfRangeException("symbol", "bad symbol");

  15:              }

  16:          }

  17:      }

Since this is a contrived demo, we only handle three symbols and return a static value. This does however provide us with an opportunity to see how .NET exceptions work in WCF. If we receive a symbol that is not in our list, we are throwing an ArgumentOtOfRangeException. If we were using this as just a .NET object we wouldn’t have a problem; either our code would catch the exception and do something with it, or it would bubble up to the user.

Our client is a winform application. The important part is the call to our service (via a proxy of course):

   1:  public partial class Form1 : Form

   2:  {

   3:      private readonly MyWcfServiceClient _proxy;

4:

   5:      public Form1()

   6:      {

   7:          InitializeComponent();

   8:          btnCallService.Click += CallService;

   9:          _proxy = new MyWcfServiceClient();

  10:      }

11:

  12:      public void CallService(object sender, EventArgs e)

  13:      {

  14:          lblResult.Text = _proxy.GetStockPrice(txtSymbol.Text).ToString();

  15:      }

  16:  }

So all we’re doing is grabbing a value (the ticker symbol) from a text box and passing it as an argument to the service. The result is used to set the value of a label control. When we run this and feed one of the three symbols that our service uses, the expected happens: a value is returned and set to the text of the label. When we provide an unsupported symbol, we get an error:

The exception text should look familiar to anyone who has worked with ASP.NET…

System.ServiceModel.FaultException: The server was unable to process the request due to an internal error. For more information about the error, either turn on IncludeExceptionDetailInFaults (either from ServiceBehaviorAttribute or from the <serviceDebug> configuration behavior) on the server in order to send the exception information back to the client, or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation and inspect the server trace logs.

Like ASP.NET, WCF will not return detailed exception information to clients as a security measure. Also like ASP.NET, we have the ability to change the configuration to return more detailed exception information. One line nine below, we have set the includeExceptionDetailInFaults value to “True”:

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

   2:  <configuration>

   3:    <system.serviceModel>

   4:  ...

   5:      <behaviors>

   6:        <serviceBehaviors>

   7:          <behavior name="Service1Behavior">

   8:            <serviceMetadata httpGetEnabled="True"/>

   9:            <serviceDebug includeExceptionDetailInFaults="True" />

  10:          </behavior>

  11:        </serviceBehaviors>

  12:      </behaviors>

  13:    </system.serviceModel>

  14:  </configuration>

This results in the details of the error message being passed back to us:

This can be OK for development, but is not a good idea for production.

Let’s make a few changes to our client application:

   1:  public void CallService(object sender, EventArgs e)

   2:  {

   3:      try

   4:      {

   5:          lblResult.Text = _proxy.GetStockPrice(txtSymbol.Text).ToString();

   6:      }

   7:      catch

   8:      {

   9:          MessageBox.Show("Service call failed");

  10:      }

  11:  }

By catching the exception we can let the user know that something happened and handle it gracefully. Running the application and use the symbol “ORCL” causes the exception, which is handled:

So, we can just re-submit a supported symbol right…?

Uh-oh.

Turns out that when a WCF service throws a normal .NET exception, it faults the channel. Any subsequent calls to the channel results in a CommunicationObjectFaultedExcption being thrown immediately. The channel cannot be salvaged; your only option is to throw it out and recreate it. The proxy implements an interface called ICommunicatioObject that has a Faulted event that we can subscribe to.A few more changes to our client…:

   1:  private MyWcfServiceClient _proxy;

2:

   3:  public Form1()

   4:  {

   5:      InitializeComponent();

   6:      btnCallService.Click += CallService;

   7:      _proxy = new MyWcfServiceClient();

   8:      ((ICommunicationObject)_proxy).Faulted += RecreateProxy;

   9:  }

10:

  11:  void RecreateProxy(object sender, EventArgs e)

  12:  {

  13:      _proxy = new MyWcfServiceClient();

  14:  }

… and now our client is able to recreate the proxy if a communication fault occurs.

This way of dealing with exceptions in WCF works well if you are a client of a service that you may not control or have the metadata needed to create a fault contract for. Otherwise, using the FaultException class and/or WCF fault contracts are a better way to go. I’ll be covering them more in detail in the next couple posts.

Code on!

Working with WCF: Part Five - Message Contracts

James Bender — Tue, 15 Jun 2010 14:42:20 GMT

Previous posts in this series:

Like all Internet based businesses, our Web Bagels company has become wildly successful. This, of course, has resulted in Venture Capitalists throwing obscene amounts of cash at us. There is only one thing to do: expand. In addition to our retail delivery business we now want to start supplying local grocery stores, coffee shops and restaurants with our bagels. To accommodate this, we also have expanded our physical resources and now have several smaller commercial bakeries scattered across the region. Each satellite kitchen is responsible for one or more commercial accounts (baking and billing). We want this to be somewhat transparent to our customers; we don’t want them to have to specify (or even have to know) the specific bakery that will be producing their bagels. Another design consideration is that with each order the customer will be sending super-secret payment information to cover the cost of the bagels, which requires that the message be encrypted. We also have the issue that our clients are running on a variety of platforms, with different messaging requirements and conventions. So, while we want all the commercial clients to send their orders to the same service, the service needs to be able to route the message to the appropriate bakery without being able or needing to read the message.

Sounds difficult? Not really.

Getting SOAPy

SOAP messages, which are the types of messages we have been working with all this time, use a message layout paradigm similar to an envelope. When you send a letter through the snail-mail (do people still do this?) you would write on the envelope all the information that the Post Office needed to deliver that message to the intended recipient. The mail carrier didn’t need to open your envelope and read the letter to figure out where it needed to go.

A SOAP message is an XML document that has two “main” sections: the header and the body. The header is equivalent to the envelope you put your letter in and the body is the letter. So what does that mean to our service implementation? Consider the following topology:

This diagram represents the basic topology of our service infrastructure. Our clients will send their requests to the public service. The message then has to be routed, without actually reading the message, to either Bakery A or Bakery B. The Public Service is what’s referred to an an “intermediary service.” It’s job is to accept messages, perhaps perform some processing based on the message, and to send it along to another service, where the ultimate goal is for the message to reach it’s final destination. If, as is our case, the intermediary service simply needs to route the message to the next service then it doesn’t need to look at the body; the header should have all the information that’s needed for the service to figure out where the message needs to go. You may know this concept as WS-Addressing and is a very important standard in SOA implementations.

Back to Bagels

For our contrived example need to create a new data contract for corporate orders. Add a new class called CorporateOrder to the WebBagles project and add the fields as shown here:

This is pretty much the same order information that our WebBagles service takes in for orders now. To accommodate the commercial accounts we’ve added the SuperSecretPaymentData field as well as the DeliveryLocation field which is a customer location code number for the store we are to deliver the bagels to.

Note: We will not be encrypting the message in this demonstration. Security will be covered in a future post. For now, we will pretend that the message is encrypted.

It’s time to introduce the Data Contracts cousin; the Message Contract. Like the Data Contract, the Message Contract tells .NET how to format messages to be sent with WCF. Whereas the Data Contract defined how we want the messages body to look, the Message Contract allows us to control what fields are written to the body of the message and which are written to the header. Will use the same declarative model to let WCF know that CorporateOrder is a Message Contract. For now, we’ll just write everything to the body by decorating the fields with the MessageBodyMember attribute:

Remember, pretty much everything in WCF works on the opt-in model. This means that we must decorate ALL the fields on the class that we want to be included in the message. If we don’t decorate a field, it gets ignored.

One wrinkle we encounter when using Message Contracts as parameters for our service methods is that we must also return a Message Contract or void; no other primitive types and no Data Contracts. Let’s create a return message contract. Right click the WebBagles project and add a new class called CorporateResponse. Add the following code:

Just because we can’t directly return Data Contracts from our service method doesn’t mean we can’t return Data Contracts from our service method at all. We just need to wrap them in a Message Contract. We already have all the response information defined in BagelOrderResponse. It wouldn’t make sense to redefine it. It’s easier to simply define our message as returning an instance of BagelOrderResponse in the message body.

You can wrap as many Data Contracts in a Message Contract you want, just remember that you CAN NOT put a message contract in a Data Contract or in another Message Contract. The Message Contract MUST be at the top of the abstraction layers. And remember; there can only be one Message Contract in your message stack.

Now we need to add a new method to our service to consume this message. Open the IBagelOrderService interface and add a method called PlaceCorporateOrder so that it appears as follows:

Now, a question you may be asking yourself is “Hey, why did he use a different method name? Why not just overload PlaceOrder?” The reason is that services don’t use method names like we think of them in .NET. They use something called “Actions” which WCF abstracts away from us, so that 99% of the time we don’t need to worry about them. This is done in the interest of interoperability, and in this paradigm there is really no good, reliable way to differentiate web service methods (actions) with the same name based on the signature. Therefore we need to name every action on a web service with a unique name. There is a way we can use overridden method names in our .NET contracts while giving them unique action names, and it will be covered in a future post. For now we’ll just change the name of the method in our contract.

The next step is to implement the new method in our service class. Add the following method to the BagelOrderService class:

This is just a stub implementation that we’ll use for now, we’ll make changes in a few minutes that show how we deal with message contracts, but you can already see that we are able to access the fields on order (an instance of our Message Contract CorporateOrder) the same way we use Data Contracts. Make sure that the WebBagels project is default running project (right click the WebBagles project, select “Set As Startup Project”) and hit F5 and… you’ll get a build error:

Remember; we added a method to the BagelOrderService. Our custom BagelOrderServiceClient uses the same .NET code to define it’s methods unlike the other two proxies (right click, add service reference and SVCUTIL) which use the WSDL emitted from the service. This is easily fixed though, just implement the method in the proxy:

It’s as easy as that. Our Client doesn’t need to know that CorporateOrder is a Message Contract; WCF insulates us from that implementation detail. Now that that’s taken care of, we can hit F5 and take a look at how our Message Contract is being used. You’ll notice that our new method is listed in the WCF test client:

Will invoke this method with some test data:

And invoke the method. It returns as expected and if we take a look at the XML of the outgoing method we don’t see anything too different. The data is all in the message body, albeit in a slightly different XML wrapper as before:

The point of this demo was to get some of that data, specifically the delivery location, into the header. Let’s go back to our CorporateOrder class and make a that change. Right now Delivery Location is set as a Message Body Member. That attribute, as you can see, tells WCF to write our data to the messages body. Let’s change that attribute to Message Header:

That’s all we had to do. WCF now knows that when this message is serialized DeliveryLocation, and any other field decorated with the MessageHeader attribute should be written to the SOAP header, not the body.

Let’s change our service to look at that value and route our order accordingly. In this case we have two bakeries. If the delivery location code is even, it goes to bakery A, otherwise it goes to bakery B. Again notice that I’m simply accessing a field on the order object. I don’t have to know that it’s part of the header or do anything special to deal with that fact:

Each RouteToBakery method simply calls a method with the bagel processing logic we’ve been using, but provides a hard-coded confirmation number so we can see that the message was routed correctly:

When we run the application the input for our method doesn’t look any different; the same fields are listed and there’s no indication what goes in the header and what goes in the body:

If we supply this method with some data and call it though, we can see that our Delivery Location is now being delivered as part of the head and is no longer part of the message body:

When to Message

As you’ve seen in previous installments of this series Message Contracts are not required to create and consume WCF services. Their job is to provide a simple, easy to use way to customize your SOAP messages both for security concerns and to conform to various interoperability standards. You may also find them handy if you have an existing corporate SOA standard that you must work in. Message Contracts are powerful tools (we’ve only scratched the surface here) and like all powerful tools should be treated with respect and used when needed. Unless you have a need to define what goes in a message body and what goes in a header, you’re OK sticking with Data Contracts.

Like Service and Data Contracts, there are many more customization points in Message Contracts than we’ve explored here. They will be covered in a future post. For now, stick with the basics and you’ll be able to control how your data is sent across the wire.

Write Crappy Code

James Bender — Mon, 26 Apr 2010 15:13:57 GMT

I do a lot of work with large companies that usually have many development efforts going on simultaneously. A lot of these are maintenance projects, which are basically bug fixes or enhancements to systems that have been around awhile and have already spent a good deal of time in production. Then there are the new development efforts.

The Grass Is Always Greener

Most developers are excited about the prospect of “Green Field” development. Finally you get a chance to build a system the way you know it should be built. You’ve learned from the mistakes of your past, and are eager to put that wisdom to work. You might also be thinking that this is the perfect time to try out one of those new-fangled ORM’s you’ve been hearing about. And just think, since you’re building this from scratch you’ll be able to FINALLY build something with TDD and feel good about your code quality. In short, you’ll be able to fix all those things you complain about in the existing code base.

That’s most of us.

However, I’ve met a few individuals in my brief time on this earth who are while-knuckle, cold-sweat TERRIFIED at the idea of building something from scratch. They like the relative security of having a code base to work on. TDD?! Are you kidding? How can I write a test for something that doesn’t exist? And working with a new framework or tool? Are you out of your mind? What if I pick the wrong one? Then my application is hosed from the get go! And what if I don’t really have all the business requirements? How can I start developing if I don’t have all the requirements?!

Over Analysis == Paralysis

I met one of these poor souls recently. His way of dealing with a green field project was to go into this weird “over-analysis” mode where he tries to vet and verify every aspect of the system before writing a line of code. Beyond the idea that this spits in the face of Agile development (which everybody loves more than a basket of fluffy kittens) it causes him the thrash. In short, this guys doing A LOT of work and getting absolutely nowhere. To make matters worse, he has a deadline that is fast approaching. He’s so terrified of writing the wrong line of code, or missing a field in his database schema, or having to re-work one of his layers, or not naming one of his entity classes correctly that he’s just not doing anything. He’s afraid of writing an application that’s a piece of crap; he seems to only want to write code if it’s going to be perfect the first time he does it.

How Green Is YOUR Grass?

What this developer needs to realize is that there is no “perfect system.” Not gonna to happen. There’s always going to be something you wish you had done better or differently. Time is a great teacher. If you look at code you wrote two years ago I bet you’ll find stuff you would have done differently with the benefit of a little more time and experience. There’s nothing wrong with this.

You can’t be afraid of writing crappy code. Fact is a lot developers that I highly respect spend half their day writing crappy code, and the other half of the day refactoring. And they manage to deliver GREAT (though admittedly not perfect) applications this way. You write your code in an IDE or text editor, not on a stone tablet.You can (and should) change your code. More importantly you should be OK with changing your code. It’s good to think about what you’re going to write before you write it. But you can’t finish until you start. And you can’t start without writing something.

My advice, in this developers case, write a piece of crap.

The system is due on a specific date, which is NOT far away. His options at this point are show up to work that day with nothing, or show up with a system that’s not perfect. Heck, maybe it’s not even very good. But it’s better so show up with something than empty handed. Even something that’s not complete is something. Most managers would rather have something that needs some work than nothing at all. Have a plan for how your going to make it better, but deliver something.

And in this case, bringing some donuts to the meeting might not be a bad idea either. :)

Why Having IM at Work is Awesome

James Bender — Mon, 19 Apr 2010 19:01:29 GMT

Instant Messenger Window 1 : Manny Moe & Jack

Instant Messenger Window 2: Moe & Jack

1:58 PM Manny

i am looking into using linq to sql for the data store. Did you have experience on many to many mapping in linq2sql? It does not support that so requires hack / workaround

1:58 PM Moe

you'll just have to implement it in your repository

1:58 PM Jack

ask Moe

1:58 PM Moe

not to difficult to work around

1:59 PM Jack

i have no frame of reference

i think Moe has bandwidth this afternoon

1:58 PM Moe

i hate you

1:59 PM Moe

i've got your frame of reference right here

1:59 PM Moe

seriously?!

Working with WCF: Part One: Introduction and Your First Service

James Bender — Sat, 06 Mar 2010 12:52:14 GMT

I’ve been playing with WCF since .NET 3 came out. Sometimes I have to be reminded that not everybody is as familiar with all it’s “cob-webby corners” as I am. And that’s OK. Often (too often) I encounter someone who has NEVER used WCF and doesn’t even know where to begin.That’s not so OK.

Usually I encounter these poor souls right when they need to be able to create or deal with WCF services NOW! Since it’s generally too late for them to attend my “Getting Started with WCF” talk by this time, and I can’t always drop what I’m doing to help them, I’ll be devoting several posts to the basics of WCF. While these posts are created with the new user (no previous WCF experience) in mind, even seasoned users may get something out of these posts.

The first post will cover creating your first service. Future posts will demonstrate the various ways to consume services, custom messages, what behaviors are, transports, what channels are, REST vs. SOAP and how to create a REST service in WCF, deployment, what’s coming in .NET 4.0, some entry-level RIA service work and all sorts of other WCF goodness.

Every Journey Begins With yada yada yada…

As mentioned, this post will take you through creating your first service. In this series I will be using Visual Studio 2010 (currently using Beta 2) with the .NET 3.5. You do NOT need VS 2010 for this example, VS 2008 will work fine. At some point I will dedicate a post to what’s new in .NET 4, and having Visual Studio 2010 will be necessary if you want to follow along.

We’ll be creating a simple service and hosting it in the test WCF Server that ships with Visual Studio. In the next post we will create a console application to host our service. Hosting in IIS is a deep topic, and will be covered in a future post. Remember, when starting Visual Studio you will need to run it as an administrator. For information on how to do this, see this post by Jeff Blankenburg.

Away We Go…

In our example we are going to be building a serviced based front end for an internet-based bakery called Web Bagels.

Open the dialog in Visual Studio to create a new project. Open the C# node and select the WCF sub-node.You’ll see a list of available WCF projects. We are going to create a WCF Service Library and call it WebBagels. The resulting dialog should look something like this:

Although we are going to be doing these demos in C# you can easily accomplish the same thing in VB.NET.

Click OK and wait for Visual Studio to perform its magic. When it’s done you’ll have what appears to be a normal class library with a few files in it:

The files IService1.cs and Service1.cs are sample WCF files. Feel free to open them up and look through them if you like, but we’re not going to use them for the demo, so delete them when you’re finished. Unlike most class libraries, this one has an app.config file. We’re going to need this, so make sure you keep it around.

The next step is to create a file for our service. Create a C# class file called BagelOrderService. Your solutions should look like this:

Our First Actual WCF Stuff

The first service we’re going to create is a simple service to allow users to submit bagel orders. They’ll tell us how many dozen bagels they want and what flavor.

WCF services are simple classes; they have public methods that generally take arguments (but don’t have to), do some work and may or may not return values. The difference between WCF services and plain objects is that we must tell WCF that the methods of this class are going to be accessed externally via a channel (Http, TCP, MSMQ, etc.) that is going to send a message to the class to execute an action.

So how do we do this? Turns out with WCF it’s very easy.

The first step is to create an interface that defines our bagel ordering method:

Now I know what some of you are probably saying: “[gasp] He put the interface in the same file as the class! HERETIC!”

Relax. This is a demo. They are in the same file ~~because I am lazy~~ for the sake of clarity. In reality I would not put interfaces for WCF services in the same file as the service. That’s not to say I never put interfaces and classes in the same file, but that’s another post.

Let go ahead and implement our interface in our BagelOrderService class:

We now have a class that will take bagel orders and return an order number! OK, it’s not actually doing that much. But it’s enough to get us going. We’ll be building this service out over the course of this series.

To turn it into a WCF service we need to identify it to the .NET framework as a WCF service. This is done using the ServiceContact and OperationContract attributes:

Notice the new using statement at the top of the class. ServiceContract and OperationContract reside in the System.ServiceModel assembly. Visual Studio was kind enough to include a reference to this assembly for us when we told it we were creating WCF services. If we hadn’t we’d have had to add the reference manually.

ServiceContract identifies the interface as being an interface for a service. When you run a hosting application (one you write or IIS) the .NET runtime knows to look at this interface and build a service mechanism around it. You can set specific attributes about your service here like namespace and session mode as arguments to the ServiceContract attribute. We’ll cover this in a later post, for now the defaults will be find.

For the most part WCF operates on an “opt-in” model, meaning that just identifying a class of interface as being a WCF object (via the ServiceContact attribute) doesn’t mean that the individual methods or properties are going to be recognized and used by WCF. This can be contrasted with the .NET XML serializer which is an “opt-out” model, meaning that if you decorate a class with the Serializable attribute, all the public properties will be serialized. If you want properties to be ignored you must specify which ones to ignore.

OperationContract is the attribute we use to identify which methods in our interface we want to be exposed as actions on our service. Like ServiceContract there are a variety of attributes we can specify about the action that will be exposed on the service like action name and if the call is a one-way action.

One thing to note, you don’t have to use an interface here. You could add the ServiceContract and OperationContract to your class and things would work just fine. But don’t do this. Tieing your service implementation, or any “service based” class to a concrete implementation is never a good idea.

Actions are basically the service equivalent of methods. More on those in a later post.

It Wouldn’t Be .NET Without a Configuration File…

… and WCF is no exception.

Remember when I said we were going to hold on to that app.config file? Good, because now is when we need it. Open it in Visual Studio. It should look something like this:

There is A LOT of stuff to cover in this file. Today we’re just going to worry about the bare necessities to the our service up and running. The first step is to make sure this configuration file is actually using our service. Find this line in the configuration file:

This is the node in our configuration that tells WCF which concrete implementation of our service we are going to be using. In our case it’s the BagelOrderService class. Change this line to look like this:

We’re almost done! All that’s left is to let WCF know where our service contact is. That’s done by change the contact attribute of our endpoint. The endpoint for our service should like something like this:

We just need to change the contact attribute to point to our service contract:

We’re ready to test!

Let’s Light This Candle

Our WCF class library is a little different than an traditional Visual Studio class library. Normally when you try to debug a class library in Visual Studio you’re given a “gentle reminder” that you can’t actually run libraries. Our WCF library is special though. In order to ease development and testing of WCF services Microsoft has included a small testing service host (think of it as Cassini for services) and a test client. Press F5 in Visual Studio to start debugging. Your solution will compile and Visual Studio will start the test host for you:

This may take a few moment, especially the first time you run the service. Once the service is up and running you’ll be presented with the WCF test client:

On the left side we have a tree view which represents our service. Currently we only have one method (PlaceOrder) in our service, so we only have the one node under our interface. Double click on that node and the right section of the window should present you with a data entry screen to test our service with:

Let’s try it go head and enter some data in the “Value” fields for both arguments and press the Invoke button. It may take several seconds the first time, but you should see a result similar to this:

There are a few more goodies hidden in this test client which we’ll explore in a future post.

Congratulations, you just created a WCF service!

In the next post I’ll explain more about the configuration file and show you how to create a console application to host your new service.

Code on!

Make your investment count

James Bender — Sun, 02 Aug 2009 14:05:05 GMT

I recently had a conversation with a friend and fellow developer who was very excited. His company recently welcomed a new CIO to the organization, who had some, comparatively, progressive idea. One of his first actions was to increase IT development spending by several million dollars to tackle some projects that had had to be put off over the past few years, including renovating several applications that we’re quite performing up to expectations.

Unfortunately, while the CIO’s spirit was in the right place it became clear that his money was not.

The various development groups began developing applications the way they had always done, but made no effort to update their tools, techniques or practices. Instead of spending part of their substantial investment to introduce things like Agile methodologies, Test Driven Development, Web Standards, Source Control policies or automated builds, they proceeded to develop a whole new collection of applications like they had been developing them for years.

The group knew that these old practices had led them to a lot of pain in the past and needed to be revamped. But the organization placed value on raw lines of code and not the quality of what was being produced. As a result, those applications that needed “renovation” were simply ported from .NET 2.0 (and in some cases 1.1) to 3.5. Management was surprised when “upgrading” these applications did not result in large performance and stability increases.

Making a lot of changes to the way we work as developers can be scary. There’s a lot to learn, it seems complicated at the start, and no one wants to risk looking stupid. But it’s also important for us as individuals and software development in general to be willing to examine and investigate new techniques and tools that will make it easier to develop higher-quality code more efficiently. Keeping an open mind will unlock a lot of doors to improvement.

Companies need to understand that their code is an asset just like a building, vehicle fleet or piece of manufacturing equipment. You wouldn’t dream of letting those things fall into disrepair, so why are companies OK with their code base rot? When making an investment in IT, it’s important to understand where that money is going, and what it’s going to buy you in the long run. If you have a code base of dubious quality and pay for large teams to simply “plough ahead” you will just end up with a larger base of low quality code.

2009 Columbus Give Camp is in the books…

James Bender — Tue, 21 Jul 2009 18:50:54 GMT

… and it was a tremendous experience!

The goal of a Give Camp is to unite non-profits that need technical assistance, be it a new web site, help with a CRM or making changes to an existing line of business application with passionate geeks in the area who are willing to give a weekend to help these non-profits accomplish their goals.

This year, in Columbus, about 45 software professionals came together to help eight non-profits. The results were amazing. In about 48 hours, eight full scale applications were either completed, or nearly completed. Most starting from scratch. It was great to see the variety of technologies and talents in one place and one time. It was also great to see the results a small but committed team of developers could create in a short period of time. Truly amazing! I want to thank all the volunteers who came out to help. A weekend can be a big thing to give up, and the Give Camp organizers and non-profits are extremely thankful of your efforts.

I would also like to thank all the non-profits that participated. We had a great time getting together and learning from each other while helping you.

I would also like to thank our sponsors. Quick Solutions for providing us with a great workspace, and soda and coffee through the weekend. Discount ASP.NET for providing hosting for the non-profit applications. Tech Smith for providing funds and licenses of their amazing products. Telerik provided us with licenses for some of their products and swag. Microsoft for providing funds and swag. eRubycon for providing a free pass to eRubycon 2009. And The Sophic Group for sponsoring dinner on Saturday night. Please remember the support these sponsors provided.

I would like to single out two sponsors who went above and beyond for us: Potbelly and Pei Wei. One of the most difficult things about organizing an event that lasts all day is feeding people. When that even spans multiple days AND encourages participants to stay over-night, that task is even harder. Potbelly and Pei Wei made some of those meals a whole lot easier for us! Please remember them if you’re in the Polaris area at lunch or dinner time (Potbelly is here, Pei Wei is here)

See you all at Give Camp 2010!