WCF

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!

Working with WCF Part Seven - What's the deal with REST?

James Bender — Thu, 15 Jul 2010 14:49:31 GMT

Previous posts in this series:

We’re gonna step out of the whole Web Bagels/WCF demo thing on this post so I can give you a brief primer on Representational State Transfer (REST).

The good news is that if you are reading this blog then you have used REST. The reason is that REST is the architectural basis for the Internet. When you opened your web browser of choice and typed www.jamescbender.com into the address bar and hit ENTER, the browser issued a request to the access resource located at www.jamescbender.com (whatever that may be) using the REST GET verb. In fact, if you’ve ever navigated to any website you’ve seen REST in action. That’s the basis of REST; clients make requests to servers using a Uniform Resource Identifier (URI) which, depending on which REST verb was used in the request, returns, created, alters or deletes the resource at the location specified by the URI. It’s that simple.

URI’s and You

There are two components of a REST request; the URI and the verb.

The URI is probably the easiest for most people to get their heads around. It’s the location of the resource on the Internet that we want to get/change/delete. We’ve all used websites before, and we generally access them by a URL. You can think of a REST services URI as it’s location. But there is a bit more to it than that. Consider the following list of URI:

www.GloboCorp.com/Departments

www.GloboCorp.com/Departments/Sales

www.GloboCorp.com/Departments/Sales/Employees/JohnDoe

www.GloboCopr.com/Departments/Sales/Employees/search?name=JohnDoe

The first thing to notice about all of these is that they are human readable. You may know nothing about Globo Corp., but you know that it has departments, one of those departments is Sales and it has an employee named John Doe. A big part of our ability to understand that is the hierarchy that the information is presented in. When creating URI’s for REST services it’s important to think about how you want your information to be accessed and conceptualized. In this case it makes sense to have the list of Departments as one of the “top level” branches in the hierarchy. For another company it may make sense to have Employees be the top level. It all depends on what your data is like and how you want it presented.

Another thing to note is the “Universal” aspect of the URI. These are simply locations on the Internet. There is no special decoder ring needed to access these; any application that can use HTTP, and can handle the content type of the response (text, a picture, a sound file, etc.), can use the resources located at these addresses. You could embed these URI’s in a document and anyone reading that document, assuming they had some sort of HTTP capable web browser and access to the Internet could get the resource that resides at that location.

Finally, since these are simply URI’s, and there is nothing special about them, they can be cached like any other URI. This is a big advantage over the SOAP based services we’ve been using up till now. Since there’s a certain amount of “magic” that happens when a SOAP service is invoked caching is difficult, usually involving some sort of customization on the host. Since REST is URI based most web servers provide the ability to cache right out of the box.

VERB – That’s what’s happening.

Once we have our resource location we need to specify what we want to do with the resource. These is where the HTTP Request Method, a.k.a. the REST verb come into play. There are a variety of REST verbs available. The four are the most commonly used and you will use in your everyday like are the following:

Get – returns the resource at the URI’s location
Post – creates a resource at the URI’s location
Put – alters the resource at the URI’s location
Delete – delete the resource at the URI’s location

In addition to these four, you may start to encounter the HEAD verb as more service providers have begun implementing it. HEAD returns metadata about the resource at the location that you would get if you sent a Get verb.

The benefit of the verb paradigm in REST is that we have a standardized interface. Unlike SOAP based services we aren’t creating our own verbs like GetEmployee or CreateSale. Being able to understand the information hierarchy behind our URI’s and having a standard list of methods (verbs) we can use on those resources makes developing clients that use REST services much easier and more intuitive.

POX and JSON

So now we know how to request resources from REST based web services. But what are we getting back. In the Web Bagels example we’ve been using SOAP based web services, which in fact return SOAP messages. REST doesn’t use SOAP. So what are our options?

POX

One option for our response is Plain Ol’ XML (POX). Like SOAP, our data comes back as an XML stream, That’s really where the similarity ends. Unlike SOAP, POX is very small, terse and easy to read. For example, consider this SOAP message:

