2005 2006 2007 2008 2009 2010 2011 2015 2016 2017 2018 aspnet azure csharp debugging docker elasticsearch exceptions firefox javascriptajax linux llblgen mongodb powershell projects python security services silverlight training videos wcf wpf xag xhtmlcss

Learn WCF via MSDN Nuggets

Want to learn WCF (a.k.a. Indigo)? If so, you should head on over to MSDN UK to see Mike Taulty's latest MSDN Nuggets.

http://www.microsoft.com/uk/msdn/events/nuggets.aspx

Currently there are three videos:

  • Hello World
  • Type Serialization
  • Bindings

You will find that WCF looks much like old-school COM, but has the power of MSMQ, COM+, remoting, Web Services and the simplicity of .NET. Awesome!

For more information on WCF check out this great MSDN article: http://msdn.microsoft.com/library/en-us/dnlong/html/introtowcf.asp.

MSDN Nuggets WCF Mania!



I just did my weekly check of the MSDN nuggets page and found that Mike Taulty has been hard at work. He just released 6 more WCF videos.

  • Message Encoding
  • Message Patterns
  • Sessions
  • Instancing
  • Concurrency
  • Exceptions

Given the great quantity and quality of videos out there on WinFX technologies there is absolutely no reason people can't learn these new technologies. You don't need to read books, study whitepapers, or listen to those Geneva-convention-violating boring webcasts, all you have to do it click and pay attention. It's as if osmosis truely is a viable way of learning!

You can access these videos at the below link.

MSDN Nuggets

Indigo Girl



OK, everyone interested in WCF needs to stop what they are doing and head on over to http://www.thatindigogirl.com/. Michele has posted chapters to her up amazing, soon-to-be-released WCF book up there. Not just that, but there are a few things that really impress me.

First off, she has to be my new technology role model (move over Brad Abrams and Andrew Trolsen) as she to be the highest ranking MVP in the world. Sheesh, just go look at her profile at http://www.idesign.net/.

Secondly, she's probably the best writer I've ever read. Picky doesn't even begin to describe me. If I don't consider the author absolutely outstanding, I don't bother flipping the pages. She is one of the very few people I can actually put up with. Her bypassing of the silly Hello World example for a more useful one was very respectable and it demonstrated to me that she wants to get right to the point (in turn this shows technical security; insecure writers have SO padding and PCness!)

Third, she seems to be a bottomless pit of powerful and useful training. Today was the first time I read her work and in the first 30 pages of her book I was able to overcome a load of WCF obstacles I was hitting with the go-live version.

Fourth, she has a very beautiful website. Not that she did it, but it does show that she cares about her environment. It rather bothers me when my fellow architects feel the need to go all hardcore and boring on me. She seems to be immune to that. Um...yes, I rate my favorite architects by more than their technical skills!

I swore to only buy book from Abrams and Troelsen, but I'm going to pre-order her book...something I've never done before. I'm extremely impressed with her work. Seriously, go check her blog, website, and book out!

WCF Beta 2 and Go-live license!



At last! We now have beta 2 of WCF and a corresponding Go live license! This is incredible news for architects and developers alike. We can finally use the foundation to help unite our current (and future) component services, web services, and MSMQ applications in production

Just the other day I was designing an architecture and I was thinking "Gosh, this would be so nice in WCF. I *REALLY* don't want to do this in the old school way...if only the beta 2 and the Go-live license would be released!" Three days later...BAM!

Woohoo!! Not only that but beta 2 of WWF with a corresponding Go-live license is also available. I haven't been this excited since Firefox 1.5 came out!!!

Here's the Go-live license and the WCF beta 2 download (as well as WWF beta 2).

WCF Relative Binding Speeds



My latest infrastructure design consists of a few services spread over various servers and with many clients in various locations. Some of the clients will be on the same machine as the service, others will be on the same NT-based network, others will be WSE3 services, and even others will be PHP based. I wanted to provide the best solution for each, ergo my love for the Go-live of WCF! With WCF I can have the services expose multiple endpoints to allow a diverse number of clients each with their own maximum efficiency (remember, if you aren't measuring, then you aren't engineering!) PHP clients for example will get a BasicHttpBinding endpoint, while clients on the same machine as the service will use the NetNamedPipeBinding.

What do the speeds look like for each of these bindings? I went ahead and wrote a quick test harness to see the relative speeds of each binding. These are very simple tests, but they do demonstrate how the speeds of the bindings compare with each other. Without a ton of needless talk, let's get right into what's going on…

Here is the service configuration file…

  <system.serviceModel>
    <services>
      <service type="WcfDemo.DemoService">
        <endpoint
          address="WsDualHttpBinding"
          contract="WcfDemo.IDemoService"
          binding="wsDualHttpBinding"
          />
        <endpoint
          address="WsHttpBinding"
          contract="WcfDemo.IDemoService"
          binding="wsHttpBinding"
          />
        <endpoint
          address="BasicHttpBinding"
          contract="WcfDemo.IDemoService"
          binding="basicHttpBinding"></endpoint>
        <endpoint
          address="NetTcpBinding"
          contract="WcfDemo.IDemoService"
          binding="netTcpBinding"
          />
        <endpoint
          address="NetNamedPipeBinding"
          contract="WcfDemo.IDemoService"
          binding="netNamedPipeBinding"></endpoint>
      </service>
    </services>
  </system.serviceModel>

Here is the significant portion of the service code...

Uri netTcpAddress = new Uri("net.tcp://localhost:8080/");
Uri httpAddress = new Uri("http://localhost:8081/");
Uri netPipeAddress = new Uri("net.pipe://localhost/");
using (ServiceHost service = new ServiceHost(typeof(DemoService), new Uri[] { netTcpAddress, httpAddress, netPipeAddress })) {
        service.Open( );


        Console.WriteLine("Listening...");
        Console.ReadLine( );
}

Notice the netPipeAddress is using "net.pipe" as the address scheme and doesn't have a port. This is actually for the netNamedPipeBinding binding which is for inner process communication on the same machine, so there wouldn't be a port for that. The netTcpBinding binding does however have a port as it would really be out on the network somewhere. Also keep in mind that you add a URI for each address scheme, not each address.

Here is the client configuration file...

<system.serviceModel>
    <client>
      <endpoint
        address="http://localhost:8081/WsDualHttpBinding"
        binding="wsDualHttpBinding"
        name="WSDualHttpBinding"
        contract="IDemoService" />
      <endpoint
        address="http://localhost:8081/WsHttpBinding"
        binding="wsHttpBinding"
        name="WSHttpBinding"
        contract="IDemoService" />
      <endpoint
        address="http://localhost:8081/BasicHttpBinding"
        binding="basicHttpBinding"
        name="BasicHttpBinding"
        contract="IDemoService" />
      <endpoint
        address="net.tcp://localhost:8080/NetTcpBinding"
        binding="netTcpBinding"
        name="NetTcpBinding"
        contract="IDemoService" />
      <endpoint
        address="net.pipe://localhost/NetNamedPipeBinding"
        binding="netNamedPipeBinding"
        name="NetNamedPipeBinding"
        contract="IDemoService" />
    </client>
  </system.serviceModel>

Again notice there is no port on the netNamedPipeBinding binding and there is a port on the netTcpBinding. Also notice that each of the addresses end in the name of the endpoint specified by the server; the endpoints also have a name attribute to be accessible by the client-side code as seen in the next code block.

Here is how I start my client code...

DemoServiceClient wSDualHttpClient = new DemoServiceClient("WSDualHttpBinding");
DemoServiceClient wSHttpClient = new DemoServiceClient("WSHttpBinding");
DemoServiceClient basicHttpClient = new DemoServiceClient("BasicHttpBinding");
DemoServiceClient netTcpClient = new DemoServiceClient("NetTcpBinding");
DemoServiceClient netNamedPipeClient = new DemoServiceClient("NetNamedPipeBinding");

My actual benchmarking code consists of a simple timer that look like this...

Person person = new Person( );
DateTime a = DateTime.Now;
int i = 0;
while ((DateTime.Now - a).Seconds < 10) {
    wSDualHttpClient.RecordPerson(person);
    i++;
}
Console.WriteLine("WSDualHttpBinding: Processed {0} calls in 10 seconds", i);

That basically just means I want to run as many tests as possible in 10 seconds.

I actually ordered the tests based on my predictions of their relative speeds and it turns out my predictions were correct. Take a look for yourself...

WSDualHttpBinding: Processed 1602 calls in 10 seconds
WSHttpBinding: Processed 2531 calls in 10 seconds
BasicHttpBinding: Processed 17913 calls in 10 seconds
NetTcpBinding: Processed 39957 calls in 10 seconds
NetNamedPipeBinding: Processed 48255 calls in 10 seconds

This isn't really that surprising. The more complex web services protocols are slower than the most basic ones, which are in turn slower than a direct TCP connection, which in turn is slower than the named-pipes binding connection for use on the same machine.  So, if you are going to be doing something chatty, you may want to think twice before using SOAP.

That was actually an out-of-the-box benchmark; that is, I didn't customize the bindings in any way. In another test I turned off security for the WsDualHttpBinding and WsHttpBinding bindings.

First, I added the following binding sections to both the service and the client configuration files.

<bindings>
  <wsDualHttpBinding>
    <binding name="noSecurity">
      <security mode="None"></security>
    </binding>
  </wsDualHttpBinding>
  <wsHttpBinding>
    <binding name="noSecurity">
      <security mode="None"></security>
    </binding>
  </wsHttpBinding>
</bindings>

Then I altered the endpoints to point to the appropriate binding. Here is the service configuration alteration.

<endpoint
    address="WsDualHttpBinding"
    bindingConfiguration="noSecurity"
    contract="WcfDemo.IDemoService"
    binding="wsDualHttpBinding"
    />
<endpoint
    address="WsHttpBinding"
    bindingConfiguration="noSecurity"
    contract="WcfDemo.IDemoService"
    binding="wsHttpBinding"
    />

here is the client configuration alteration.

<endpoint
    address="http://localhost:8081/WsDualHttpBinding"
    binding="wsDualHttpBinding"
    name="WSDualHttpBinding"
    bindingConfiguration="noSecurity"
    contract="IDemoService" />
<endpoint
    address="http://localhost:8081/WsHttpBinding"
    binding="wsHttpBinding"
    name="WSHttpBinding"
    bindingConfiguration="noSecurity"
    contract="IDemoService" />

The results for both WSDualHttpBinding and WSHttpBinding were much faster!

WSDualHttpBinding: Processed 5773 calls in 10 seconds
WSHttpBinding: Processed 17257 calls in 10 seconds
BasicHttpBinding: Processed 19528 calls in 10 seconds
NetTcpBinding: Processed 39756 calls in 10 seconds
NetNamedPipeBinding: Processed 47457 calls in 10 seconds

So as you can see you can get really different levels of performance based on the different binding you use. The ability to have these various endpoints provides a great mechanism for my services to reach all kinds of different clients with great interoperability and maximized speed for network and local communication. Best of all, it's all free...no extra coding! All I had to do to add the new binding was add the endpoint to the service configuration file. WCF takes care of all the rest for you...

Supplemental material - Sample Projects

WCF: A self-hosted service with multiple endpoints



Last night I started playing with more more interesting things in WCF (multiple endpoints) and I kept running into a wall: how do you set more than one http endpoint on the same service!? Nothing I was doing was working, then I ran into Indigo Girl's WCF book chapters online (see my next post). Her examples clearly explain what I was doing wrong. Let me explain how to do what I wanted to do in my own words…

Instead of having a different "server" for each endpoint of the same address scheme (i.e. http), you have a a base address for and then give each a name. There is one WSDL for all the endpoints of a service. That is: one service, one WSDL; not one endpoint, one WSDL. This stems from the fact that by default there are two endpoints repackages: mex and HTTP Get. The HTTP get one is the one that will help out with the WSDL.

Here is the fixed up code. By running this up and generating the proxy, we are able to have the complete mechanism for communication from the client to the service, including the configuration file (below).

Program.cs
Uri httpUri = new Uri("http://localhost:8081/");
using(ServiceHost hService = new ServiceHost(typeof(DemoService), httpUri)) {
 hService.AddServiceEndpoint(typeof(IDemoService), new BasicHttpBinding( ), "BasicService");
 hService.AddServiceEndpoint(typeof(IDemoService), new WSDualHttpBinding( ), "DualHttpService");


 hService.Open( );


 Console.WriteLine("Listening...");
 Console.ReadLine( );
}
client app.config


  <system.serviceModel>
    <client>
      <endpoint
        address="http://localhost:8081/BasicService"
        binding="basicHttpBinding"
        name="BasicHttpService"
        contract="IDemoService" />
      <endpoint
        address="http://localhost:8081/DualHttpService"
        binding="wsDualHttpBinding"
        name="DualHttpService"
        contract="IDemoService" />
    </client>
  </system.serviceModel>

