So what are you waiting for?  Head on over and check out the webcast!

The video available through JupiterMedia and can be viewed at http://www.internet.com/video/. Just look for the "Developer Video" titled "REST Support in WCF".

Direct links are:
http://link.brightcove.com/services/link/bcpid1431564240/bclid1433966034/bctid1815668056

In our example, we are going to store a custom connection Id on the channel in the service.  Usually you can uniquely identify a client by the SessionId, but occasionally you may want to use your own custom Id or just store some additional information on the channel.

Creating an IContextChannel Extension

ConnectionIdExtension

The extension itself is very straight forward.  We can either store the ConnectionId in the object before it is attached to the channel, or if the ConnectionId is null, then a new one will be created when it is attached to the Channel.

public class ConnectionIdExtension : IExtension<IContextChannel>
{
    private string m_ConnectionId = String.Empty;

    public string ConnectionId
    {
        get
        {
            return m_ConnectionId;
        }
        set
        {
            m_ConnectionId = value;
        }
    }

    public ConnectionIdExtension()
    {
    }

    public ConnectionIdExtension(
        string connectionId)
    {
        m_ConnectionId = connectionId;
    }

    #region IExtension<IContextChannel> Members
    public void Attach(IContextChannel owner)
    {
        // If there is no connectionId, create one
        if (String.IsNullOrEmpty(m_ConnectionId))
        {
            m_ConnectionId = Guid.NewGuid().ToString();
        }
    }

    public void Detach(IContextChannel owner)
    {
    }
    #endregion IExtension<IContextChannel> Members
}

Attaching ConnectionIdExtension in an Operation

For our example service, we just have a method that returns the ConnectionId.  It firsts checks the extensions collection on the channel to see if there is a ConnectionIdExtension applied. If there isn’t, a new one is created and added to the extensions collection.

[ServiceBehavior(InstanceContextMode=InstanceContextMode.PerCall)]
public class MyService : IMyService
{
    public string GetConnectionId()
    {
        IContextChannel channel = OperationContext.Current.Channel;

        ConnectionIdExtension connectionIdExtension =
            channel.Extensions.Find<ConnectionIdExtension>();

        if (connectionIdExtension == null)
        {
            connectionIdExtension = new ConnectionIdExtension();
            channel.Extensions.Add(connectionIdExtension);
        }

        return connectionIdExtension.ConnectionId;
    }
}

Calling the Service and Observing the Behavior

If you use the WcfTestClient to test this method, you should see the same ConnectionId being used for each and every call from the client.  However, if you select the “Start a new proxy” option on the client, then the Id will be different with each call.  This option tells the client to create a new proxy instance with each call, so there is a new connection being used.

You can download a complete sample of the code discussed in this article here: http://www.danrigsby.com/Files/Rigsby.ChannelContext.zip

To catch any of my future talks, you can always check out my speaking engagements here: Speaking Engagements. I am currently promoting 4 main talks this season (September – November). If you are interested in hearing any of these, please send me an email, talk to your user group leaders, or comment on this thread.  I enjoy every opportunity to speak, share, and talk with my peers. I do still have materials for a session on Heroes {Community} Launch (Visual Studio 2008 and .Net 3.5), if there is any interest in this still.

Expect new presentations for Winter (December – February).  I am anticipating upcoming talks on the following: JQuery, Live Mesh API, Oslo, and PDC 2008.

As a treat, here is a picture of “RESTifarian Dan the Pig” taken at the closing ceremony of Kentucky Day of .Net.  I didn’t wear both of these items at the same time during my talks, but those who attended would understand each of these props.

Async Operations in Wcf Series:
Part 1: Event Based Model
Part 2: IAsyncResult Model (Client-Side)
Part 3: IAsyncResult Model (Server-Side)
Part 4: Canceling Operations
Part 5: Handling Exceptions

This is the fifth in a five part series on asynchronous operations in Wcf.  If you are new to this series, you might want to read the first section of part one to get an introduction to this post: http://www.danrigsby.com/blog/index.php/2008/03/18/async-operations-in-wcf-event-based-model/

What happens when there is an exception

We have covered the ins and outs of working with asynchronous operations.  But what happens in the unexpected happens?  What happens if an Exception or FaultException occurs on the server? There are basically two situations:

1. The exception is thrown before the thread is queued or before the thread context switch has happened.  This would still be on the users’s initiated thread.
2. The exception is thrown during the actual asynchronous operation on a different thread. This would be on some internal thread in the WCF service.

In situation 1, this acts like any other service call.  Since the exception occurred on the same thread the client initiated, it is simply propagated back to the client like any other exception.