Now check out the exact same message in it’s POX version:

Wow! Three things were accomplished here. First, and most strikingly it’s a MUCH smaller message. As a result it’s become much more human-friendly. Additionally we’ve trimmed a lot of the complexity that comes with SOAP out of the process. We do need to keep in mind that the simplicity comes at a cost; when we removed the SOAPyness from our message we lost some security as well as some other WS-* abilities like addressing, routing, reliability and anything involving workflow. More on that in a bit. But what we do have is a simple XML document that can be easily understood, parsed and acted upon.

JSON

I’ve you’ve been doing “Web 2.0” stuff you’ve no doubt heard of Asynchronous JavaScript and XML, better known as AJAX. AJAX is all the rage with web developers who want to provide a good user experience on the web by making several “smaller” calls to a back-end web service and using that result to change part of the page instead of doing a full page refresh. These keeps the user from having to sit and wait for the whole page to be re-served and re-rendered when only a small part of the page is changing. Most of these calls are coming from client side JavaScript and in the “dark ages” you would get back an XML document that you would have to parse before you can use.

JavaScript Object Notation or JSON was defined in 2001, but didn’t really gain steam till 2005 when large web properties like Yahoo, Google and Microsoft embraced it. The idea was that since we’re already using JavaScript to make these calls, and JavaScript is a dynamic scripting language, why not just return the text that corresponds to a JavaScript object? This made life a lot easier for the client developers, and once libraries to quickly format messages for JSON it made life just as easy for service developers too. An example of the JSON equivalent of the previous message would look something like this:

As you can see JSON shares a lot of characteristics of POX; both are simple, compact and human readable. It’s also instantly consumable by JavaScript so there’s no need to parse it, pull it apart and put it in an object; it’s already in one. Once you get this back from your service you can use it like any other object in your client side JavaScript.

What of SOAP?

The resurgence of REST does not mean the death of SOAP. Yes, SOAP is complex. But that complexity brings power. For the Enterprise, SOAP is not going away. There are still too many things that business cares about that are easier to do in SOAP than with REST-based services. Things like transactions, reliable messaging, workflows and orchestrations, message routing and custom security. SOAP excels at these and that is why you need to know (and care) about it.

What is changing is how you architect and plan your service infrastructure. Specifically where you use SOAP/REST based services. Personally, I’ll start from the standpoint of making something a REST service until a requirement arises that can be more quickly, easily and reliably done with SOAP. Then I’ll switch to SOAP. An emerging pattern many have seen that follows this line of thinking is that we are starting to see REST services deployed along the edges of a service architecture, in places where outside client need to have easy and interoperable access to our data. While SOAP services are still very much relied on in the center of the service architecture, where things like sessions, long running workflows, more advanced security and services busses are needed. Of course the standard Architect mantra of “It depends” comes into play.

Next time we’ll use WCF to add some REST-based services to our Web Bagels application.

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.

Working with WCF: Part Three – Connecting To Your Service With A Client pt. 2

James Bender — Fri, 23 Apr 2010 13:46:08 GMT

Previous posts in this series:

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

Working with WCF: Part Two – Your First Host and A Bit About Configuration

Working with WCF: Part Three – Connecting To Your Service With A Client pt. 1

In my previous post in this series I outlined two of the three most common ways to create proxies for WCF services. The first technique as was to use the “Add Service Reference…” functionality in Visual Studio. The second was to use the command line tool SVCUTIL to generate a proxy class and configuration file that you then add to your project. The last technique is to hand roll your own proxy.

Don’t Panic!

It’s not as difficult as it sounds.

Let’s start with adding a new console application to our solution called WebBagles.Client.Custom. Your solution should look like this:

Add references to the .NET assembly System.ServiceModel and to the WebBagels project (the one with your service contract in it) Now add a new C# class called proxy.cs. Change the name of the class from proxy to BagelOrderServiceClient, and have it inherit from ClientBase<IBagelOrderService> and IBagelOrderService. Let Visual Studio/Resharper/elvin magic/whatever create the stub methods for your IBagelOrderService interface. When that’s all done,the contents of your proxy.cs file should look like this:

You don’t have to change the name of your cs file to proxy.cs. I did this to make it the same as the other projects. It’s just a cs file, you can name it whatever you want.

This should look pretty familiar. Much like our service implementation we’ve simply implemented the service contract interface. we’ll use a method from the ClientBase base class to do our heavy lifting:

Our base class has a property called Channel, which provides us direct access to the communications channel between the client and the service. A channel is made up of things like encoders, security protocols, wire transfer protocols, etc. Right now all you need to worry about is that calling the corresponding method on the Channel will invoke the communications stack and call the method on the service.

Our client code should look familiar if you read the last post…

So now we have a proxy and the client code to invoke it. It complies, so CLEARLY we are done! Ship it!

Well… let’s just try to run it once to be sure…

Oh yeah, the configuration file. Guess we need to deal with that.

Configuration the Easy(er) Way

For the most part we’ve had the files provided for us; Add Service Reference and SVCUTIL both created our app.config files and as you’ll recall and we *ahem* borrowed the config for our service.

With this approach we’re not so lucky; we’ll need to do it ourselves.Go ahead and add an app.config file to the WebBagles.Client.Custom project.

The good news here is that we don’t have to write all that ugly XML by hand. Instead we’ll be employing the WCF configuration editor. Right click on the app config file in the WebBages.Client.Custom project and select Edit WCF Configuration:

This will open the WCF configuration editor with the app.config file already loaded:

From this tool you can pretty much do any WCF configuration task you may need. We’ll use this to create our client endpoint.

In the configuration tree view on the left click on the Client node:

You may or may not have an SB endpoint already listed here. The SB endpoint seems to be some sort of remnant for a .NET-based SDK. It doesn’t do anything and wont cause any problems, so just ignore it.

Besides, we’re here to create our own endpoint. So lets do just that. Click on the “Create a New Client…” link to open the “New Client Element Wizard:

And here we make a choice. If you have the app.config file from the service you are consuming you can just point this tool at it and it will figure out everything for you. It’s like magic. And, if you have that configuration file, it’s the best way to go. But it would also make for a pretty short demo, so we’re gonna pretend that we don’t have that file and select “Manually” to create our own endpoint from scratch. Select the Manually radio button and click Next:

We’ll need to specify the contract of the service we want to consume. This, for review, tells us what methods are available on the service and how they are called. Hit the Browse button and you’ll see something similar to the standard file open dialog:

In this case we are going to be looking for the assembly with our service contract in it. In this case it will be in the bin/Deabug folder:

Double click on the WebBagels.dll and you’ll see something a little different:

We’re actually looking for a service contract; not an assembly. Double clicking on the assembly with our contract in it caused the wizard to open the assembly and find all service contracts in it. In our case we only have the one. Select it and click the Open button.

Now that we have our contract selected, it’s time to move on to the next step. Click the Next button.

We need to select our binding, and we’ll do it here. We have the full variety of bindings that ship with WCF available to us here. We’ve been using HTTP all this time, and right now we only have an HTTP endpoint on our service, so we’ll stick with that. Select HTTP (if it’s not already selected) and click Next

There are several types of HTTP bindings available. Selecting Basic Web Services Interoperability translates to the basicHttpBinding, which is sort of the “legacy” binding. It’s primarily for service that are VERY old and don’t support the WS-* standards or pre-date the WS-I 1.1 Basic Profile. We’ll stick with Advanced Web Services interoperability. Select that, make sure Simplex communication is selected and click the Next button.

Finally we get around to providing the address for our service! If you forgot this you can copy it from the host applications app.config file. Simply paste it in and click Next