Even when using entitely different protocols (the higher level http and say the lower level tcp), you have one WSDL. Of course in this case, since there are more one address scheme (http and net.tcp), you have more than one base address; one per scheme.

Program.cs
Uri netTcpAddress = new Uri("net.tcp://localhost:8080/");
Uri httpAddress = new Uri("http://localhost:8081/");
using (ServiceHost service = new ServiceHost(typeof(DemoService), new Uri[] { netTcpAddress, httpAddress })) {
 service.Open( );


 Console.WriteLine("Listening...");
 Console.ReadLine( );
}
server app.config


  <system.serviceModel>
    <services>
      <service type="WcfDemo.DemoService">
        <endpoint
          address="NetTcpService"
          contract="WcfDemo.IDemoService"
          binding="netTcpBinding"
          />
        <endpoint
          address="DualHttpService"
          contract="WcfDemo.IDemoService"
          binding="wsDualHttpBinding"
          />
      </service>
    </services>
  </system.serviceModel>
client app.config


  <system.serviceModel>
    <client>
      <endpoint
        address="net.tcp://localhost:8080/NetTcpService"
        binding="netTcpBinding"
        name="NetTcpService"
        contract="IDemoService" />
      <endpoint
        address="http://localhost:8081/DualHttpService"
        binding="wsDualHttpBinding"
        name="DualHttpService"
        contract="IDemoService" />
    </client>
  </system.serviceModel>

As you can see WCF really allows for some pretty powerful scenarios...

March 2006 WCF Resources



Heres just an update on the popular resources on WCF on the web.

Some links worth looking at...

Here's a list of the video Mike has up at the MSDN Nuggets website (link above).

  • "Hello World"
  • Type Serialization
  • DataContract Serialization
  • Typed and Untyped Messages
  • Bindings
  • Message Encoding
  • Message Patterns
  • Sessions
  • Instancing
  • Concurrency
  • Exceptions
  • Transactions
  • HTTPS Transport Security
  • Message Security
  • Authorisation
  • Auditing

WCF Relative Binding Speed Demo Updated



Last year I released a simple demo showing the relative binding speeds of the various native bindings in WCF. Since that time, WCF the syntax has changed a bit making my original code obsolete. Now I'm posting the the source code based on the final version of WCF.

Here are the changes I made (most are simply to update):

  • The client proxies changed from "Proxy" to "Client"
  • <service type="..."> changed to <service name="...">
  • The 'mex' binding was added.
  • ServiceEndpoint was moved to System.ServiceModel.Description
  • On the service interface, the ServiceContract attribute ProtectionLevel was set to ProtectionLevel.None so that security is not required, thus giving a more accurate benchmark.

You can use these as a bases for you own services, but you may also wish to look at my XML Assembly Compiler which has a WCF service template. You can simply select the template, perhaps design a few types and interfaces, and let it create your entire WCF project for you.

Links

English Standard Version Bible Web Service via WCF



The WCF version of this died years ago. The new versions are at https://bitbucket.org/davidbetz/esv-bible-services-for-.net

Many of the applications that I create are Bible based applications and my designs are made easier thanks to the the English Standard Version of Scripture. Long before I used it for development, I fell in love with it and made it my primary Bible version, not only because it's an incredible Bible translation with incredible accuracy and amazing readability, but also because it's so widely accessible. Their website at http://www.gnpcb.org/esv/ is by far one of my favorite websites. I can read on my screen, adjusting the font-size on a whim or click on an audio link to listen to any chapter in a variety of formats. Furthermore, they have great Firefox support and great technical articles explaining the internals of the system.

Not only that, you can also access the ESV text through e-mail and through a SOAP interface. Being someone deeply involved with interop and someone who has commited myself to the study of Scripture I am overjoyed to have the ability to directly access the ESV Bible data source. That said, now adays I'm a WCF user and the ESV Bible Web Service interface has methods and properties which, when used in WCF, are very Java-ish. Not a problem... I went ahead and got the svcutil code and modified it a bit to make the proxy follow the .NET Framework Design Guidelines. I cleaned up the svcutil output, added XML comments, added an added enumeration class and then split into different files for easier modification. Feel free to take the classes and combine them back into one proxy file as you wish. Here is a sample application using the fixed proxy:

using (var client = new ESVBibleClient( )) {
    var options = new OutputOptions( );
    options.IncludeFootnotes = true;
    options.IncludeCopyright = true;
    options.OutputFormat = OutputFormat.PlainText;


    String text = client.DoPassageQuery("TEST", "1 John 2", options);


    Console.WriteLine(text);
    Console.ReadLine( );
}

XmlHttp Service Interop - Part 2 (Utilizing WCF)



Today I'm publishing the second in an article series regarding XmlHttp Service Interop. In this article, entitled "Utilizing WCF", I explain how to build WCF services, how to trace their XML messages, and how to communicate with them and other SOAP services via raw XmlHttp.

Instead of posting the entire thing on my blog, from here on out I'm going to be posting articles in their own pages to make them easier to read and easier to access. This will also make it easier for me to update and edit as well. You may access this article as well as others in the series by the links below.

Extremely Misunderstood Software



Today I was thinking about some of the misunderstandings going around about software. Actually my life revolves around misunderstandings in every area of my life (not just my life in technology!) and I'm usually thinking about it in some respect. I can recall back to early 2004 when I was the black sheep in both the Microsoft AND Mozilla communities for promoting .NET and web standards. The Mozilla-ish (open-source) guys would mock the severe inefficiencies and painful security flaws of .NET (though they never ACTUALLY used .NET!) and the Microsoft-ish (.NET) guys would mock call me personally unrepeatable names for even suggesting that web developers should learn the foundational principles of JavaScript, CSS, and XHTML before they starting asking a load of "how do I…" questions. Now while the open-source community has wised up a bit, I still get extremely vile insults from the git-r-done areas .NET community where even mentioning proper development or training will get you killed. In any case, this is my life and like I say… not just in technology. Basically, everyone hates me :)

So, here's my concise (yeah like I'm capable of that) list of software that is EXTREMELY misunderstood. I'm not going to go into any detail except put a single line by the item which should give you a hint as to what the software really is. This is important: if you understand one of the confusions, that confusion is analogous to each of the others. For example, if you know how insane it is to compare SQL Server 2005 to MySQL then, guess what… you now understand why it's insane to compare Firefox to IE or LLBLGen Pro to .netTiers or NHibernate. You just can't do it! Yet, people all day long give me unjustifiable grief about this stuff and I am forced to spend literally 70% of my time in marketing instead of programming!

I'll shut up now… here's the list:

List of Extremely Misunderstood Software

Squid Micro-Blogging Library for .NET 3.5



A few years ago I designed a system that would greatly ease data syndication, data aggregation, and reporting.  The first two components of the system were repackaged and release early last year under the incredibly horrible name "Data Feed Framework".  The idea behind the system was two fold.  The first concept was that you write a SQL statement and you immediately get a fully functional RSS feed with absolutely no more work required.  Here's an example of a DFF SQL statement that creates an RSS feed of SQL Server jobs:

select Id=0,
Title=name,
Description=description
from msdb.dbo.sysjobs
where enabled = 1

The second part of DFF was it's ASP.NET control named InfoBlock that would accept an RSS or ATOM feed and display it in a mini-reader window.  The two parts of DFF combine to create the following:

Given the following SQL statement (or more likely a stored procedure)...

select top 10
Id=pc.ContactID, 
Title=pc.FirstName + ' ' + pc.LastName + ': $' + convert(varchar(20), convert(numeric(10,2), sum(LineTotal))), 
Description='', 
LinkTemplate = '/ShowContactInformation/{id}'
from Sales.SalesOrderDetail sod
inner join Sales.SalesOrderHeader soh on soh.SalesOrderID = sod.SalesOrderID
inner join Person.Contact pc on pc.ContactID = soh.SalesPersonID
group by pc.FirstName, pc.LastName, pc.ContactID
order by sum(LineTotal) desc

...we have an automatically updating RSS feed and when that RSS feed is given to an InfoBlock, you get the following:

image

InfoBlocks could be placed all over a web site or intranet to give quick and easy access to continually updating information.  The InfoBlock control would also register the feed with modern web browsers that had integrated RSS support.  Furthermore, since it was styled properly in CSS, there's no reason for it to be a block at all.  It could be a horizontal list, a DOM-based window, or even a ticker as CSS and modern AJAX techniques allow.

DFF relied on RSS.NET for syndication feed creation and both RSS.NET and Atom.NET for aggregation.  It also used LLBLGen Pro a bit to access the data from SQL Server.  As I've promised with all my projects, they will update as new technologies are publicly released.  Therefore, DFF has been completely updated for .NET 3.5 technologies including LINQ and WCF.

I've also decided to continue down my slippery slope of a change in product naming philosophy.  Whereas before I would follow the Microsoft marketing philosophy of "add more words to the title until it's so long to say that you require an acronym" to the more Linux or O'Reilly approaches of "choose a random weird sounding word and leave it be" and "pick a weird animal", respectively.  I've also been moving more towards the idea of picking a cool name and leaving it as is.  This is in contrast to Microsoft's idea of picking an awesome name and then changing it to an impossibly long name right before release (i.e. Sparkle, Acrylic, and Atlas)  Therefore, I decided to rename DFF to Squid.  I think this rivals my Dojr.NET and Prominax (to be released-- someday) projects as having the weirdest and most random name I've ever come up with.  I think it may have something to do with SQL and uhhhh.. something about a GUID.  Donno.

Squid follows the same everything as DFF, however the dependencies on RSS.NET and ATOM.NET were completely removed.  This was possible due to the awesome syndication support in WCF 3.5.  Also, all reliance on LLBLGen Pro was removed.  LLBLGen Pro (see my training video here) is an awesome system and is the only enterprise-class O/R mapping solution in existence.  NHibernate should not be considered enterprise-class and it's usability is almost through the floor.  Free in terms of up-front costs, does not mean free in terms of usability (something Linux geeks don't seem to get).  However, given that LINQ is built into .NET 3.5, I decided that all my shared and open-source projects should be using LINQ, not LLBLGen Pro.  The new LLBLGen Pro uses LINQ and when it's released, should absolutely be used as the primary solution for enterprise-class O/R mapping.

Let me explain a bit about the new syndication feature in WCF 3.5 and how it's used in Squid.  Creating a syndication feed in WCF is required a WCF endpoint just like everything else in WCF.  This endpoint will be part of a service and will have an address, binding, and contract.  Nothing fancy yet as the sweetness is in the details.  Here's part of the contract Squid uses for it's feed service (don't be jealous of the VS2008 theme -- see Scott Hanselman's post on VS2008 themes):

namespace Squid.Service
{
    [ServiceContract(Namespace = "http://www.netfxharmonics.com/services/squid/2008/03/")]
    public interface ISquidService
    {
        [OperationContract]
        [WebGet(UriTemplate = "GetFeedByTitle/{title}")]
        Rss20FeedFormatter GetFeedByTitle(String title);


        //+ More code here
    }
}

Notice the WebGet attribute.  This is applied to signify that this will be part of a HTTP GET request.  This relates to the fact that we are using a new WCF 3.5 binding called the WebHttpBinding.  This is the same binding used by JSON and POX services.  There are actually a few new attributes, each of which provides it's own treasure chest (see later in this post when I mention a free chapter on the topic).  The WebGet attribute has an awesome property on it called UriTemplate that allows you to match parameters in the request URI to parameters in the WCF operation contract.  That's beyond cool.

The service implementation is extremely straight forward.  All you have to do is create a SyndicationFeed object, populate it with SyndicationItem objects and return it in the constructor of the Rss20FeedFormatter.  Here's a non-Squid example:

SyndicationFeed feed = new SyndicationFeed();
feed.Title = new TextSyndicationContent("My Title");
feed.Description = new TextSyndicationContent("My Desc");
List<SyndicationItem> items = new List<SyndicationItem>();
items.Add(new SyndicationItem()
{
    Title = new TextSyndicationContent("My Entry"),
    Summary = new TextSyndicationContent("My Summary"),
    PublishDate = new DateTimeOffset(DateTime.Now)
});
feed.Items = items;
//+
return new Rss20FeedFormatter(feed);

You may want to make note that you can create an RSS or ATOM feed directly from an SyndicationFeed instance using the SaveAsRss20 and SaveAsAtom10 methods.