In situation 2, the exception occurs on a separate thread, so the client isn’t directly notified. Instead the server caches the exception and signals the client that the operation is complete.  The client in turn will call its end operation completion method which will throw the exception back to the client.  Keep in mind though, that if the exception is fatal to the service and beyond recovery, it can crash the service process itself.

Exception example

An example of this can be shown with a simple service that calculates a square root.  In the call on the server, we have it wait 20 seconds before returning the result.  However, if we throw an exception before the wait period, the client will get signaled immediately. 

public double GetSquareRoot(double value)
{
    // Throwing exception here causes the server to signal to 
    // the client that the operation is complete and the exception
    // is rethrown on the client
    throw new FaultException("Fault before queuing thread.");

    Thread.Sleep(20000); // Wait 20 seconds

    return Math.Sqrt(value);
}

You can download this full example here: http://www.danrigsby.com/Files/Rigsby.WcfAsyncOperationExceptions.zip

The security timestamp is invalid because its creation time (‘8/262008 1:45:51 PM’) is in the future. Current time is ‘8/26/2006 1:40:01 PM’ and allowed clock skew is ‘00:05:00′.

The exception is of type TimeStampHasCreationTimeInFuture which is defined as: “The security timestamp is invalid because its creation time is in the future. Current time is specified and allowed clock skew is specified.”

This occurs when the difference of the client/server clocks is larger than the allowed value (the default is 5 minutes).  There two possible solutions to this issue:

1. Set the clocks on the client and server such that they are more in sync.  (You can use “net time” to help you accomplish this.)
2. Increase the allows clock skew time on the binding.

Option one is by far the easiest, but isn’t always possible depending on your network nor is to the most bulletproof since other clients could have the same issue. Option two isn’t as easy as it sounds though.  There is no setting you can change on your current bindings to set the max clock skew.  Instead, you need to resort to a custom binding.

Here is an example of a custom binding created in a configuration file with the max clock skew set to 15 minutes instead of the default 5 minutes:

<system.serviceModel>
    <services>
        <service name="MyService" behaviorConfiguration="MyBehavior">
            <endpoint address ="" binding="MyCustomBinding" contract="IMyService" />
        </service>
    </services>
    <behaviors>
        <serviceBehaviors>
            <behavior name="MyBehavior">
                <serviceMetadata httpGetEnabled="True"/>
            </behavior>
        </serviceBehaviors>
    </behaviors>
    <bindings>
        <customBinding>
            <binding name="MyCustomBinding">
                <security>
                    <localClientSettings maxClockSkew="00:15:00" />
                    <localServiceSettings maxClockSkew="00:15:00" />
                    <secureConversationBootstrap />
                </security>
                <textMessageEncoding />
                <httpTransport />
            </binding>
        </customBinding>
    </bindings>
</system.serviceModel>

// Create custom binding by extending any existing binding.
System.ServiceModel.Channels.CustomBinding myCustomBinding =
    new System.ServiceModel.Channels.CustomBinding(binding);

// Find the security binding element
System.ServiceModel.Channels.SecurityBindingElement security =
    myCustomBinding.Elements.Find<SecurityBindingElement>();

// Change the clock skew for service and client
if (security != null)
{
    security.LocalServiceSettings.MaxClockSkew = TimeSpan.FromMinutes(15);
    security.LocalClientSettings.MaxClockSkew = TimeSpan.FromMinutes(15);
}

ServiceHost host = new ServiceHost(typeof(MyService));
host.Open();
host.InstanceCreated += new EventHandler<InstanceEventArgs>(host_InstanceCreated);

1. PerCall: Every call made to the endpoints would create a new service instance.  This could be useful.
2. PerSession: Every new client connection would create a new service instance for the life of the client’s session. This could be very useful.
3. Single: A service instance is created during the first call.  This is fairly useless since it is called when the single instance of the service starts, but not again.

However, I accepted the challenge to come up with an implementation of this extension.  What I came up with is called ObservableServiceHost.  This is a custom ServiceHost that you can use instead of the default System.ServiceModel.ServiceHost.  The solution requires only 4 files:

1. InstanceEventArgs

A simple EventArgs class is needed as a container for the InstanceContext.

public class InstanceEventArgs : EventArgs
{
    public InstanceContext InstanceContext
    {
        get;
        set;
    }

    public InstanceEventArgs()
    {
    }

    public InstanceEventArgs(
        InstanceContext instanceContext)
    {
        InstanceContext = instanceContext;
    }
}

2. ObservableServiceHost

ObservableServiceHost extends the functionality of a ServiceHost.  This class consists of the following:

• A new event called InstanceCreated which uses the InstanceEventArgs.
• Re-implemented constructors of the base ServiceHost class.
• When the ServiceHost is Opened, a custom IEndpointBehavior is added to each of the endpoints used at the time the service is opened.  Endpoints which implement IMetadataExchange are be ignored though since the event doesn’t need to be fired a new metadata instance is created. (You could potentially modify this to add a different behaviors for different service interfaces.)

public class ObservableServiceHost : ServiceHost
{
    public event EventHandler<InstanceEventArgs> InstanceCreated;

    protected internal virtual void OnInstanceCreated(
        InstanceContext instanceContext)
    {
        EventHandler<InstanceEventArgs> handler = InstanceCreated;
        if (handler != null)
        {
            handler(this, new InstanceEventArgs(instanceContext));
        }
    }

    public ObservableServiceHost(
        object singletonInstance,
        params Uri[] baseAddresses) : base(singletonInstance, baseAddresses)
    {
    }

    public ObservableServiceHost(
        Type serviceType,
        params Uri[] baseAddresses) : base(serviceType, baseAddresses)
    {
    }

    protected override void OnOpening()
    {
        AddInstanceContextInitializers();

        base.OnOpening();
    }

    private void AddInstanceContextInitializers()
    {
        foreach (ServiceEndpoint endpoint in this.Description.Endpoints)
        {
            if (endpoint.Contract.ContractType != typeof(IMetadataExchange))
            {
                endpoint.Behaviors.Add(new InstanceCreationEndpointBehavior(this));
            }
        }
    }
}

3. InstanceCreationInitializer

This is a basic implementation of IInstanceContextInitializer which can be used to inspect the InstanceContext when an instance is created.  This class consists of the following:

• A constructor that takes in a reference to the ObservableServiceHost.
• An implementation of IInstanceContextInitializer.Initialize which fires the InstanceCreated event on the referenced ObservableServiceHost when the InstanceContext is created.

public class InstanceCreationInitializer : IInstanceContextInitializer
{
    private ObservableServiceHost m_ObservableServiceHost;

    #region IInstanceContextInitializer Members
    public void Initialize(
        InstanceContext instanceContext,
        Message message)
    {
        if (m_ObservableServiceHost != null)
        {
            m_ObservableServiceHost.OnInstanceCreated(instanceContext);
        }
    }
    #endregion IInstanceContextInitializer Member

    public InstanceCreationInitializer(
        ObservableServiceHost observableServiceHost)
    {
        m_ObservableServiceHost = observableServiceHost;
    }
}

4. InstanceCreationEndpointBehavior

This class implements IEndpointBehavior which is used to extend the runtime behavior of an endpoint and add our InstanceCreationInitializer to the endpoint dispatcher.  It is this behavior that we add to each of the endpoints when the ObservableServiceHost opens.

This class consists of the following:

• A constructor that takes in a reference to the ObservableServiceHost and creates an instance of the InstanceCreationInitializer.
• An implementation of IEndpointBehavior.ApplyDispatchBehavior which adds our InstanceCreationInitializer to the endpoint dispatchers InstanceContextInitializers collection.  This will cause our InstanceCreationInitializer to be run when a new instance is created.  The InstanceCreationInitializer  in turn calls our InstanceCreated event on the ObservableServiceHost.

public class InstanceCreationEndpointBehavior : IEndpointBehavior
{
    private InstanceCreationInitializer m_InstanceCreationInitializer;

    #region IEndpointBehavior Members

    public void AddBindingParameters(ServiceEndpoint endpoint, BindingParameterCollection bindingParameters)
    {
    }

    public void ApplyClientBehavior(ServiceEndpoint endpoint, ClientRuntime clientRuntime)
    {
    }

    public void ApplyDispatchBehavior(ServiceEndpoint endpoint, EndpointDispatcher endpointDispatcher)
    {
        endpointDispatcher.DispatchRuntime.InstanceContextInitializers.Add(
            m_InstanceCreationInitializer);
    }

    public void Validate(ServiceEndpoint endpoint)
    {
    }
    #endregion IEndpointBehavior Members

    public InstanceCreationEndpointBehavior(
        ObservableServiceHost observableServiceHost)
    {
        m_InstanceCreationInitializer = new InstanceCreationInitializer(observableServiceHost);
    }

}

Example Service

Included in the code for this article is an example of how to use this library.  You can take any new or existing service and use it with the ObservableServiceHost, then just attach to the InstanceCreated event:

static class Program
{
    static void Main(string[] args)
    {
        ObservableServiceHost serviceHost = new ObservableServiceHost(
            typeof(MyService));
        serviceHost.Open();
        serviceHost.InstanceCreated += new EventHandler<InstanceEventArgs>(serviceHost_InstanceCreated);

        Console.WriteLine("Press any key to exit application...");
        Console.WriteLine();
        Console.ReadLine();

        serviceHost.Close();
    }

    static void serviceHost_InstanceCreated(object sender, InstanceEventArgs e)
    {
        Console.WriteLine("New InstanceContext created");
    }
}

You can play around with the InstanceContextMode on the Service to see what happens when you use it with PerCall, PerSession, or Single.  The line of code to look for is:

[ServiceBehavior(InstanceContextMode=InstanceContextMode.PerCall)]

I hope others find this class useful or at least have learned more about the extensibility that WCF has to offer. You can download the complete library and sample server here: http://www.danrigsby.com/Files/Rigsby.ServiceHostCreation.zip

You can still get the Visual Studio 2005 extensions for .NET Framework 3.0 (Windows Workflow Foundation) from here (for now):  http://www.microsoft.com/downloads/details.aspx?familyid=5D61409E-1FA3-48CF-8023-E8F38E709BA6&displaylang=en

However, the official link for Visual Studio 2005 extensions for.NET Framework 3.0 (WCF & WPF): http://www.microsoft.com/downloads/details.aspx?FamilyId=F54F5537-CC86-4BF5-AE44-F5A1E805680D&displaylang=en has been removed for many months.

So why is the link broken?  There have been a few posts on the MSDN Forums asking where these extensions went.  The basic answer is that, according to Microsoft, Visual Studio 2005 was never meant to be used to develop WCF, WF, and WPF.  Visual Studio 2008 is the correct tool to use, and on June 30th 2008, the license for this CTP expired (see this post).

While you cant get  Visual Studio 2005 extensions for.NET Framework 3.0 (WCF & WPF) from the official Microsoft site, you can still find it at these locations:

• http://www.download.com/The-Visual-Studio-2005-extensions-for-NET-Framework-3-0-WCF-WPF-November-2006-CTP/3000-10253_4-10727672.html
• http://downloads.zdnet.co.uk/0,1000000375,39328336s,00.htm

However, due to licensing concerns, these links may go down over time too.  So, if you need these extensions, you will want to grab them soon.  But if you are doing any development in .Net Framework 3.0, you need to move to Visual Studio 2008.

Some companies out there will have issues with this, but you can still use .Net 3.0 technologies in Visual Studio 2005.  It’s just the tools that are no longer supported.

The video is available through JupiterMedia and can be viewed at http://www.internet.com/video/. Just look for the "Developer Video" titled "Simple WCF Services".  Direct link is:

http://link.brightcove.com/services/link/bcpid1431564240/bclid1433966034/bctid1727929931

Browser and WebServer Limits: http://www.boutell.com/newfaq/misc/urllength.html

• Internet Explorer: 2,083 characters, with no more than 2,048 characters in the path portion of the URL
• Firefox: 65,536 characters show up, but longer URLs do still work even up past 100,000
• Safari: > 80,000 characters
• Opera: > 190,000 characters
• IIS: 16,384 characters, but is configurable
• Apache: 4,000 characters

Different things can happen when you go beyond these URL limits depending on the browser and web servers. It could be a “413 (Entity Too Large)” error, “414 (Request-URI Too Long)” error, the URL could be truncated, or it may just work.  However since different things can happen and your service could be consumed by any source, you have to assume the worst could happen.

By looking at just these numbers, it seems you would be pretty safe with a URL that gets up to 2,000 characters.  However, lets look at the W3C standards on this.  The HTTP specification doesn’t really set a size for the length of a URL, but it does recommend being cautious when going above 255. According to Hypertext Transfer Protocol – HTTP/1.1 section 3.2:

Servers ought to be cautious about depending on URI lengths above 255 bytes, because some older client or proxy implementations might not properly support these lengths.

So for the sake of a REST interface you should avoid setting up an interface where there is any possibility of a URL getting beyond 255.  If you are using a GET verb to request a resource via the URL you should be pretty safe.  However POSTing or PUTing an insert or update via a URL may not be the way to go unless the data size is very small.

The most important thing is to keep your interfaces consistent.  You don’t want one operation that allows an insert via the URL and another through POST data.  This just makes things confusing and less discoverable.  Especially since REST has no way to publish metadata about the operations.   You could follow standards such as these:

In general this follows “High REST” which is the more pure REST.  This dictates that the HTTP Verbs define the methods to act on the resource.

Ultimately it’s up to you how you implement the REST interface, but stay consistent, be careful about URL limits, and try to follow industry standards.