There are situations were you will need to specify multiple endpoints for your client. In this case you’ll need to name your endpoints and when you new-up your proxy provide it with the name of the endpoint you want it to use. We only have the one endpoint, so leave the Name field as is and click the Next button:

Here is the summary of choices we’ve made. Note the binding. All along we’ve been using the wsHttpBinding. But the configuration editor has selected the ws2007HttpBinding for us. The ws2007HttpBinding is an implementation of the Organization for the Advancement of Structured Information Standards (OASIS) standards for http bindings. This mainly focuses around the implementation of reliable services. For now you just need to be aware that is it NOT compatible with the wsHttpBinding used by our service host. We need to change it.

Click the Finish button and you’ll see that our new endpoint as been added to the client configuration:

Click on the endpoints name (in this case it’s empty) and it will show you the endpoint details. You’ll see that true to it’s word the configuration tool as set our binding to the ws2007HttpBinding:

Changing this is easy. Just click on the drop down arrow next to the binding name and you’ll see a list of available bindings. Select wsHttpBinding. Your endpoint should look like this:

Select File | Save from the menu. DON’T forget this step or you’ll have to do this process all over again. Close the configuration tool and go back to Visual Studio. Visual Studio will alert you that one of your open files has changed, tell it that everything is OK by clicking Yes.Your clients app.config file should look similar to this:

All that’s left is to test it. Start the host application and when it’s ready to start accepting requests start the WebBagles.Client.Custom application. It should call the service and display the result as you can see here:

In answer to the question you’re asking yourself now, yes: you can use this WCF configuration manager to create host-side service information to, and we’ll do this in a future post.

These last two posts covered a lot of content Congrats if you made it all the way through both of them! Next time we start look at WCF contracts.

Code on!

Working with WCF: Part Three – Connecting To Your Service With A Client pt. 1

James Bender — Fri, 02 Apr 2010 13:07:26 GMT

Previous posts in this series:

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

Working with WCF: Part Two – Your First Host and A Bit About Configuration

We’ve got a service. We’ve got a host. But that’s all pointless without someone to use it.

A Tale of Three Clients

As with almost everything in WCF, you have several options about how you want to consume your service before you even start to talk about things like transport or security. As expected there are benefits and draw backs to each of the approaches. We’ll take a look at two of them in the post. In the next post we’ll take a look at the third method and take a quick lap around the WCF configuration editor.

Looking behind the curtain, all three of these approaches have the same plumbing and parts; we are creating a proxy class to represent our service. The proxy abstracts all the mechanics of communicating with the service over the wire so we don’t have to worry about that. This proxy will rely on configuration of some sort. Normally this can be done with a *.config file of some sort (as we did in the last installment) although it is possible to configure services and clients with code. We’ll take a look at this at another time. Finally, if your service relies on any complex types, these will need to be defined on the client side as well. I’ll demonstrate this in an upcoming post where I explain Data and Message Contracts.

Away we go!

The Easy

The easiest way to consume a WCF service from a .NET project is to add it as a service reference. To do this we are going to add a console application to our solutions called WebBagles.Client.Easy. Your project should have three projects now:

The idea behind this approach is that services are analogous to assemblies; you should be able to reference them and use their types. Adding a service proxy in this way is almost as easy as adding an assembly reference. Right click on the WebBagels.Client.Easy project and select “Add Service Reference…”

This will open the “Add Service Reference” dialog:

The first thing we need to supply is the address of our service or at least the server it’s on. If we know that we can simply type/paste it into the Address text box and hit the Go button. Visual Studio will go out to that address and download the WSDL for the service at that address and show us a list of what’s available.

If the service is in our solution, we can click the Discover button and Visual Studio will find all the services in our solution and list them for us. Go ahead and click the Discover button now:

The first time you run this it may take several moments to complete. As you can see Visual Studio has found our bagel order service. I’ve gone ahead and expanded the Services node so that we can see that the endpoint that was found supports our IBagelOrderService service contract with our PlaceOrder operation.