As with any WCF service, you need a place to host it and you need to configure it.  To create a service, I simply throw down a FeedService.svc file with the following page directive (I'm really not trying to have the ugliest color scheme in the world-- it's just an added bonus):

<%@ ServiceHost Service="Squid.Service.SquidService" %>

The configuration is also fairly straight forward, all we have is our previously mentioned ending with an address(blank to use FeedService.svc directly), binding (WebHttpBinding), and contract(Squid.Service.ISquidService).  However, you also need to remember to add the WebHttp behavior or else nothing will work for you.

<system.serviceModel>
  <behaviors>
    <endpointBehaviors>
      <behavior name="FeedEndpointBehavior">
        <webHttp/>
      </behavior>
    </endpointBehaviors>
  </behaviors>
  <services>
    <service name="Squid.Service.SquidService">
      <endpoint address=""
                binding="webHttpBinding"
                contract="Squid.Service.ISquidService"
                behaviorConfiguration="FeedEndpointBehavior"/>
    </service>
  </services>
</system.serviceModel>

That's seriously all there is to it: write your contract, write your implementation, create a host, and set configuration.  In other words, creating a syndication feed in WCF is no different than creating a WsHttpBinding or NetTcpBinding service.  However, what about reading an RSS or ATOM feed? This is even simpler.

To read a feed all you have to do is create an XML reader with the data source of the feed and pass that off to the static Load method of the SyndicationFeed class.  This will return an instance of SyndicationFeed which you may iterate or, as I'm doing in Squid, transform with LINQ.  I actually liked how my server-control used an internal repeater instance and therefore wanted to continue to use it.  So, I kept my ITemplate object (RssListTemplate) the same and used the following LINQ to transform a SyndicationFeed to what my ITemplate what already using:

Object bindingSource = from entry in feed.Items
                       select new SimpleFeedEntry
                       {
                           DateTime = entry.PublishDate.DateTime,
                           Link = entry.Links.First().Uri.AbsoluteUri,
                           Text = entry.Content != null ? entry.Content.ToString() : entry.Summary.Text,
                           Title = entry.Title.Text
                       };

Thus, with .NET 3.5 I was able to remove RSS.NET and ATOM.NET completely from the project.  LINQ also, of course helped me with my database access and therefore remove my dependency on my LLBLGen Pro generated DAL:

using (DataContext db = new DataContext(Configuration.DatabaseConnectionString))
{
    var collection = from p in db.FeedCreations
                     where p.FeedCreationTitle == title
                     select p;
    //+ More code here
}

Thus, you can use Squid in your existing .NET 3.5 system with little impact to anything.  Squid is what I use in my Minima blog engine to provide the boxes of information in the sidebar.  I'm able to modify the data in the Snippet table in the Squid database to modify the content and order in my sidebar.  Of course I can also easily bring in RSS/ATOM content from the web with this as well.

You can get more information on the new web support in WCF 3.5 by reading the chapter "Programmable Web" (free chapter) in the book Essential WCF for .NET 3.5 (click to buy).  This is an amazing book that I highly recommend to all WCF users.

Links

NetFXHarmonics DevServer Released



Two months ago started work on a project to help me in my AJAX and SOA development.  What I basically needed was a development web server that allowed me to start up multiple web servers at once, monitor server traffic, and bind to specific IP interfaces.  Thus, the creation of NetFXHarmonics DevServer.  I built it completely for myself, but others started to ask for it as well.  When the demand for it became stronger, I realized that I needed to release the project on the web.  Normally I would host it myself, but given the interest from the .NET community, I thought I would put it on CodePlex.  I've only cried twice seen I've put it on CodePlex, but I'll survive.

NetFXHarmonics DevServer is a web server hosting environment built on WPF and WCF technologies that allows multiple instances of Cassini-like web servers to run in parallel. DevServer also includes tracing capabilities for monitoring requests and responses, request filtering, automatic ViewState and ControlState parsing, visually enhanced HTTP status codes, IP binding modes for both local-only as well as remote access, and easy to use XML configuration.

Using this development server, I am able to simultaneously start multiple web sites to very quickly view everything that happens over the wire and therefore easily debug JSON and SOAP messages flying back and forth between client and server and between services.  This tool have been a tremendous help for me in the past few months to discover exactly why my services are tripping out without having to enable WCF tracing.  It's also been a tremendous help in managing my own web development server instances for all my projects, each having 3-5 web sites (or segregated service endpoints) each.

Let me give you a quick run down of the various features in NetFXHarmonics DevServer with a little discussion of each feature's usage:

XML Configuration

NetFXHarmonics DevServer has various projects (and therefore assemblies) with the primary being DevServer.Client, the client application which houses the application's configuration.

In the app.config of DevServer.Client, you have a structure that looks something like the following:

<jampad.devServer>
</jampad.devServer>

This is where all your configuration lives and the various parts of this will be explained in their appropriate contexts in the discussions that follow.

Multiple Web Site Hosting

In side of the jampad.devServer configuration section in the app.config file, there is a branch called <servers /> which allows you to declare the various web servers you would like to load.  This is all that's required to configure servers.  Each server requires a friendly name, a port, a virtual path, and the physical path.  Given this information, DevServer will know how to load your particular servers.

<servers>
  <server key="SampleWS1" name="Sample Website 1" port="2001"
          virtualPath="/" physicalPath="C:\Project\DevServer\SampleWebsite1">
  </server>
  <server key="SampleWS2" name="Sample Website 2" disabled="true" port="2003"
          virtualPath="/" physicalPath="C:\Project\DevServer\SampleWebsite2">
  </server>
</servers>

If you want to disable a specific server from loading, use the "disabled" attribute.  All disabled servers will be completely skipped in the loading process.  On the other hand, if you would like to load a single server, you can actually do this from the command line by setting a server key on the <server /> element and by accessing it via a command line argument:

DevServer.Client.exe -serverKey:SampleWS1

In most scenarios you will probably want to load various sets of servers at once.  This is especially true in properly architected service-oriented solutions.  Thus, DevServer includes a concept of startup profiles.  Each profile will include links to a number of keyed servers.  You configure these startup profiles in the <startupProfiles /> section.

<startupProfiles activeProfile="Sample">
  <profile name="Sample">
    <server key="SampleWS1" />
    <server key="SampleWS2" />
  </profile>
</startupProfiles>

This configuration block lives parallel to the <servers /> block and the inclusion of servers should be fairly self-explanatory.  When DevServer starts it will load the profile in the "activeProfile" attribute.  If the activeProfile block is missing, it will be ignored.  If the activeProfile states a profile that does not exist, DevServer will not load.  When using a startup profile, the "disabled" attribute on each server instance is ignored.  That attribute is only for non-startup profile usage.  An activeProfile may also be set via command line:

DevServer.Client.exe -activeProfile:Sample

This will override any setting in the activeProfile attribute of <startupProfiles/>.  In fact, the "serverKey" command line argument overrides the activeProfile <startupProfiles /> attribute as well.  Therefore, the order of priority is is as follows: command line argument override profile configuration and profile configuration overrides the "disabled" attribute.

Most developers don't work on one project and with only client.  Or, even if they do, they surely have their own projects as well.  Therefore, you may have even more servers in your configuration:

<server key="ABCCorpMainWS" name="Main Website" port="7001"
        virtualPath="/" physicalPath="C:\Project\ABCCorp\Website">
</server>
<server key="ABCCorpKBService" name="KB Service" port="7003"
        virtualPath="/" physicalPath="C:\Project\ABCCorp\KnowledgeBaseService">
</server>
<server key="ABCCorpProductService" name="Product Service" port="7005"
        virtualPath="/" physicalPath="C:\Project\ABCCorp\ProductService">
</server>

These would be grouped together in their own profile with the activeProfile set to that profile.

<startupProfiles activeProfile="ABCCorp">
  <profile name="ABCCorp">
    <server key="ABCCorpMainWS" />
    <server key="ABCCorpKBService" />
    <server key="ABCCorpProductService" />
  </profile>
  <profile name="Sample">
    <server key="SampleWS1" />
    <server key="SampleWS2" />
  </profile>
</startupProfiles>

What about loading servers from different profiles?  Well, think about it... that's a different profile:

<startupProfiles activeProfile="ABCCorpWithSampleWS1">
  <profile name="ABCCorpWithSampleWS1">
    <server key="SampleWS1" />
    <server key="ABCCorpMainWS" />
    <server key="ABCCorpKBService" />
    <server key="ABCCorpProductService" />
  </profile>
</startupProfiles>

One of the original purposes of DevServer was to allow remote non-IIS access to development web sites.  Therefore, in DevServer you can use the <binding /> configuration element to set either "loopback" (or "localhost") to only allow access to your machine, "any" to allow web access from all addresses, or you can specific a specific IP address to bind the web server to a single IP address so that only systems with access to that IP on that interface can access the web site.

In the following example the first web site is only accessible by the local machine and the second is accessible by others.  This comes in handy for both testing in a virtual machine as well as quickly doing demos.  If your evil project manager (forgive the redundancy) wants to see something, bring the web site up on all interface and he can poke around from his desk and then have all his complains and irrational demands ready when he comes to your desk (maybe you want to keep this feature secret).

<server key="SampleWS1" name="Sample Website 1" port="2001"
        virtualPath="/" physicalPath="C:\Project\DevServer\SampleWebsite1">
  <binding address="loopback" />
</server>
<server key="SampleWS2" name="Sample Website 2" port="2003"
        virtualPath="/" physicalPath="C:\Project\DevServer\SampleWebsite2">
  <binding address="any" />
</server>

Web Site Settings

In addition to server configuration, there is also a bit of general configuration that apply to all instances.  As you can see from the following example, you can add default documents to the existing defaults and you can also setup content type mappings.  A few content types already exist, but you can override as the example shows.  In this example, where ".js" is normally sent as text/javascript, you can override it to go to "application/x-javascript" or to something else.

<webServer>
  <defaultDocuments>
    <add name="index.jsx" />
  </defaultDocuments>
  <contentTypeMappings>
    <add extension=".jsx" type="application/x-javascript" />
    <add extension=".js" type="application/x-javascript" override="true" />
  </contentTypeMappings>
</webServer>

Request/Response Tracing

One of the core features of DevServer is the ability to do tracing on the traffic in each server.  Tracing is enabled by adding a <requestTracing /> configuration element to a server and setting the "enabled" attribute to true.

<server key="SampleWS1" name="Sample Website 1" port="2001"
        virtualPath="/" physicalPath="C:\Project\DevServer\SampleWebsite1">
  <binding address="loopback" />
  <requestTracing enabled="true" enableVerboseTypeTracing="false" enableFaviconTracing="true" />
</server>

This will have request/response messages show up in DevServer which will allow you to view status code, date/time, URL, POST data (if any), response data, request headers, response headers, as well as parsed ViewState and Control state for both the request and response.  In addition, each entry is color coded based on it's status code.  Different colors will show for 301/302, 500+, and 404.

image

When working with the web, you don't always want to see every little thing that happens all the time.  Therefore, by default, you only trace common text specific file like HTML, CSS, JavaScript, JSON, XAML, Text, and SOAP and their content.  If you want to trace images and other things going across, then set "enableVerboseTypeTracing" to true.  However, since there is no need to see the big blob image data, the data of binary types are not sent to the trace viewer even with enableVerboseTypeTracing.  You can also toggle both tracing as well as verbose type tracing on each server as each is running.

There's also the ability to view custom content types without seeing all the images and extra types.  This is the purpose of the <allowedConntetTypes /> configuration block under <requestTracing />, which is parallel to <servers />.

<requestTracing>
  <allowedContentTypes>
    <add value="application/x-custom-type" />
  </allowedContentTypes>
</requestTracing>

In this case, responses of content-type "application/x-custom-type" are also traced without needing to turn on verbose type tracing.

However, there is another way to control this information.  If you want to see all requests, but want the runtime ability to see various content types, then you can use a client-side filter in the request/response list.  In the box immediately above the request/response list, you can type something like the following:

verb:POST;statuscode:200;file:css;contentType:text/css

Filtering will occur as you type, allowing you to find the particular request you are looking for.  The filter is NOT case sensitive.  You can also clear the request/response list with the clear button.  There is also the ability to copy/paste the particular headers that you want from the headers list by using typical SHIFT (for range) and CTRL-clicking (for single choosing).

Request/Response monitoring actually goes a bit further by automatically parsing both ViewState and ControlState for both request (POST) and response data.  Thanks goes to Fritz Onion for granting me permission to use his ViewState parser class in DevServer.

