WCF

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

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

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!

I’m Following Rod Paddock at Codestock?!

James Bender — Thu, 25 Jun 2009 03:46:07 GMT

Codestock is this weekend in Knoxville. You can check out the agenda page here and see that there are some great, very smart people speaking there. With seven tracks over two days, plus open spaces, there’s something for everyone at this great event. I was honored to speak at the first Codestock event last year, and I’m thrilled to be back!

I’ll be presenting “How to make your application awesome with JSON, REST and WCF” in which I’ll explain why REST is the “new” hotness (turns out it’s not that new) and how to take advantage of it with WCF. You’ll also get to see some cool JQuery and ASP.NET MVC stuff as part of the talk. It’s the first time I’ve given this talk, so I’m very excited!

Turns out I’m following Rod Paddock. Yeah, that Rod Paddock. Editor in Chief of CoDe Magazine, author of many books, international speaker and Microsoft MVP. By contrast, I was all excited this morning because I found a $5.00 bill in my pocket that I forgot I had.

Ron Paddock followed by James Bender. Kinda like…

	followed by
	followed by
	followed by

In all seriousness, I’m really looking forward and VERY happy to be speaking at Codestock. It’s a must-attend event and if you’re not going, well, you should go!

Indy Code Camp Recap

James Bender — Sun, 17 May 2009 02:57:59 GMT

Thanks to everyone who attended my talk on custom WCF behaviors at the Indy Code Camp. I hope you all found the topic interesting and the content useful.

You can get the slides and code samples here:

For those who might be interested, I’ll be presenting an Intro to WCF talk at Cincinnati .NET Users Group in the future. More information will be posted here in the future.

What’s At the Center of A Tootsie Pop – Why Developers Need to Know WCF

James Bender — Tue, 07 Apr 2009 19:04:39 GMT

This past Saturday I took part in the West Michigan .NET University. In addition to the .NET Bootcamp I did with Len, I presented on Web Service concepts and WCF. At the end of the WCF session I was asked if Microsoft was really committed to WCF or if something else will be replacing it in a few years.

I believe the answer is that Microsoft is committed to WCF.

If you look at all of the recent cloud-based offerings by Microsoft you can see it’s commitment to WCF in the API’s. These new platforms and services all communicate via services. An Azure application uses WCF services to communicate between it’s various worker and web roles. The SDK for .NET services is largely made up of extensions to WCF in the form of new bindings. Live Mesh allows you to access your content via service REST endpoints. All built on WCF.

So it’s clear to me that Microsoft is committed to WCF as the “center” of it’s on-going cloud strategy. It’s also clear to me that while deep knowledge of things such as custom behaviors and bindings can still be a “niche” skill, developers MUST have a solid working knowledge of WCF that goes beyond the standard “Hello World” sample.

The one where I talk about the MSMQ Binding

James Bender — Sat, 04 Apr 2009 04:22:58 GMT

One of the most over-looked bindings available in WCF is the Microsoft Message Queue (MSMQ) binding. The virtues of HTTP and TCP are well documented. REST is the cool, “new” way to access services. MSMQ seems relegated to interfacing WCF with older “legacy” systems.

This shouldn’t be the case. The MSMQ binding provides a rich set of features and functionality that make it an excellent choice for building many types of applications.

MSMQ from 1,000 ft.

MSMQ is a first-in, first-out message queue that have been available in Windows Server since NT 4. The concept is pretty simple: a sender sends a message to the queue, and a receive pulls it off when it’s ready.

The big benefit of MSMQ is that it allows messages to be passed between computers across networks in a secure, reliable manner. Since the queue is not an actual component of either application, the receiver does not need to be running when the message is sent (it will sit in the queue and wait to be picked up) nor does the receiver have to be on-line when the message is processed. Individual messages and queues allow one-way delivery of messages, but a second queue can be added to allow for duplexing.