Before we click OK to have Visual Studio create the proxy for us lets change the namespace to something a little more developer friendly:

That’s better! Click the OK button and let Visual Studio do it’s magic. When the dust settles you should have a new service proxy, complete with a configuration file, as part of your client application:

All that’s left is for us to write the client to call the service! Open the Program.cs file in the WebBagels.Client.Easy project. Add the following code to the Main method:

Aside from the calls to the Console class to do our screen output, we’re just creating an instance of the proxy class we generated then calling the method on it that corresponds to our service method (PlaceOrder). In this case, we don’t technically need the close since the connection to the service will be closed when the proxy object is disposed, but it’s a good habit to get into. A lot of scaling issues in WCF have been solved by finding an unclosed connection and closing it.

Let’s try it! Hit F5 to start the service host:

Now that the service is started we can start the client. In the Solution Explorer, right click on the WebBagels.Client.Easy project and under the Debug menu select Start New Instance. Our client should make a call to our service and display the result:

Simple Is Simple For A Reason

If you need to get a simple WCF client working to call a service this is a good way to do it. The simplicity does cost though. The big one being that you can’t generate proxies as part of your build process. Also, while you can create proxies that will work in most common scenarios, you lose the ability to do some “enterprisy” things, like combine data types, import of a WSDL document, specify framework version and a bunch of other things I’ll cover in my “Stupid Client Tricks” post. For now, know that for 90% of what you are doing, the simple way is a good way to go.

The Command Line

If you want to do any complex proxy generation or make the creation of the proxy a step in the build process, then you’ll want to use the .NET command line utility SVCUTIL to generate your proxy. While “Add Service Reference” is centered around simple creation of a proxy and configuration, SVCUTIL allows some other more advanced functionality for things like combining common types from difference services, managing service namespaces and importing/exporting WSDL. Today we’re just going to use it to make a proxy.

Create a new console application project called WebBagels.Client.SVCUTIL. Your solution should like something like this:

Next fire up the Visual Studio command prompt. You specifically want this VS one as it will already have the location of SVCUTIL in the path. SVCUTIL will go out to your service to download the WSDL, so you’ll want to make sure your service is running. Right click on the WebBagels.Host project, and select Debug | Start New Instance. You’ll need the location of the service for SVCUTIL to download from, so copy the address of your service out of the hosts config file.

Once you’ve done all that, go to the command window you’ve opened and change directory till you get to the directory for the WebBagels.Client.SVCTUIL project.

OK, we’re FINALLY ready to generate our proxy!

Enter the following command into the command line. Don’t press enter yet!

Pretty, huh?

SVCUTIL has a ton of switches to customize how it works. The three you see here are the ones you’ll use most of the time. The “/out” switch allows you to specify the name of your proxy code file. In this case it will create a file called proxy.cs. If you leave this it will try to derive a name based on the service you are targeting. This can get ugly. It can also change if the people developing the service change the WSDL in certain ways. So I just get in the habit of always setting it. The “/l” switch is shorthand for “/language” and tells SVCUTIL (in this case) to create our proxy as a C# file, which is the default if you don’t specify. You can have it generate VB by using (you guessed it!) VB as your parameter. Finally, the “/config” switch tells SVCUTIL what to call the configuration file. Some developers like to keep their service configurations in separate files, and this makes it easy.

OK, hit the Enter key!

SVCUTIL will fire up, download the WSDL from your service (you remembered to start it, right?) and create your proxy and configuration files. The result should look something like this:

Go ahead and close the command window, shut down your service host and go back to Visual Studio.

Unlike “Add Service Reference” this process did not add a reference to System.ServiceModel to our client application. Go ahead and do that now.

Almost there. Right click on the WebBagels.Client.SVCUTIL project and select “Add | Existing Item… “ from the menu. Visual Studio will open the file dialog, and it should already be pointed to your project directory. Change the file type to “All files” and select the proxy.cs file and the app.config file:

Click the Add button. The files should be added to your project:

FINALLY we get to write some code! Open up the Program.cs file.

Even though we used a different process to create the proxy the procedure to call it is pretty much the same; we create an instance of the proxy object and call the methods on it:

You’ll notice that the name of the client class is different. Without telling it otherwise, SVCUTIL will take the name of the service and append “Client” to create the proxy class. This will be fine 99% of the time. If you’re ever in doubt about what SVCUTIL ended up naming your proxy class, don’t be afraid to crack up the proxy.cs class and take a look. It’s just C# code after all.

Let’s test it out. Using the same procedure above, start the service and once that’s humming along, fire up the WebBagels.Client.SVCUTIL project:

And there you go!

Until next time…

We covered a lot in this post. If you stuck it through to the end good for you! In the next post I’ll show you yet one more (and some would say the best) way of creating a WCF proxy and show you an easy way to edit those nasty configuration files.

See you then!

Working with WCF: Part Two – Your First Host and A Bit About Configuration

James Bender — Wed, 17 Mar 2010 14:13:07 GMT

Previous posts in this series:

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

So now you have a service, congratulations! What are you going to do with it?

Be A Good Host

Some people like to say of WCF that you have “… a multitude of hosting options” but in reality you have two; host it in IIS or create your own host.

IIS has a lot going for it. Odds are if you are in a .NET shop you are already using it and have people on staff who know how to manage it. It has facilities to handle scaling, memory management and process cycling. IIS makes managing services relatively easy.

One thing to note here is that if you are using IIS 6 you can ONLY host HTTP based endpoints for your service (more on endpoints below). That means no TCP, Named Pipes or MSMQ for you! IIS 7 ships with Windows Activation Services (WAS) which allows you to host all types of endpoints in your IIS installation. If you’re one of the lucky ones that has access to IIS 7 with WAS, I say use it!

IIS deployment can be a bit tricky (especially with WAS), so I’m going to cover that in it’s own dedicated post in the future.

Self-hosting is the umbrella the “multitude people” use to cover the “multitude of ways” you can host WCF You can host WCF services in a console application, a Windows service, a Windows application, etc. But they all come down to the same thing; writing your own custom host for WCF. In the days of ASMX, if you wanted to self-host you'd have to, well… you'd have to write IIS. Which sounds hard, and provides little benefit since someone already wrote IIS! You could write customized HTTP modules to inject some of your own functionality, but the pain level for that is rather high.

I’m Already Out of Dumb “Host” Puns, So Let’s Just Write Some Code

Don’t worry, this is gonna be a breeze

When we last left our WebBagels solution, it looked something like this:

In this example we’re going to host this service in a console application, but the same approach can be used for Windows services or Windows applications. The first step is to add a console application called WebBagels.Host to our solution:

WCF allows you to write your own hosting logic by exposing a class called ServiceHost which is in the System.ServiceModel assembly/namespace. You’ll need to add a reference to System.ServiceModel to webBagles.Host. At a minimum all you have to do is tell it what kind of service class you want to host and and then call Open:

On line 12 you can see the declaration of our service host, which is going to do all of our heavy lifting. In order to create this class we have to pass it the type where our service implementation exists, in this case BagelOrderService. Our contract is IBagelOrderService, and BagelOrderService is but one possible implementation of this contract. We could have several implementations of our service available, and if need be our hosting logic could determine which particular implementation it wants to host at start up. A good, almost everyday example of this would be testing. You may have a production implementation that uses actual production resources, and a “stub” test version that just responds as if it was doing something.

The rest of this Console App 101; we open our service, tell the user we’re ready and wait for them to press a key, at which point we shut everything down.

Some example of this you’ll see will create the service host in a using block:

I don’t like to do that. Yes, this is easier, but the problem is the Dispose method on ServiceHost (I know, it doesn’t show up, but trust me it’s there) attempts to close the host. The but what if the exception is thrown during open? In this case close is going to create it’s own exceptions (in this case an InvalidOperationException and a CommunicationObjectFaultedException) and we’ll never know why the initial open failed. Wrapping our hosting logic in a try/catch/finally block give us the opportunity to see what really is happening.