As a Training Tool

When announce any major project I always provide an "as a training tool" section to explain how the project can be used for personal training.  NetFXHarmonics DevServer is built using .NET 3.5 and relies heavily on LINQ and WCF with a WPF interface.  It also uses extensive .NET custom configuration for all server configuration.  In terms of LINQ, you can find many examples of how to use both query expression syntax and extension method syntax.  When people first learn LINQ, they think that LINQ is an O/R mapper.  Well, it's not (and probably shouldn't be usef for that in enterprise applications! there is only one enterprise class O/R mapper: LLBLGen Pro).  LINQ allows Language INtegrated Query in both C# and VB.  So, in DevServer, you will see heavy reliance on LINQ to search List<T> objects and also to transform LINQ database entities to WCF DTOs.

DevServer also relies heavily on WCF for all inner-process communication via named-pipes.  The web servers are actually hosted inside of a WCF service, thus segregating the web server loader from the client application in a very SOA friendly manner.  The client application loads the service and then acts as a client to the service calling on it to start, stop, and kill server instances.  WCF is also used to communicate the HTTP requests inside the web server back to the client, which is itself a WCF service to which the HTTP request is a client.  Therefore, DevServer is an example of how you can use WCF to communicate between AppDomains.

The entire interface in DevServer is a WPF application that relies heavy on WPF binding for all visual information.  All status information is in a collection to which WPF binds.  Not only that all, but all request/response information is also in a collection.  WPF simply binds to the data.  Using WPF, no eventhandling was required to say "on a click event, obtain SelectedIndex, pull data, then text these TextBox instances".  In WPF, you simply have normal every day data and WPF controls bind directly to that data being automatically updated via special interfaces (i.e INotifyPropertyChanged and INotifyCollectionChanged) or the special generic ObservableCollection<T>.

Since the bindings are completely automated, there also needs to be ways to "transform" data.  For example, in the TabItem header I have a little green or red icon showing the status of that particular web server instance.  There was no need to handle this manually.  There is already a property on my web server instance that has a status.  All I need to do is bind the image to my status enumeration and set a TypeConverter which transforms the enumeration value to a specific icon.  When the enumeration is set to Started, the icon is green, when it says "Stopped", the icon is red.  No events are required and the only code required for this scenario is the quick creation of a TypeConverter.

Therefore, DevServer is an example of WPF databinding.  I've heard people say that they are more into architecture and WCF and therefore have no interested in learning WPF.  This statement makes no sense.  If you don't want to mess with UI stuff, you need to learn WPF.  Instead of handing events all over the place and manually setting data, you can do whatever it is you do and have WPF just bind to your data.  When it comes to creating quick client applications, WPF is a much more productive platform than Windows Forms... or even the web!

Links

Architectural Overview: Creating Streamlined, Simplified, yet Scalable WCF Connectivity

Contents

Introduction

One of the most awesome things about WCF is that the concepts scale extremely well.  If you understand the ABCs of WCF, then you can do anything from creating a simple Hello World to a complex sales processing service.  It's all based on having an address, a binding, and a contract.  All the other concepts like behaviors, validators, and service factories are simply supplemental to the core of the system.  When you understand the basics, you have the general essence of all of WCF.

Because of this fully-scalable ABC concept, I'm able to use the same pattern for WCF architecture and development for every solution.  This is really nice because it makes it so that I don't have to wait time designing a new setup every time a new problem comes along.  In this discussion, I would like to demonstrate how you can create your own extremely efficient WCF solution based on my template.  Along the way, you will also learn a few pieces of WCF internals to help you understand WCF better.

Before I begin the explanation though, keep in mind that most concepts mentioned here are demonstrated in my Minima Blog Engine 3.1.  This is my training software demonstrating an enormous world of modern technologies.  It's regularly refactored and often fully re-architected to be in line with newer technologies.  This blog engine relies heavily on WCF as it's a service-oriented blog engine.  Regardless of how many blogs you have (or any other series of "content entries"-- for example, the documentation section of the Themelia web site is Minima), you have a single set of services that your entire organization uses.  If you understand the WCF usage in Minima, you will understand WCF very well.

Now, onto the meat (or salad, for the vegetarians) of the discussion...

Service Structure

On any one of my solutions, you will find a X.Service project and a X.ServiceImpl project where X is the solution "code" (either the solution name or some other word that represents the essence of the solution).  The former is the public .NET project which contains service contracts, data contracts, service configuration, and service clients.  The latter is the private .NET project which contains the service implementations, behaviors, fault management, service hosts, validators, and other service-side-only, black-boxes portions of the service.  All projects have access to the former, only the service itself will ever even know about the latter.

This is a very simple setup based upon a public/private model, like in public key cryptography.  The idea is that everything private is protected with all your might and everything public is released for anyone, within the context of the solution, to see.

For example, below is the Minima.Service project for Minima Blog Engine 3.1.  Feel free to ignore the folder structure, no one cares about that.  Just because I make each folder a namespace with prefixed folder names for exclusions, doesn't mean anyone else in the world does.  I find it to be the most optimal way to manage namespaced and non-namespaced groups, but the point of this discussion is the separation of concerns in the projects.

MinimaService

For the time being, simply notice that data contracts and service contracts are considered public.  Everything else in the file is either meaningless to this discussion or will be discussed later.

Here is the Minima.ServiceImpl project for the same solution:

MinimaServiceImpl

Here you can see anything from the host factory to various behaviors to validators to fault management to LINQ-to-SQL capabilities.  Everything here is considered private.  The outside world doesn't need to know, therefore shouldn't know.

For the sake of a more simplified discussion, let's switch from the full-scale solution example of Minima to a smaller "Person" service example.  This "Person" service is part of the overall "Contact" solution.  Here's the Contact.Service for our Contact solution:

PersonService

As you can see, you have a standard data contract, a service contract, and a few other things, which will be discussed in a bit.

For this example, we don't need validators, fault management, or behaviors, or host factories, all we need is a simple service in our Contact.ServiceImpl project:

PersonServiceImpl

By utilizing this model separating the private from the public you can easily send the Contact.Service assembly to anyone you want without requiring them to create their own client proxy or use the painfully horrible code generated by "Add Service Reference", which ranks in my lists as one of the worst code generators right next to FrontPage 95 and Word 2000.

As a side note, I should mention that I have colleagues who actually take this a step further and make a X.Service.Client project which houses the WCF client classes.  They are basically following a Service/Client/Implementation model where as I'm following a Public/Private model.  Just use which ever model makes sense for you.

The last piece needed in this WCF setup is the host itself.  This is just a matter of creating a new folder for the web site root, adding a web.config, and adding a X.svc file.  Period.  This is the entire service web site.

In the Person service example, the service host has only two files: web.config and Person.svc.

Below is the web.config, which declares two endpoints for the same service.  One of the endpoints is a plain old fashioned ASMX style "basic profile" endpoint and the other is one to be used for JSON connectivity.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.serviceModel>
    <behaviors>
      <endpointBehaviors>
    <behavior name="JsonEndpointBehavior">
      <enableWebScript />
    </behavior>
      </endpointBehaviors>
    </behaviors>
    <services>
      <service name="Contact.Service.PersonService">
    <endpoint address="json" binding="webHttpBinding" contract="Contact.Service.IPersonService" behaviorConfiguration="JsonEndpointBehavior" />
    <endpoint address="" binding="basicHttpBinding" contract="Contact.Service.IPersonService" />
      </service>
    </services>
  </system.serviceModel>
</configuration>

The Person.svc is even most basic:

<%@ ServiceHost Service="Person.Service.PersonService" %>

This type of solution scales to any level.  If you want to add a service, just add a new X.svc file and register as a new service.  If you want to add another endpoint, just add that line.  It's incredibly simple and scales to solutions of any size and even works well with non-HTTP services like netTcpBinding services.

Service MetaData

Now let's look at each of these files to see how they are optimized.  First, lets' look at the data contract, Person:

using System;
using System.Runtime.Serialization;
//+
namespace Contact.Service
{
    [DataContract(Namespace = Information.Namespace.Contact)]
    public class Person
    {
    //- @Guid -//
    [DataMember]
    public String Guid { get; set; }


    //- @FirstName -//
    [DataMember]
    public String FirstName { get; set; }


    //- @LastName -//
    [DataMember]
    public String LastName { get; set; }


    //- @City -//
    [DataMember]
    public String City { get; set; }


    //- @State -//
    [DataMember]
    public String State { get; set; }


    //- @PostalCode -//
    [DataMember]
    public String PostalCode { get; set; }
    }
}

Everything about this file should be self explanatory.  There's a data contract attribute on the class and data member attributes on each member.  Simple.  But what's with the data contract namespace?

Well, earlier this year, a co-architect of mine mentioned to me that you can centralize your namespaces in static locations.  Genius.  No more typing the same namespace on each and every data and service contract.  Thus, the following file is included in each of my projects:

using System;
//+
namespace Contact.Service
{
    public class Information
    {
    //- @NamespaceRoot -//
    public const String NamespaceRoot = "http://www.netfxharmonics.com/service/";


    //+
    //- @Namespace -//
    public class Namespace
    {
        public const String Contact = Information.NamespaceRoot + "Contact/2008/11/";
    }
    }
}

If there are multiple services in a project, and in 95%+ of the situations there will be, then you can simply add more services to the Namespace class and reference them from your data and service contracts.  Thus, you never, EVER have to update your service namespaces in more than one location.  You can see this in the service contract as well:

using System;
using System.ServiceModel;
//+
namespace Contact.Service
{
    [ServiceContract(Namespace = Information.Namespace.Contact)]
    public interface IPersonService
    {
    //- GetPersonData -//
    [OperationContract]
    Person GetPersonData(String personGuid);
    }
}

This service contract doesn't get much simpler.  There's no reason to discuss it any longer.

Service Implementation

For the sake of our discussion, I'm not going to talk very much at all about the service implementation.  If you want to see a hardcore implementation, go look at my Minima Blog Engine 3.1.  You will see validators, fault management, operation behaviors, message headers, and on and on.  You will seriously learn a lot from the Minima project.

For our discussion, here's our Person service:

using System;
//+
namespace Contact.Service
{
    public class PersonService : Contact.Service.IPersonService
    {
    //- @GetPersonData -//
    public Person GetPersonData(String personGuid)
    {
        return new Person
        {
        FirstName = "John",
        LastName = "Doe",
        City = "Unknown",
        Guid = personGuid,
        PostalCode = "66062",
        State = "KS"
        };
    }
    }
}

Not too excited, eh?  But as it is, this is all that's required to create a WCF service implementation.  Just create an every day ol' class and implement a service contract.

As I've mentioned, though, you could do a ton more in your private service implementation.  To give you a little idea, say you wanted to make absolutely sure that no one turned off metadata exchange for your service.  This is something that I do for various projects and it's incredibly straight-forward: just create a service host factory, which creates the service host and programmatically adds endpoints and modified behaviors. Given that WCF is an incredibly streamlined system, I'm able to add other endpoints or other behaviors in the exact same way.

Here's what I mean:

using System;
using System.ServiceModel;
using System.ServiceModel.Description;
//+
namespace Contact.Service.Activation
{
    public class PersonServiceHostFactory : System.ServiceModel.Activation.ServiceHostFactory
    {
    //- @CreateServiceHost -//
    protected override ServiceHost CreateServiceHost(Type serviceType, Uri[] baseAddresses)
    {
        ServiceHost host = new ServiceHost(typeof(PersonService), baseAddresses);
        //+ add metadata exchange
        ServiceMetadataBehavior serviceMetadataBehavior = host.Description.Behaviors.Find<ServiceMetadataBehavior>();
        if (serviceMetadataBehavior == null)
        {
        serviceMetadataBehavior = new ServiceMetadataBehavior();
        host.Description.Behaviors.Add(serviceMetadataBehavior);
        }
        serviceMetadataBehavior.HttpGetEnabled = true;
        ServiceEndpoint serviceEndpoint = host.Description.Endpoints.Find(typeof(IMetadataExchange));
        if (serviceEndpoint == null)
        {
        host.AddServiceEndpoint(typeof(IMetadataExchange), MetadataExchangeBindings.CreateMexHttpBinding(), "mex");
        }
        //+
        return host;
    }
    }
}

Then, just modify your service host line:

<%@ ServiceHost Service="Person.Service.PersonService" Factory="Person.Service.PersonServiceFactory" %>

My point in mentioning that is to demonstrate how well your service will scale based upon a properly setup base infrastructure.  Each thing that you add will require a linear amount of work.  This isn't like WSE where you need three doctorates in order to modify the slightest thing.

