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!