Great, we’re done! Let’s fire ‘er up! Change your solution setting to make WebBagels.Host the startup project and hit F5

Uh oh!

[sigh] Well, we avoided it as long as we could, but like most things in .NET, WCF requires configuration.

Creating the Service Configuration

Go ahead and add an app.config file to your WebBagels.Host application.Initially, it should look something like this:

All of the configuration for WCF, both clients and services goes in the system.ServiceModel node. Instead of doing a bunch of typing to create all this, we’re going to copy the config file that Visual Studio created for us when it made our service library project. Open that app.config file and copy the system.ServiceModel node, and everything in it, to the app.config you created for your console hosting application, careful to place it IN the configuration element. You’re file should look something like this (note: the part that we are adding is boxed in red and I have removed the comments to make the file a little easier to read):

Let’s look at this file in a little more detail:

The Services Node

The services node contains service nodes, which in turn contain all the information WCF needs to host your service. Since you can host multiple services in a hosting application (by creating multiple instance of ServiceHost) your configuration file can have multiple service nodes in your services nodes:

The service node has a couple attributes that are important. The name attribute identifies the concrete implementation of our service, in this case the BagelOrderService class that implemnts our service contract in IBagelOrderService. That’s the value ServiceHost is going to use to find which section of the configuration file it’s going to use, so it needs to be the fully qualified class name of your service implementation.

The behaviorConfiguration attribute identifies a section of the configuration file that will contain information about what behaviors our service will use. I’ll cover behaviors later in this post.

Within our service node we have a few sections. The first is the host section:

This node holds some configuration information that is applied to all endpoints for your service. Right now we are using it to specify a base address, which will be pre-pended to the address we will define in our service endpoints. You can have base addresses for each type of transport. TCP base addresses begin with “net.tcp.” MSMS address begin with “net.msmq” and so on. You can only have one base address for each transport type AND if your transports communicate over a port, the port numbers, even across transports MUST be unique (more on that below).

Speaking of endpoints:

Our service has two endpoints; the service endpoint which clients use to invoke the service, and a metadata endpoint that returns a WSDL (Web Service Definition Language) document which in turn allows clients to discover and learn about the capabilities and requirements of the service.These, like all endpoints, boil down to three things. The ABC of the endpoint; Address, Binding and Contract.

The Address is the location of the service. It’s basically a URI that allows clients to locate the service on a network and invoke it’s actions or acquire it’s metadata. You can see that the address for our service is, uh, empty. But, if you remember, we defined a base address in the host section of our service. The WCF runtime will take the base address and append whatever address we put in the endpoint to it to create a complete address. In this case the address to invoke our service is the base address because we have left the address in our service endpoint blank. The address to access the WSDL document would be the base address plus “mex” (base address plus the value of the endpoints address attribute) This does NOT mean that you can just omit the address attribute. WCF doesn’t like that. So, you know, don’t do it. It’s also important to remember that addresses must be unique. You don’t like it when your mail gets delivered to your neighbors house. WCF REALLY doesn’t like it!

The Binding is the way the service communicates with the client. The fancy-pants way to describe this is as a “channel stack” which involves a lot of stuff we’ll cover in a later post. For now if someone says “channel stack” just remember that they are talking about the binding. The out-of-the box bindings that come with WCF in .NET 3/3.5 fall into a few families; HTTP, TCP, MSMQ and Named Pipes. Each of these have specialized sub-types for things like pier-to-pier and service bus communications. We’ll cover the which of these to use when in a later post. But for now since HTTP is probably the most widely interoperable transport in that list, we’ll stick with that. In fact, when in doubt you’ll want to use the wsHttpBinding that we are using here. In this case, the “ws” means that the binding supports the most common WS-* protocols. For all the SOAP geeks out there, it specifically implements WS-I 1.1 Basic Profile.