Service Client without Magic

At this point, a few of my colleagues end their X.Service project and begin a X.Service.Client class.  That's fine.  Keeping the client away from the service metadata is nice, but its not required.  So, for the sake of this discussion, let's continue with the public/private model instead of the service/client/implementation model.

Thankfully, I have absolutely no colleagues who would ever hit "Add Service Reference".  I've actually never worked with a person who does this either.  This is good news because, as previously mentioned, the code generated by the add service reference is a complete disaster.  You also can't modify it directly without risking your changing being overwritten.  Even then, the code is SO bad, you wouldn't want to edit it.  There's no reason to have hundreds or THOUSANDS of lines of code to create a client to your service.

A much simpler and much more manageable solution is to keep your code centralized and DRY (don't repeat yourself).  To do this, you just need to realize that the publicly accessible X.Service project already contains the vast majority of everything needed to create a WCF client.  Because of this, you may access the service using WCF's built in mechanisms.  You don't need anything fancy, it's all built right in.

Remember, WCF simply requires the ABC: and address, binding, and contract.  On the client-side, WCF uses this information to create a channel.  This channel implements your service contract, thus allowing you to directly access your WCF service without any extra work required.  You already have the contract, so you just have to do is declare the address and binding.  Here's what I mean:

//+ address
EndpointAddress endpointAddress = new EndpointAddress("http://localhost:1003/Person.svc");
//+ binding
BasicHttpBinding basicHttpBinding = new BasicHttpBinding();
//+ contract
IPersonService personService = ChannelFactory<IPersonService>.CreateChannel(basicHttpBinding, endpointAddress);
//+ just use it!
Person person = personService.GetPersonData("F488D20B-FC27-4631-9FB9-83AF616AB5A6");
String firstName = person.FirstName;

No 3,000 line client generated code, no excess classes, no configuration.  Just direct access to your side.

Of course, if you want to use a configuration file, that's great too.  All you need to do in create a system.serviceModel section in your project or web site and declare your service endpoint.  What's really nice about this in WCF is that, since the concept for WCF are ABC on both the client and server, most of the configuration is already done for you.  You can just copy and paste the endpoint from the service configuration to your client configuration and add a name element.

<system.serviceModel>
  <client>
    <endpoint name="PersonServiceBasicHttpBinding" address="http://localhost:1003/Person.svc" binding="basicHttpBinding" contract="Simple.Service.IPersonService" />
  </client>
</system.serviceModel>

For the most part, you will also need to keep any bindings on the service side as well, though you wouldn't copy over validation information.

At this point you can just change the previously used WCF channel code to use an endpoint, but that's an architectural disaster.  You never want to compile configuration information into your system.  Instead of tying them directly, I like to create a custom configuration for my solution to allow the endpoint configuration to change.  For the sake of this discussion though, let's just use appSettings (do NOT rely on appSettings for everything!  That's a cop-out.  Create a custom configuration section!).  Here's our appSetting:

<appSettings>
  <add key="PersonServiceActiveEndpoint" value="PersonServiceBasicHttpBinding" />
</appSettings>

At this point, I can explain that Configuration class found in the public Contact.Service project:

using System;
//+
namespace Contact.Service
{
    public static class Configuration
    {
    //- @ActivePersonServiceEndpoint -//
    public static String ActivePersonServiceEndpoint
    {
        get
        {
        return System.Configuration.ConfigurationManager.AppSettings["PersonServiceActiveEndpoint"] ?? String.Empty;
        }
    }
    }
}

As you can see, this class just gives me strongly-typed access to my endpoint name.  Thus allowing me to access my WCF endpoint via a loosely connected configuration:

//+ configuration and contract
IPersonService personService = new ChannelFactory<IPersonService>(ServiceConfiguration.ActivePersonServiceEndpoint).CreateChannel();
//+ just use it!
Person person = personService.GetPersonData("F488D20B-FC27-4631-9FB9-83AF616AB5A6");
String firstName = person.FirstName;

When I feel like using a different endpoint, I don't modify the client endpoint, but just add another one with a new name and update the appSettings pointer (if you're info fancy names, this is essentially the bridge pattern).

Now, while this is a great way to directly access data by people who understand WCF architecture, it's probably not a good idea to allow your developers to have direct access to system internals.  Entry-level developers need to focus on the core competency of your company (i.e. sales, marketing, data management, etc), not ponder the awesomeness of system internals.  Thus, to allow other developers to work on a solution without having to remember WCF internals, I normally create two layers of abstraction on top of what I've already shown.

For the first layer, I create a concrete ClientBase class to hide the WCF channel mechanics.  This is the type of class that "Add Service Reference" would have created if your newbie developers accidentally used it.  However, the one we will create won't have meaningless attributes and virtually manageable excess code.

Below is our entire client class:

using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
//+
namespace Contact.Service
{
    public class PersonClient : System.ServiceModel.ClientBase<IPersonService>, IPersonService
    {
    //- @Ctor-//
    public PersonClient(String endpointConfigurationName)
        : base(endpointConfigurationName) { }


    //+
    //- @GetPersonData -//
    public Person GetPersonData(String personGuid)
    {
        return Channel.GetPersonData(personGuid);
    }
    }
}

The pattern here is incredibly simple: create a class which inherits from System.ServiceModel.ClientBase<IServiceContractName> and implements your service contract.  When you implement the class, the only implementation you need to add is a call to the base channel.  In essence, all this class does is accept calls and pass them off to a pre-created channel.  When you add a new operation to your service contract, just implement the interface and add a single line of connecting code to wire up the client class.

The channel creation mechanics that I demonstrated earlier is now done provided automatically by the ClientBase class.  You can also modify this class a little by bridging up to a total of 10 different constructors provided by ClientBase.  For example, the following constructor call will allow developers to specify a specific binding and endpoint:

public PersonClient(Binding binding, EndpointAddress address)
    : base(binding, address) { }

At this point, we have something that protects developers from having to remember how to create a channel.  However, they still have to mess with configuration names and must remember to dispose this client object (there's an open channel, remember).  Therefore, I normally add another layer of abstraction.  This one will be directly accessibly for developer user.

This layer consists of a series of service agents.  Each service has its own agent and is essentially a series of static methods which provide the most efficient means of making a service call.  Here's what I mean:

using System;
//+
namespace Contact.Service
{
    public static class PersonAgent
    {
    //- @GetPersonData -//
    public static Person GetPersonData(String personGuid)
    {
        using (PersonClient client = new PersonClient(ServiceConfiguration.ActivePersonServiceEndpoint))
        {
        return client.GetPersonData(personGuid);
        }
    }
    }
}

As you can see, the pre-configured service endpoint is automatically used and the PersonClient is automatically disposed at the end of the call (ClientBase<T> implements IDisposable).  If you want to use a different service endpoint, then just change it in your appSettings configuration.

Conclusion

At this point, I've explained every class or each project in my WCF service project model.  It's up to you to decide how to best create and manage your data and service contracts as well as clients.  But, if you want a streamlined, efficient, model for all your service projects, you will want to create a publicly accessible project to house all your reusable elements.

Also, remember you don't need a full-on client class to access a service.  WCF communicates with channels and channel creation simply requires an address, binding, and contract.  If you have that information, just create your channel and make your call.  You can abstract the internals of this by using a ClientBase object, but this is entirely optional.  If the project you are working on requires hardcore WCF knowledge, there's no reason to pretty it up.  However, if non-WCF experts will be working with your system, abstractions are easy to create.

Links

Love Sudoku?  Love competition?  Try the new Sudokian.com experience today.

Understanding WCF



If you like this document, please consider writing a recommendation for me on my LinkedIn account.

Contents

Introduction

One of the most beautiful things about the Windows Communication Foundation (WCF) is that it's a completely streamlined technology.  When you can provide solutions to myriad of diverse problems using the same principles, you know you're dealing with a work of genius.  This is the case with WCF.  With a single service implementation, you can provide access to ASMX, PHP, Java, TCP, named pipe, and JSON-based services by add a single XML element for each type of connection you want to support.  On the flip side, with a single WCF client you can connect to each of these types of services, again, by adding a single like of XML for each.  It's that simple and streamlined.  Not only that, this client scenario works the same for both .NET and Silverlight.

In this document, I'm going to talk about how to access WCF services using Silverlight 2 without magic.  There will be no proxies, no generated code, no 3rd party utilities, and no disgusting "Add Service Reference" usage.  Just raw WCF.  This document will cover WCF connectivity in quite some depth.  We will talk about service setup, various WCF, SOA, and Silverlight paradigms, client setup,  some security issues, and a few supplemental features and techniques to help you aide and optimize service access.  You will learn about various WCF attributes, some interfaces, and a bunch of internals.  Though this document will be in depth, nothing will ever surpass the depth of MSDN.  So, for a more full discussion on any topic, see the WCF documentation on MSDN.

Even though we're focusing on Silverlight, most of what will be explained will be discussed in a .NET context and then applied to Silverlight 2.  That is, instead of learning .NET WCF and Silverlight WCF, you will .NET WCF and how to vary this for Silverlight.  This comparative learning method should help you both remember and understand the concepts better.  Before we begin, though, let's begin with a certain WCF service setup.  After all, we you don't have a service, we can't talk about accessing it.

Service Setup In Depth

When working with WCF, you are working with a completely streamlined system.  The most fundamental concept in this system is the ABC.  This concept scales from Hello World to the most complex sales processing system.  That is, for all WCF communication, you need an address, a binding, and a contract.  Actually, this is for any communication anywhere, even when talking to another person.  You have to know to whom, how, and what.  If you don't have these three, then there can't be any communication.

With these three pieces of information, you either create a service-side endpoint which a client will access or a client-side channel which the client will use to communicate with the service.

WCF services are setup using a 3 step method:

  • First, create a service contract with one or more operation contracts.
  • Second, create a service implementation for those contracts. 
  • Third, configure a service host to provide that implementation with an endpoint for that specific contract.

Let's begin by defining a service contract.  This is just a simple .NET interface with the System.ServiceModel.ServiceContractAttribute attribute applied to it.  This interface will contain various operation contracts, which are simply method signatures with the System.ServiceModel.OperationContractAttribute applied to each.  Both of these attributes are in the System.ServiceModel assembly.

Do not under any circumstances apply the ServiceContract attribute directly to the implementation (i.e. the class).  The ability to do this is probably the absolute worst feature in WCF.  It defeats the entire purpose of using WCF: your address, your binding, your contract and your implementation are complete separate.  Because this essentially makes your implementation your contract, all your configuration files will be incredibly confusing to those of us who know WCF well.  When I look for a contract, I look for something that starts with an "I".  Don't confuse me with "PersonService" as my contract.  Person service means person… service.  Not only that, but later on you will see how to use a contract to access a service.  It makes no sense to have my service access my service; thus with the implementation being the contract, your code will look painfully confusing to anyone who knows WCF.

Here's the sample contract that we will use for the duration of this document:

using System;
using System.ServiceModel;
//+
namespace Contact.Service
{
    [ServiceContract(Namespace = Information.Namespace.Contact)]
    public interface IPersonService
    {
        //- GetPersonData -//
        [OperationContract]
        Person GetPersonData(String personGuid);
    }
}

Keep in mind that when you design for WCF, you need to keep your interfaces as simple as possible.  The general rule of thumb is that you should have somewhere between 3 to 7 operations per service contract.  When you hit the 12-14 mark, it's seriously time to factor out your operations.  This is very important.  As I'll mention again later, in any one of my WCF projects I'll have upwards of dozens of service contracts per service.  You need to continuously keep in mind what your purpose is for creating this service, filtering those purposes through the SOA filter.  Don't design WCF services like you would a framework, which, even then shouldn't have many access points!

The Namespace property set on the attribute specified the namespace used to logically organize services.  Much like how .NET uses namespaces to separate various classes, structs, and interfaces, SOAP services use namespaces to separate various actions.  The name space may be arbitrarily chosen, but the client and service must just agree on this namespace. In this case, the namespace is the URI http://www.netfxharmonics.com/service/Contact/2008/11/.  This namespace will also be on the client.  This isn't a physical URL (universal resource locator), but a logical URI (universal resource identifier).  Despite what some may say, both terms are in active use in daily life.  Neither is more important than the other and neither is "deprecated".  All URLs are URIs, but not all URIs are URLs as you can see here.

Notice in this interface, there is a method interface that returns Person.  This is a data contract.  Data contracts are classes which have the System.Runtime.Serialization.DataContractAttribute attribute applied to them.  These have one or more data members, which are public or private properties or fields that have the System.Runtime.Serialization.DataMemberAttribute attribute applied to them.  Both of these attributes are in the System.Runtime.Serialization assembly.  This is important to remember; if you forget, you will probably assume them to be in the System.ServiceModel assembly and your contract will never compile.

Notice I said that data members are private or public properties or fields.  That was not a typo.  Unlike the serializer for the System.SerializableAttribute attribute, the serializer for DataContract attribute allows you to have private data members.  This allows you to hide information from developers, but allow services to see it.  Related to this is the how classes with the DataContract attribute differ from classes with the Serializable attribute.  When you use the Serializable attribute, you are using an opt-out model.  This means that when the attribute is applied to the class, each members is serializable.  You then opt-out particular fields (not properties; thus one major inflexibility) using the System.NonSerializedAttribute attribute.  On the other hand, when you apply the DataContract attribute, you are using an opt-in model.  Thus, when you apply this attribute, you must opt-in each field or property you wish to be serialized by applying the DataMember attribute.  Now to finally look at the Person data contract:

[DataContract(Namespace = Information.Namespace.Contact)]
public class Person
{
    //- @Guid -//
    [DataMember]
    public String Guid { get; set; }


    //- @FirstName -//
    [DataMember]
    public String FirstName { get; set; }


    //- @LastName -//
    [DataMember]
    public String LastName { get; set; }


    //- @City -//
    [DataMember]
    public String City { get; set; }


    //- @State -//
    [DataMember]
    public String State { get; set; }


    //- @PostalCode -//
    [DataMember]
    public String PostalCode { get; set; }
}

Note how simple this class is.  This is incredibly important.  You need to remember what this class represents: data moving over the wire.  Because of this, you need to make absolutely sure that you are sending only what you need.  Just because your internal "business object" has 10,000 properties doesn't mean that your service client will ever be able to handle it.  You can't get blood from a turnip.  Your business desires will never change the physics of the universe.  You need to design with this specific scenario of service-orientation in mind.  In the case of Silverlight, this is even more important since you are dealing with information that needs to get delegated through a web browser before the plug-in ever sees it.  Not only that, but every time you send an extra property over the wire, you are making your Silverlight application that less responsive.

When I coach architects on database design, I always remind them to design for the specific system which they'll be using (i.e. SQL Server) and always keep performance, space, and API usability in mind (this is why it's the job of the architect, not the DBA, to design databases!)  In the same way, if you are designing a system that you know will be used over the wire, account for that scenario ahead of time.  Much like security, performance and proper API design aren't "features", they're core parts of the system.  Do not design 10 different classes, each representing a property which will be used in another class which, in turn, will be serialized and sent over the wire.  This will be so absolutely massive that no one will ever be able to handle it.  If you have more than around 15 properties in your entire object graph, it's seriously time to rethink what you want to send.  And, never, ever, ever send an instance of System.Data.DataSet over the wire.  There has never been, is not now, and never will be any reason to ever send any instance of this type anywhere.  It's beyond massive and makes the 10,000 property data transfer object seem lightweight.  The fact that something is serializable doesn't mean that it should be.

This is main reason you should not apply the Serializable attribute to all classes.  Remember, this attribute follows an opt-out model (and a weak one at that).  If you want your "business objects" to work in your framework as well as over the wire, you need to remove this attribute and apply the DataContract attribute.  This will allow you to specify via the DataMember attribute which properties will be used over the wire, while leaving your existing framework completely untouched.  This is the reason the DataContract attribute exists!  Microsoft realized that the Serializable attribute is not fine grained enough for SOA purposes.  They also realized that there's no reason to force everyone in the world to write special data transfer objects for every operation.  Even then, use DataContract sparingly.  Just as you should keep as much private as possible and as much internal as possible, you want to keep as much un-serializable as possible.  Less is more.

In my Creating Streamlined, Simplified, yet Scalable WCF Connectivity document, I explain that these contracts are considered public.  That is, both the client and the service need the information.  It's the actual implementation that's private.  The client needs only the above information, where as the service needs the above information as well as the service implementation.  Therefore, as my document explains, everything mentioned above should be in a publicly accessible assembly separate from the service implementation to maximize flexibility.  This will also allow you to rely on the original contracts instead of relying on a situation where the contracts are converted to metadata over the wire and then converted to sloppily generated contracts.  That's slower, adds latency, adds another point of failure, and completely destroys your hand crafted, highly-optimized contracts.  Simply add a reference to the same assembly on both the client and server-side and you're done.  If multiple people are using the service, just hand out the public assembly.

At this point, many will try to do what I've just mentioned in a Silverlight environment to find that it doesn't seem to work.  That is, when you try to add a reference to a .NET assembly in a Silverlight project, you will get the following error message:

DotNetSilverlightReferenceMessageBox

Fortunately, this isn't the end of the world.  In my document entitled Reusing .NET Assemblies in Silverlight, I explain that this is only a Visual Studio 2008 constraint.  There's absolutely no technical reason why Silverlight can't use .NET assemblies.  Both the assembly and module formats are the same for Silverlight and .NET.  When you try to reference an assembly in a Silverlight project, Visual Studio 2008 does a check to see what version of mscorlib the assembly references.  If it's not 2.X.5.X, then it says it's not a Silverlight assembly.  So, all you need to do is modify your assembly to have it use the appropriate mscorlib file.  Of course, then it's still referencing the .NET System.ServiceModel and System.Runtime.Serialization assemblies.  Not a big deal, just copy/paste the Silverlight references in.  My aforementioned document explains everything you need to automate this procedure.

Therefore, there's no real problem here at all.  You can reuse all your contracts on both the service-side and on the client-side in both a .NET Silverlight environment.  As you will see a bit later, Silverlight follows an async communication model and, therefore, must use async-compatible service contracts.  At that time you may begin to think that you can't simply have a one-stop shop for all your contract needs.  However, this isn't the case.  As it turns out .NET can do asynchronous communication too, so when you create that new contract, you can keep it right next to your original service contract.  Thus, once again, you have a single point where you keep all your contracts.

Moving on to step 2, we need to use these contracts to create an implementation.  The service implementation is just a class which implements a service contract.  The service implementation for our document here is actually incredibly simple:

using System;
//+
namespace Contact.Service
{
    public class PersonService : Contact.Service.IPersonService
    {
        //- @GetPersonData -//
        public Person GetPersonData(String personGuid)
        {
            return new Person
            {
                FirstName = "John",
                LastName = "Doe",
                City = "Unknown",
                Guid = personGuid,
                PostalCode = "66062",
                State = "KS"
            };
        }
    }
}

That's it.  So, if you already have some logic you know is architecturally sound and you would like to turn it into a service.  Create an interface for your class and add some attributes to the interface.  That's your entire service implementation.

Step 3 is to configure a service host with the appropriate endpoints.  In our document, we are going to be using an HTTP based service.  Thus after we setup a new web site, we create a Person.svc file in the root and add to it a service directive specifying our service implementation.  Here's the entire Person.svc file:

<%@ ServiceHost Service="Contact.Service.PersonService" %>

No, I'm not joking.  If you keep your implementation in this class as well, then you are not using WCF properly.  In WCF, you keep your address, your binding, your contract, and your implementation completely separate.  By putting your implementation in this file, you are essentially tying the address to the implementation.  This defeats the entire purpose of WCF.  So, again, the above code is all that should ever be in any svc file anywhere.  Sometimes you may have another attribute set on your service directive, but this is basically it.

This is an unconfigured service host.  Thus, we must configure it.  We will do this in the service web site's web.config file.  There's really only one step to this, but that one step has a prerequisite.  The step is this: setup a service endpoint, but this requires a declared service.  Thus, we will declare a service and add it to an endpoint.  An endpoint specifies the WCF ABC: an address (where), a binding (how), and a contract (what).  Below is the entire web.config file up to this point:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.serviceModel>
    <services>
      <service name="Contact.Service.PersonService">
        <endpoint address="" binding="basicHttpBinding" contract="Contact.Service.IPersonService" />
      </service>
    </services>
  </system.serviceModel>
</configuration>

This states that there can be "basicHttpBinding" communication through Contact.Service.IPersonService at address Person.svc to Contact.Service.PersonService.  Let's quickly cover each concept here.

The specified address is a relative address.  This means that the value of this attribute is appended onto the base address.  In this case the base address is the address specified by our web server.  In the case of a service outside of a web server, then you can specify an absolute address here.  But, remember, when using a web server, the web server is going to control the IP address and port bindings.  Our service is at Person.svc, thus we have already provided for us the base URL.  In this case the address is blank, but you will use this address attribute if you add more endpoints as you will see later.

The binding specifies how the information is to be format for transfer.  There's actually nothing too magical about a binding, though.  It's really just a collection of binding elements and pre-configured parameter defaults, which are easily changed in configuration.  Each binding element will have at a minimum two binding elements.  One of these is a message encoding binding element, which will specify how the message is formatted.  For example, the message could be text (via the TextMessageEncodingBindingElement class; note: binding elements are in the System.ServiceModel.Channels namespace), binary (via the BinaryMessageEncodingBindingElement class), or some other encoding.  The other required binding element is the transport binding element, which specified how the message is to go over the wire.  For example, the message could go over HTTP (via the HttpTransportBindingElement), HTTPS (via the HttpsTransportBindingElement), TCP (via the TcpTransportBindingElement), or even a bunch of others.  A binding may also have other binding elements to add more features.  I'll mention this again later, when we actually use a binding.

The last part of an endpoint, the contract, has already been discussed earlier.  One thing that you really need to remember about this though is that you are communication through a contract to the hosted service.  If you are familiar with interface based development in .NET or COM, then you already have a strong understanding of what this means.  However, let's review.

If a class implements an interface, you can access the instantiated object through the interface.  For example, in the following code, you are able to access the Dude object through the ISpeak interface:

interface ISpeak
{
    void Speak(String text);
}


class Dude : ISpeak
{
    public void Speak(String text)
    {
        //+ speak text
    }
}


public class Program
{
    public void Run()
    {
        ISpeak dude = new Dude();
        dude.Speak("Hello");
    }
}

You can think of accessing a WCF service as being exactly like that.  You can even push the comparison even further.  Say the Dude class implemented IEat as well.  Then we can access the instantiated Dude object through the IEat interface.  Here's what I mean:

interface ISpeak
{
    void Speak(String text);
}


interface IEat
{
    void Eat(String nameOfFood);
}


class Dude : ISpeak, IEat
{
    public void Speak(String text)
    {
        //+ speak text
    }
}


public class Program
{
    public void Run()
    {
        IEat dude = new Dude();
        dude.Eat("Pizza");
    }
}

In the same way, when configuring a WCF service, you will add an endpoint for contract through which you would like your service to be accessed.

Though it's beyond the scope of this document, WCF also allows you to version contracts.  Perhaps you added or removed a parameter from your contract.  Unless you want to break all the clients accessing the service, you must keep the old contract applied to your service (read: keep the old interface on the service class) and keep the old endpoint running by setting up a parallel endpoint.

You will add a new service endpoint every time you change your version, change your contract, or change your binding.  On a given service, you have have dozens of endpoints.  This is good thing.  Perhaps you provide for four different bindings with two of them having two separate configurations each, three different contracts, and 2 different versions of one of the contracts.  In this document, we are going to start out with one endpoint and add more later.

Now we have setup a complete service.  However, it's an incredibly simple service setup, thus not requiring too much architectural attention.  When you work with WCF in a real project, you will want to organize your WCF infrastructure to be a bit more architecturally friendly.  In my document entitled Creating Streamlined, Simplified, yet Scalable WCF Connectivity, I explain streamlining and simplifying WCF connectivity and how you can use a private/public project model to simplify your

Understanding WCF Faults in Silverlight



If you like this document, please consider writing a recommendation for me on my LinkedIn account.

Contents

Introduction

Regardless of what platform you are working with, you need some mechanism for dealing with errors.  When it comes to using WCF in Silverlight we are all very fortunate to be able to build out solutions on the back of many tried and true techniques for error management. When working in this context, we are dealing with basic SOAP messages (that is, XML) and WCF's abstraction of those messages, neither of which are new to the world.

If you haven't done so already, you should read the first part of this document entitled Understanding WCF Services in Silverlight (here after "previous document").  You may consider this document an appendix to that one.  That document explains WCF and its integration into the world of Silverlight from a very low level. This document extends that one to explain error management in the world of Silverlight 3. Understanding of the previous document is a prerequisite for understanding this one.

SOAP Review

Before we take a look at error management over SOAP services, we will take a moment to review SOAP messaging. SOAP messaging is based on the concept of sending SOAP messages back and forth between client and service. A SOAP message is the package by which a client and a service communicate. Web services (a.k.a. SOAP services) are not "connected" like a chat channel. Instead, they are "disconnected" like an e-mail system. The client sends the service a message and the service, optionally, sends the client message back (depending on if the client requested a message; one way messaging is very common). Below is a sample message sent from a client to the service:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetPersonData xmlns="http://www.netfxharmonics.com/service/Contact/2009/07/">
      <personGuid>F488D20B-FC27-4631-9FB9-83AF616AB5A7</personGuid>
    </GetPersonData>
  </s:Body>
</s:Envelope>

Essentially, this message is calling the "GetPersonData" operation on the service, sending "personGuid" as a parameter. This is stored in the message body (which is distinct from, say, a message header, which is not present in this example). The body is then stored in an envelope. When this message is sent via an HTTP POST to, for example, /Person.svc with the SOAP-Action HTTP header set to the name of the SOAP operation, WCF calls the appropriate operation (set by the SOAP-Action HTTP header).  For more information on the mechanics of WCF and how to work with WCF directly see my XmlHttp Service Interop series at http://www.netfxharmonics.com/2007/05/XmlHttp-Service-Interop-Part-3-XML-Serialization).

Here is a message the service could possibly send back to the client:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetPersonDataResponse xmlns="http://www.netfxharmonics.com/service/Contact/2008/11/">
      <GetPersonDataResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <City>Unknown</City>
        <FaultDetail i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/General.Service"/>
        <FirstName>John</FirstName>
        <Guid>89DEA4C5-84A0-45db-A60D-CE49F214EA50</Guid>
        <LastName>Doe</LastName>
        <PostalCode>66062</PostalCode>
        <State>KS</State>
      </GetPersonDataResult>
    </GetPersonDataResponse>
  </s:Body>
</s:Envelope>

Here we have the data for "GetPersonData" in a result object, wrapped in a response container. This is then, once again, wrapped in a standard SOAP body, inside a standard SOAP envelope. Pretty simple stuff. Someone sends a message, the receiver sends something back. The question now becomes... what happens when something goes wrong?

Handling Errors

When doing error management with SOAP-based WCF, you are doing just that: error management. You are NOT doing exception management. Exceptions don't exist over the wire. How can an exception from WCF being handled by a PHP client? How can System.InvalidOperationException be handled by a Java client? These scenarios make no sense. Therefore, in the world of SOAP services, you have no exceptions. Instead, you have a concept called a "fault".  A fault is a SOAP error.  WCF, Java, and PHP can all deal with SOAP (since SOAP is just XML), thus, they each can deal with faults with no problem. Given this, we may adjust our terminology at this point from "error management" to "fault management".

In reality, a fault is nothing more than a piece of XML formatted in a specific way. One side sends it, the other side receives it. It's a really simple setup. (As a side note, please keep in mind that this is not a document on the internal mechanics of SOAP. That's a discussion for a different document. Fortunately, though, the understanding of faults in SOAP doesn't require deep SOAP knowledge.)

When an exception is thrown in a SOAP-based WCF service, typically a fault is sent over the wire. A SOAP-based client (be it WCF, WCF in Silverlight, PHP, or Java), then obtains it, parses it and handles it accordingly. So what's a SOAP fault look like? (you'll see later that this is an example of a very poor practice, but it's a good fault example.)

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <s:Fault>
      <faultcode>s:Client</faultcode>
      <faultstring xml:lang="en-US">Really descriptive message here.</faultstring>
      <detail>
        <InvalidOperationException xmlns="http://schemas.datacontract.org/2004/07/System" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:x="http://www.w3.org/2001/XMLSchema">
          <ClassName i:type="x:string" xmlns="">System.InvalidOperationException</ClassName>
          <Message i:type="x:string" xmlns="">Really descriptive message here.</Message>
          <Data i:nil="true" xmlns=""/>
          <InnerException i:nil="true" xmlns=""/>
          <HelpURL i:nil="true" xmlns=""/>
          <StackTraceString i:nil="true" xmlns=""/>
          <RemoteStackTraceString i:nil="true" xmlns=""/>
          <RemoteStackIndex i:type="x:int" xmlns="">0</RemoteStackIndex>
          <ExceptionMethod i:nil="true" xmlns=""/>
          <HResult i:type="x:int" xmlns="">-2146233079</HResult>
          <Source i:nil="true" xmlns=""/>
        </InvalidOperationException>
      </detail>
    </s:Fault>
  </s:Body>
</s:Envelope>

Notice that even this fault is a SOAP message: the contents are in a SOAP body, wrapped in a SOAP envelope. So, all we really did is use a concept we already knew and added something to it. By sending a "Fault" XML element in a message body, you are effectively telling the client that some error occurred on the service-side. This is a well-known pattern that all SOAP services follow.

If you look closely at this SOAP message (which, of course, is also a fault), you will notice that the "Fault" element has three children: "faultcode", "faultstring" and "detail". You may recognize some parts of this specific fault.  That is, you see the name "InvalidOperationException" as well as the "Message", "InnerException", and other elements as well-known properties of exceptions. Keep in mind, though, that none of these have anything to do with faults. These are in the "detail" section of the fault, not in any part that actually matters.  Clear as mud?

Faults don't rely on the detail element. The information in this block is simply for the end developer to obtain custom information. Since WCF doesn't rely on this information, neither should you (i.e. it won’t always be there). A fault is defined by the "faultstring" element, not the "detail" element. The "faultstring" element contains is the actually message that you will want to look at when debugging.

Not even the "faultcode" element isn’t directly used by most people. This is a well-defined enumeration with the possible values of "Client", "Server", "VersionMismatch", and "MustUnderstand" (prefixed with the XML namespace). These help you to get some idea of the category of error that occurred, but, in the majority of cases, you won't be working with it directly.  This is all to reinforce the fact that it’s faultstring that contains the actual error, not faultcode or details.

Applying to WCF

In the world of WCF for .NET, all of this is essentially internal mechanics that most mid-level or entry-level developers will only see on a senior-level developer's whiteboard (i.e. they won't use it directly). This is because WCF knows to look for faults and knows how to handle them: it will take the content from faultstring and set that as the Message in a System.ServiceModel.FaultException object. This instance of a FaultException object is developers directly work with.