Messages can sit in the queue either until a receiver grabs them or until they expire. Messages that expire are placed in a special “dead letters” queue.

Windows Vista introduced an upgrade to MSMQ called the “poison queue.” If a receiver attempts to process a message but can’t due to error, and it’s retry count is reached, it is placed into the poison queue. Previous to Vista the developer had to create a mechanism to identify these messages and “handle” them or risk attempting to process the same message over and over again until human intervention stopped it.

Queues can be transactional, meaning that if any part of a message fails, the entire message is rolled back. If the retry count has not been reached the receiver will attempt to process the message again until the count is reached and the message is moved to the poison queue.

The rest of this post assumes you have MSMQ installed on your computer and have a private transactional queue called HelloMSMQ. Instructions on how to add MSMQ and create a private queue can be found here.

Using the MSMQ Binding

OK, so now that we’ve got our private transactional queue created, the next steps are to create a message sender and message receiver. Using the netMSMQBinding binding will make this simple.

Note: There are two MSMQ bindings: the netMSMQBinding, which we will use, and the MSMQIntegratedBinding. The integrated binding is designed for using MSMQ to send/receive messages from legacy mainframe systems with MSMQ. For working with WCF to WCF communication use the “net” binding. Of course, you can expose multiple endpoints on your server, and making one endpoint “integrated” and the other “net” is an option if you need to proved services to both types of clients.

Since MSMQ by nature allows communication one way through a queue, you will need to make sure your service operation supports one-way calls. This is easily done by setting the IsOneWay property of the OperationContract to true:

[ServiceContract]

public interface IMyService

{

[OperationContract(IsOneWay=true)]

void SayHello(string name);

}

The next step is to create your endpoint. Here is the configuration for the endpoint that this services is exposed on:

Like all endpoints, this one includes the “ABC’s” of address, binding and contract. Contract here is pretty much what you would expect. The address points to a queue residing on a server somewhere, in this case the local machine. This address specifically points to the private “HelloMsmq” queue on our local machine. The binding is the netMSMQBinding. The binding configuration specifies that we aren’t going to worry about security for messages in this queue:

SVCUTIL creates a proxy that works just like any other WCF proxy; the address points at the same private queue and it uses the netMSMQBinding. From that point on you use it like you would any other WCF service

Where Would You Use This?

The inherit abilities of this binding provides a lot of benefits that can be used in many common situations. Since the service does not have to be online while clients send messages, the binding works very well in batch processing situations; clients can add messages to the queue all day, with the service being turned on at night to process the messages in a batch.

If you have a portion of your workforce that travels or needs to work disconnected at periods of time, MSMQ provides a way for them to work offline, with the queues syncing when the client reconnects to the network.

MSMQ is also an inherently reliable binding. Since messages are stored in a queue they can be “re-played” by the service if any sort of connectivity issues exist. If the message can be written to the queue it’s guaranteed that it will be delivered, at some point, to the service.

I hope this has piqued your interest in a very unappreciated and underused binding. MSMQ provides a robust and easy to use method to deliver messages to your service in a variety of enterprise scenarios. Most posts on how to utilize this binding will be coming soon…

Code on!

Speaking Tomorrow at MOCSDG !

James Bender — Wed, 01 Apr 2009 19:01:19 GMT

So, you’ve probably heard about Microsoft Azure by now, and how awesome it is. But there’s more to developing for Microsoft's Cloud Provider than web and worker roles.

I will be presenting a lap around Microsoft .NET Services, which provides some great infrastructure features that can make your Azure application development easier.

What? You’re not into the whole “cloud thing?”

Well then your in luck! Because with .NET Services you can still take advantage of these great features without having to build an “Azure application!”

What now? Oh, you’re not a “.NET developer?”

That’s cool, because .NET Services has SDK’s for Java AND Ruby! And they are available RIGHT NOW!

OK, since you have no more excuses, I’ll see you all at the Microsoft office at 6:00 tomorrow night!