The Contract is the service contract that our service implements. In this case its the IBagelOrderService interface we created in part one. 99% of the time, this is a no-brainer; you have a service implementation that implements the service contract. In some cases you may want to have a couple different contracts for the same implementation. This allows you to segment your service and only expose certain methods on certain contracts, and other methods on other contracts. This works because although a service implementation may have methods of A, B and C, the contract may only define A and B. In this case clients using that endpoint would not be able to invoke C since it’s not part of the contract that endpoint supports.

The identity element deals with security, which we’re not using right now and will cover in a future post. You could leave it or take it out, the service (right now) will work the same either way.

The last section deals with behaviors:

Behaviors is a deep topic that we’ll discuss in a later post. For now, we’ll just focus on what we’re doing here.

As you’ll recall our service node had an attribute called "behaviorConfiguration” which had a value of “WebBagels.Service1Behavior.” This is the section of the configuration file that that attribute points to. In this case we’re telling the service to allow HTTP Get requests to get the services WSDL document. If you do not wish to make your WSDL public, simply set this value to false and comment out the metadata endpoint. We are also not including exception details when the service throws and exception. If you’ve done ANY ASP.NET development work, this concept should be very familiar; instead of throwing the actual exception information down to the client, a “sanitized” message is returned which hides ~~your shame~~ any information that could compromise the security of your application.

OK, let’s try it again…

Well, we’re getting closer…

One At A Time Please

Even though we may have set the solution to treat our host as the startup project, I bet you saw something like this when you hit F5:

Yep, thought so.

The addresses in WCF endpoints are made up of a path that includes the machine name and a port number. If you’ll recall when we copied the configuration file from the WCF service library, we didn’t change anything. So, when our host AND the WcfSvcHost both ran they tried to grab the same port. And when it comes to ports, there can be only one listener at a time.

There are two ways to fix this. The easiest is to simply change the port number of the address in one of the configuration files. Quick and easy, but then you have two instances of your service running. And this could cause some “confusing” results if you need to debug the service. Mostly because YOU WILL forget to make the corresponding change to one of your clients, which will continue to hit the “other” host. Happens all the time. At any rate, if you don’t need to have a second instance running, why run it?

In the Solution Explorer, right click on the WCF service library project and select “Properties.” When the properties page for the project comes up, you should see a tab at the bottom labeled “WCF Options.” You should see a page that looks something like this:

Turns out that one little checkbox is what’s causing all of our problems. Uncheck it, recompile and hit F5:

Success!

To verify that the service is actually running, we can navigate to the endpoint we defined in our app.config file. We should see the information page for our service:

Great! Now we have our very own hosted WCF service! Now we just need to,learn how to use it. In the next installment we’ll talk about consuming services on the client side.

Code on!

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!

Getting Started with WCF Slides and Code Sample from CINNUG

James Bender — Thu, 03 Sep 2009 12:17:50 GMT

Better late than never…

Seriously, sorry to everyone who’s been waiting for these.

I had a great time speaking in Cincinnati last week and meet a lot of great people. I hope to see you all again soon.

Exceptions Happen, Part 1

James Bender — Tue, 11 Aug 2009 19:11:20 GMT

You might thing you’re special, but your not. And sooner or later it’s gonna happen to you too. Your WCF Service is going to encounter a *gasp* Exception. Do you know what to do when it does happen?

Scott Hanselman wrote a terriffic blog post on exceptions. It’s a great place to start and if you haven’t read it you should. I wrote a post last year about working with the WCF Fault Contract. But there’s more than one way to skin this cat. What I’m going to be focusing on in this series of posts are the ways you can deal with exceptions in WCF and how to communicate what’s happened to your client.

In the first installment we’re going to look at how exceptions get received by a WCF client and how the WCF channel reacts to exceptions. Let’s 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:      }

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:  }

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

Like ASP.NET, 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.

   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.

Code on!