Now pay attention very closely: you can't just throw an exception in a WCF service and expect it to show up on your client (or to show up over the wire for that matter!) Why is this? Thikn about it... do you really want an exception which contains the entire stack trace and, therefore, a snapshot of the private internal mechanics of your system thrown to a client computer? Obviously not. Since WCF knows is a horrible security violation to send stack traces over the wire, it's not going to allow this.  In fact, that fault SOAP-message shown early is hopefully a picture from fiction, not reality (you kind of figured there were a lot of unneeded xml elements, didn't you?)

What you actually do, is you throw one of two special exceptions: System.ServiceModel.FaultException or System.ServiceModel.FaultException<T> (which inherits from the first one). When you throw an exception which isn't one of these, like System.InvalidOperationException, you will see the following over the wire (i.e. throw new System.InvalidOperationException("This is my error message.")):

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <s:Fault>
      <faultcode xmlns:a="http://schemas.microsoft.com/net/2005/12/windowscommunicationfoundation/dispatcher">a:InternalServiceFault</faultcode>
      <faultstring xml:lang="en-US">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 &lt;serviceDebug&gt; 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.</faultstring>
    </s:Fault>
  </s:Body>
</s:Envelope>

You may think "not pretty". Trust me, that IS pretty. Ugly would be showing your internal stack trace over the wire. Thank you WCF for protecting us from ourselves.

Now, if you throw System.ServiceModel.FaultException instead of System.InvalidOperationException (i.e. throw new System.ServiceModel.FaultException("This is my error message."), you will see this:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <s:Fault>
      <faultcode>s:Client</faultcode>
      <faultstring xml:lang="en-US">This is my error message.</faultstring>
    </s:Fault>
  </s:Body>
</s:Envelope>

Very simple and to the point. You told it "This is my error message." and it sent "This is my error message." Can't get much simpler than that.  In fact, the simplicity stays even when you work with the exception on the client side.  Over there, the client will also have a FaultException.  The “faultstring” from the SOAP message will be places into the Message property of the FaultException object on the client.  An example of this will be shown in a bit.

Let's make this a bit more complex (read: more useful/powerful) by changing things up slightly.

As I've said, there are two fault exception types in WCF: one generic, one not. Use of the generic one allows you to send more information to the client by allowing entire objects to be serialized over the wire as part of the fault "detail" element. To see an example of this, take a look at the following custom type:

namespace Contact.Service
{
    [DataContract]
    public class FaultDetail
    {
        //- @ErrorCode -//
        /// <summary>
        /// Custom business-specific error code.
        /// </summary>
        [DataMember]
        public Int32 ErrorCode { get; set; }
        //- @Type -//
        /// <summary>
        /// Specifies the type of error.
        /// </summary>
        [DataMember]
        public String Type { get; set; }
    }
}

Now, instead of throwing the non-generic fault exception, let's throw the generic one, using the above type as the generic parameter. For example:

//- @GetPersonData -//
public Person GetPersonData(String personGuid)
{
    //+ ...validation here...     
    FaultDetail faultDetail = new FaultDetail
    {
        Type = "Validation",
        ErrorCode = 63873928
    };     //+ throw     
    throw new FaultException<FaultDetail>(faultDetail, "Invalid guid.");
    //+ ...more logic here...
}

Given this, we now have this over the wire:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <s:Fault>
      <faultcode>s:Client</faultcode>
      <faultstring xml:lang="en-US">Invalid guid.</faultstring>
      <detail>
        <FaultDetail xmlns="http://schemas.datacontract.org/2004/07/Contact.Service" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
          <ErrorCode>63873928</ErrorCode>
          <Type>Validation</Type>
        </FaultDetail>
      </detail>
    </s:Fault>
  </s:Body>
</s:Envelope>

As you can see, using the generic FaultException type, you can send all kinds of stuff over the wire.

Fault Contracts

While this is great for dynamically typed systems (i.e. PHP and JavaScript), we don't yet have a complete solution for strong-typed ones (i.e. .NET). What’s that? Again, think about it: How does the other end know what type is "FaultDetail". Is that ABCCorp.Web.FaultDetail? ABCCorp.Service.FaultDetail? What's the namespace? In what assembly?

To make this happen in .NET, we have to introduce something called a "fault contract". As you recall from the previous document, WCF has service contracts and operation contracts. Fault contracts are just another contract type in the contact family.

These are setup by applying the System.ServiceModel.FaultContractAttribute attribute to various operations of your service contract.  When you apply this attribute, you must tell it what type you would like to allow to be thrown from that specific operation.  This is simply done by giving the constructor of the fault contract attribute to type object of your fault detail type.  For example, below is our operation contract with the fault contract applied.

//- GetPersonData -//
[OperationContract]
[FaultContract(typeof(FaultDetail))]
Person GetPersonData(String personGuid);

If you're following along and paying close attention you should be thinking "How in the WORLD does that help the client? This is on the server! The same SOAP data is going to come over the wire and the client has no more information." Well, as you recall from the previous document, the contracts must be both on the service-side and on the client-side. In the case of .NET, these are the same types since the contracts are in an assembly shared by both client and service (remember, use of the "Add Service Reference" for .NET-to-.NET communication provides ZERO value and only complicates life).

So, if you are doing .NET-to-.NET, your client contract DOES have this and WCF on the client will automatically know to use that spe

Understanding WCF Versioning ("My Random Notes" Edition)

I never got around to putting the following into something pretty and eloquent... and might not blog any more, but here are my raw notes I would have used to write something more full.


WCF Service Contract Versioning

Clients calls a service interface, not an implemenation. It identifies a particular interface via the WCF namespace set on the service contract on the service. As long as the client calls an interface with a particular namespace on the service side, the call will be allowed.

Strong Versioning

For example, if a client is using the following service contract, it can only call this contract using its full XML namespace. The namespace is specified with the Namespace property of the ServiceContract attribute. However, the interface that is called is the specified namespace suffixed with the interface name. This gives a feel very similar to that of .NET's namespace system which allows for namespaces for organization and full types as the types namespace suffixed with the type name.

As an example, see the following interface is accessed via the "http://www.abccorp.com/services/sample01/2007/02/IServiceV1" identifier.

[ServiceContract(Namespace="http://www.abccorp.com/services/sample01/2007/01")]
public interface IServiceV1
{
    [OperationContract]
    String GetData(Int32 value);
}

If, however, the month portion of a namespace is changed from version 01 to 02, as the following example demonstrate, the client would immediately break as it would still be calling via the old identifier.

[ServiceContract(Namespace="http://www.abccorp.com/services/sample01/2007/02")]
public interface IServiceV1
{
    [OperationContract]
    String GetData(Int32 value);
}

On the service-side there is no "magic" that allows one service to be access over another. The client accesses a specific interface and that specific iterface is of course assigned as a WCF endpoint. Therefore, each version requires it's own endpoint. However, an endpoint doesn't mean another entire host, power, or base URI. In an HTTP environment, this simply means that the endpoint identifier is suffixed to the actual service URI.

For example, instead an address of "" (blank), the address is an arbitrary endpoint identifier as seen below:

Before

<endpoint address="" binding="basicHttpBinding" contract="IService" />

After

<endpoint address="v1" binding="basicHttpBinding" contract="IServiceV1" />
<endpoint address="v2" binding="basicHttpBinding" contract="IServiceV2" />

This will be mentioned in a bit more detail in a later section.

Lax Versioning

Assume the following service service contract, implementation, and endpoint:

[ServiceContract(Namespace = "http://www.abccorp.com/services/sample01/2007/02")]
public interface IServiceV1
{
    [OperationContract]
    String GetData(Int32 value);
}


public class Service : IServiceV1
{
    public String GetData(Int32 value) {
        return String.Format("You send {0}.", value);
    }
}


<endpoint address="v1" binding="wsHttpBinding" contract="IServiceV1" />

At this point, if the client gets the service metadata and creates a proxy, the client may send the following:

using (ServiceV1Client client = new ServiceV1Client("WSHttpBinding_IServiceV1")) {
    Console.WriteLine(client.GetData(3));
}

Now, assume the service changes from Int32 to String with no version change.

[ServiceContract(Namespace = "http://www.abccorp.com/services/sample01/2007/02")]
public interface IServiceV1
{
    [OperationContract]
    String GetData(String value);
}


public class Service : IServiceV1
{
    public String GetData(String value) {
        return String.Format("You send {0}.", value);
    }
}

With updating the service proxy on the client, the client is strongly typed to an Int32. Therefore, the client will not be able to send a String to the server. However, the client will still function as the service implicitly converts the value to a String.

The reverse of this situation can also be true. If the service started out using a String and was changed to use an Int32, the client, even though it is bound to a String type, can send data to the server as long as it is castable to an Int32. See the following for an example:

// This will work
using (ServiceV1Client client = new ServiceV1Client("WSHttpBinding_IServiceV1")) {
    Console.WriteLine(client.GetData("4"));
}


// This will NOT work
using (ServiceV1Client client = new ServiceV1Client("WSHttpBinding_IServiceV1")) {
    Console.WriteLine(client.GetData("four"));
}

Strong and Lax Together

A service may serve service contracts as the following demonstrates

public class Service : IServiceV1, IServiceV2
{
    // ...
}

The service contracts have the same essence, but their operation signatures will differ.

[ServiceContract(Namespace = "http://www.abccorp.com/services/sample01/2007/02")]
public interface IServiceV1
{
    [OperationContract]
    String GetData(Int32 value);
}


[ServiceContract(Namespace = "http://www.abccorp.com/services/sample01/2007/02")]
public interface IServiceV2
{
    [OperationContract]
    String GetData(Int32 value, String code);
}

In this case, the namespace is the same, but this is in no way a requirement. Any portion of the namespace can change as they are two completely different contracts.

These two contracts also share a method with the same name. This is legal in .NET, but there is no such thing as "service overloading". That is, the overloading is only in .NET and does not transfer to the service. Therefore, as has been previously mentioned, each contract must have its own endpoint. Given that each endpoint is for the same service, only the following is requires:


When a client will specify which endpoint to call when it creates its service proxy. For example,

using (ServiceV1Client client = new ServiceV1Client("WSHttpBinding_IServiceV1")) {
    Console.WriteLine(client.GetData(4));
}


using (ServiceV2Client client = new ServiceV2Client("WSHttpBinding_IServiceV2")) {
    Console.WriteLine(client.GetData(3, "hello"));
}

The client's application configuration will contain references to each endpoint. For example, this client may have the following:

<endpoint
  address="http://localhost:2352/Website/Service.svc/v1"
  binding="wsHttpBinding"
  contract="ServiceReference1.IServiceV1"
  name="WSHttpBinding_IServiceV1" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v2"
  binding="wsHttpBinding"
  contract="ServiceReference1.IServiceV2"
  name="WSHttpBinding_IServiceV2" />

The client also needs a specific strongly typed proxy for each endpoint, but it is also trivial. Below is an example of a complete proxy; other proxies are created following the same pattern. The properties set in the attributes should be easy to comprehend. However, it should be explicitly stated that the ConfigurationName property of the ServiceContract attribute matches the contract stated in the client application configuration.

[ServiceContract(Namespace="http://www.abccorp.com/services/sample01/2007/02", ConfigurationName="ServiceReference1.IServiceV1")]
public interface IServiceV1 {
    
    [OperationContract(Action="http://www.abccorp.com/services/sample01/2007/02/IServiceV1/GetData", ReplyAction="http://www.abccorp.com/services/sample01/2007/02/IServiceV1/GetDataResponse")]
    String GetData(Int32 value);
}


public interface IServiceV1Channel : IServiceV1, IClientChannel {
}


public partial class ServiceV1Client : ClientBase, IServiceV1 {
    public ServiceV1Client() {
    }
    
    public ServiceV1Client(String endpointConfigurationName) : 
            base(endpointConfigurationName) {
    }


    public ServiceV1Client(String endpointConfigurationName, String remoteAddress) : 
            base(endpointConfigurationName, remoteAddress) {
    }


    public ServiceV1Client(String endpointConfigurationName, EndpointAddress remoteAddress) : 
            base(endpointConfigurationName, remoteAddress) {
    }
    
    public ServiceV1Client(Binding binding, EndpointAddress remoteAddress) : 
            base(binding, remoteAddress) {
    }


    public String GetData(Int32 value) {
        return base.Channel.GetData(value);
    }
}

Given the simplicity of WCF, there is no reason to ever use tools like Visual Studio or svcutil.exe for proxy or configuration creation. Also, be aware that not all of the constructors for the proxy ("ServiceV1Client") are required.

It should also be explicitly stated that nothing that nothing here forbids the use of different bindings on each of the endpoints. For example, the following are legal endpoints on the client and Server:

Server

>endpoint address="v1" binding="basicHttpBinding" contract="IServiceV1" /<
>endpoint address="v2" binding="wsHttpBinding" contract="IServiceV2" //<

Client

>endpoint address="http://localhost:2352/Website/Service.svc/v1" binding="basicHttpBinding" contract="ServiceReference1.IServiceV1" name="WSHttpBinding_IServiceV1" /<
>endpoint address="http://localhost:2352/Website/Service.svc/v2" binding="wsHttpBinding" contract="ServiceReference1.IServiceV2" name="WSHttpBinding_IServiceV2" /<
If there are multiple bindings (B) and multiple contracts (C), then there needs to be B*C endpoints. For example, you may have the following: Server:
<endpoint address="v1/basic" binding="basicHttpBinding" contract="IServiceV1" />
<endpoint address="v2/basic" binding="basicHttpBinding" contract="IServiceV2" />
<endpoint address="v3/basic" binding="basicHttpBinding" contract="IServiceV3" />
<endpoint address="v4/basic" binding="basicHttpBinding" contract="IServiceV4" />


<endpoint address="v1/wshttp" binding="wsHttpBinding" contract="IServiceV1" />
<endpoint address="v2/wshttp" binding="wsHttpBinding" contract="IServiceV2" />
<endpoint address="v3/wshttp" binding="wsHttpBinding" contract="IServiceV3" />
<endpoint address="v4/wshttp" binding="wsHttpBinding" contract="IServiceV4" />

Client

<endpoint
  address="http://localhost:2352/Website/Service.svc/v1/basic"
  binding="basicHttpBinding"
  contract="ServiceReference1.IServiceV1"
  name="WSHttpBinding_IServiceV1_Basic" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v2/basic"
  binding="basicHttpBinding"
  contract="ServiceReference1.IServiceV2"
  name="WSHttpBinding_IServiceV2_Basic" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v3/basic"
  binding="basicHttpBinding"
  contract="ServiceReference1.IServiceV3"
  name="WSHttpBinding_IServiceV3_Basic" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v4/basic"
  binding="basicHttpBinding"
  contract="ServiceReference1.IServiceV4"
  name="WSHttpBinding_IServiceV4_Basic" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v1/wshttp"
  binding="wsHttpBinding"
  contract="ServiceReference1.IServiceV1"
  name="WSHttpBinding_IServiceV1_WSHttp" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v2/wshttp"
  binding="wsHttpBinding"
  contract="ServiceReference1.IServiceV2"
  name="WSHttpBinding_IServiceV2_WSHttp" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v3/wshttp"
  binding="wsHttpBinding"
  contract="ServiceReference1.IServiceV3"
  name="WSHttpBinding_IServiceV3_WSHttp" />
<endpoint
  address="http://localhost:2352/Website/Service.svc/v4/wshttp"
  binding="wsHttpBinding"
  contract="ServiceReference1.IServiceV4"
  name="WSHttpBinding_IServiceV4_WSHttp" />

Notice that neither the service contract, the service, nor the client proxy know anything about the bindings or the endpoints.

WCF Data Contract Versioning

If a v2 service sends a populated Person object to a v1 client, then the client will see a series of default values with the actual values being in the ExtensionData object. If the client sets its own data and sends that to the server, these values are effectively ignored.

For example, if the v2 service sends the following v2 data to the v1 client, the v1 client will see null.

return new Person()
{
    FirstName = "John",
    LastName = "Doe",
    Address1 = "1827 North South Street",
    City = "Winchestertonfieldville",
    State = "IA",
    Zip = "50182",
    Id = id
};

If the v1 client then proceeds to populate the v1 object and send it to the v2 service, the v2 service will completely ignore everything the v1 client has set because it is setting v1 data that the v2 service knows nothing about. The following client data, for example, is meaningless:

Person p = client.GetPerson(3);
p.Address = "Blank";
p.FirstName = "Jane";
client.SavePerson(p);

The v2 service will simply receive the same data it had previously send. That is, FirstName will still say "John".

The v2 service will accept the data from the v1 client if the v1 client had previously obtained that data from a v2 service. This is true even if the v2 data contract has a newly added data member which has IsRequired set to true.

However, if the client attempts to send a new v1 object to the v2 service, which has a v2 contract with a newly added data member with IsRequired set to true, a service fault will be thrown.

Client Data Contract

The data contract on the service is the same as the data contract on the client. Therefore the following is usable on both ends:

[DataContract(Namespace = "http://www.abccorp.com/services/sample01/datacontracts/2007/02")]
public class Person
{
    [DataMember]
    public Int32 Id { get; set; }


    [DataMember]
    public String FirstName { get; set; }


    [DataMember]
    public String LastName { get; set; }


    [DataMember(IsRequired=true)]
    public String Address1 { get; set; }


    [DataMember]
    public String Address2 { get; set; }


    [DataMember]
    public String City { get; set; }


    [DataMember]
    public String State { get; set; }


    [DataMember]
    public String Zip { get; set; }
}

This means that if the service sends an instance of this data contract to the client and does not have the Address1 property, a fault will occur. Given that IsRequired is checked at the destination, the fault will occur immediately when the client requests the data from the service.

In order to obtain data that is not strongly typed in the data member, you must implement the IExtensibleDataObject interface. This allows data that is unknown at the destination to be encapulated in an object. This is usable on both the client and service end. The data will be placed into the ExtensionData object which is of type ExtensionDataObject.

For example, if the server adds more data members to its data contract than what the client expects, the client will obviously not be able to populate this data into any local object. However, if the client data contract implements the IExtensibleDataObject interface, then any excess data members which the server sends to the client are placed into the ExtensionData property of the data contract instance. The functionality can be provided in a reverse manner as well. That is, if the client sends more information to ther service, if the service data contract implements the IExtensibleDataObject interface, then it will have the data encapulsated in a ExtensionData property. The IDesign standard, written by the designers of WCF, states that you should always implement this interface.

INotifyPropertyChanged

When using the Visual Studio generation tool, the data contracts that are created implement the INotifyPropertyChanged interface and have special logic in their set accessors to allow the client to monitor changes to properties. This in no way has any affect on the operations of WCF and are not required. Furthermore, given that the client service contract creation is trivial and that the data contract on the client is the same as the data contract on the server, it's recommended that all proxies be created by hand without use of Visual Studio or svcutil.exe.