Thoughts on the WCF REST Starter Kit

James Bender — Tue, 23 Dec 2008 01:53:13 GMT

One of the announcements that was kinda missed at PDC was the release of the WCF REST Starter Kit. In brief, the REST Starter Kit provides a was for developers to “jump-start” the development of REST services in WCF.

The Premise

In .NET 3.0 WCF allowed developers to abstract the way a service communicates with the world from the way the functionality of the service was implemented. Developers designing services in a “contract first” manner were able to specify minimum requirement and rules for their services. Provided that the communication medium (transport and binding) was able to provide the service with the facilities that it needed, that service could be invoked via that medium. For example, a service could expose both HTTP based and TCP based endpoints without having to change the functionality of the service. In WCF there is not a concept of a “web service”: there are just services. Some are available via HTTP over the web.

WCF also provided developers with ways to customize and extend the way the service communicated and behaved at runtime via custom channels and custom behaviors.

What it didn’t do very well was provide a way for developers to easily create REST based services. But that changed with the release of .NET 3.5. Using the WebGet and WebInvoke attributes in the Service Contract gave developers a way to write REST services in WCF

The Problem

For all it’s power, configurability and extensibility WCF has always had a bit of an image problem. Most developers view it as difficult to work with, difficult to understand and tied to a obnoxiously verbose configuration model. The inclusion of REST abilities in 3.5 did nothing to help do away with this perception.

The Solution

Enter the WCF REST Starter Kit. The Starter Kit provides a set of templates for creating a variety of REST-based services including Singleton Services (exposing a single resource on the server), Collection Service (exposing a list of resources/data), POX Service and projects for ATOM feeds and ATOM publishing protocols. The starter kit also comes with a new assembly called Microsoft.ServiceModel.Web which contains an API the provides a lot of out-of-the box functionality to support REST services including customized help pages, customized caching, easier ways to return exceptions, URI templates, and the ability to use request and response headers.

The long and the short of it is that you select a project template based on what kind of service you want to write and then add the appropriate functionality to a few methods and bang, you’ve got a service.

The Good

The starter kit comes with templates for most kind of REST based services you will need to write. While a basic knowledge of REST and how routing works (if you’ve done any significant MVC work you’ll be fine) you can get a REST based service up and running in a matter of minutes with data represented as both XML and JSON. Little real WCF knowledge is required to simply get a service up and running.

The API extensions will offer something to those more experienced with WCF by providing a means to perform some customization without having to write a custom behavior or channel.

The Bad

It started with the install. Part of the starter kit is a bunch of Visual Studio content. The installer kept giving me a Null Reference Exception. I found a workaround here.

The classes created by the starter kit are designed for ease of implementation, not for extensibility. Customization involves a lot of friction. If you need to do anything beyond a basic REST implementation you will need to acquaint yourself with the object model that the starter kit uses, which can be a little overly complex. If you need to do complex routing or create a service to provide more than one data type you’ll need a level of knowledge about REST in WCF that the start kit is supposed to insulate you from.

Another issue I’ve encountered is that when I try to rename the Service.svc file in the project generated by the Starter Kit I get an “… operation not completed. Unspecified error.” error.

In the End

I’m in favor of a REST Starter Kit, or ANYTHING for that matter that increases adoption of WCF. I think the Starter Kit is a good late-beta/1.0 release, but it’s got a ways to got before I consider it a major part of my tool-box.

Code On!

.NET University Recap

James Bender — Wed, 12 Nov 2008 15:33:34 GMT

I want to thank everybody who attended .NET university this past weekend in Columbus. It was the first event (that I know of at least) of it’s kind and it was great to meet a lot of new people who don’t normally participate in the .NET community. I hope this that you learned something useful and continue your exploration or .NET and the rich set of technologies that surround it.

For those of you who asked, my web services slide deck can be downloaded here.

Hope to see you all at the next event!