Web user interfaces have been getting smarter lately. A few years ago, most of a web application’s logic would live on the server, with client-side code in the web browser typically doing little more than making buttons light up and menus fly out in response to the mouse. But now, we expect more from our web user interfaces. Whether you use AJAX (Asynchronous JavaScript and XML), or a RIA (Rich Internet Application) technology such as Silverlight or Flash, web applications often communicate constantly with the web server, and not just when navigating between pages.

If you’re writing the server-side parts of this sort of application in C#, you will typically use ASP.NET to provide a web user interface. But what should you use for programmatic communication—the messages that flow between the web UI and the server once a page is already loaded?

WCF is a flexible choice here, because as Figure 13-1 illustrates, you can make a single set of remote services accessible to many common browser-based user interface technologies. A WCF service can be configured to communicate in several different ways simultaneously. You could use JSON (JavaScript Object Notation), which is widely used in AJAX-based user interfaces because it’s is a convenient message format for JavaScript client code. Or you could use XML-based web services. Note that using WCF on the server does not require WCF on the client. These services could be used by clients written in other technologies such as Java, as long as they also support the same web service standards as WCF.

Looking specifically at the case where your web application uses C# code on the client side, this would mean using either Silverlight or WPF. (You can put WPF in a web page by writing an XBAP—a Xaml Browser Application. This will work only if the end user has WPF installed.) If you’re using C# on both the client and the server, the most straightforward choice is likely to be WCF on both ends.

What if your server isn’t running .NET, but you still want to use .NET on the web client? There are some restrictions on WCF in this scenario. Silverlight’s version of WCF is much more limited than the version in the full .NET Framework—whereas the full version can be configured to use all manner of different protocols, Silverlight’s WCF supports just two options. There’s the so-called basic profile for web services, in which only a narrow set of features is available, and there’s a binary protocol unique to WCF, which offers the same narrow set of features but makes slightly more efficient use of network bandwidth than the XML-based basic profile. So if you want a Silverlight client to use WCF to communicate with a non-.NET web service, as Figure 13-2 illustrates, this will work only if your service supports the basic profile.

Figure 13-1. Web application clients and a WCF service

Figure 13-2. Silverlight client and non-.NET web service

More surprisingly, similar restrictions exist with a WPF XBAP. Even though XBAPs use the full version of the .NET Framework, certain features of WCF are disabled for security purposes—client code in web browsers shouldn’t have complete freedom to connect to anywhere on the Internet, because that would make life too easy for hackers. So WCF offers only a very limited version of its services to .NET applications running inside web browsers, meaning that XBAPs have similar WCF limitations to Silverlight.

If you’re writing a Silverlight client and you want to talk to a service that does not conform to the web services basic profile, that’s not necessarily a showstopper. It just rules out WCF—you will need to use the lower-level web-based APIs instead, or even the socket APIs, depending on the service.

Note that while WCF is usually a good default choice on the server side for web applications with client-side code, there are a few cases where you might not want to use it. ASP.NET provides its own mechanism for supporting AJAX clients, and while it’s considerably less flexible than WCF, you might not need the flexibility. The simplicity of using just one framework on the server instead of two might end up looking like a better option.

There’s a subtler reason why WCF might not always be the best fit: the style of communication. If you use WCF in a web application, the communication it supports will tend to involve the following steps:

This is, in effect, a remote method invocation—it’s a way for the client to ask the server to run some code and optionally get a return value. (WCF is more flexible than this in general, but in the context of a web application, your communication patterns are constrained because clients will typically be behind a firewall.) That’s likely to be a perfectly good pattern for operations such as looking up a stock price or retrieving a weather forecast. However, if you are building a photograph browser application, this would not be a great way to retrieve pictures. You could make it work, but it’s easier to use the mechanisms already built into the web browser for downloading images—you’d almost certainly want to make the bitmaps available for download via HTTP rather than using WCF. HTML and Silverlight have UI elements that know how to render images downloaded with HTTP. Browsers are usually able to start rendering images without having to wait for the download to finish, and that’s difficult to achieve with a method invocation idiom. And by using normal HTTP image download, you’d also get to take advantage of standard HTTP caching in your web browser and any caching proxies you may be using. Plain old HTTP works better here than trying to fetch a bitmap using something resembling a method call.

More generally, if the information your client code works with looks like a set of resources that might be identified with URIs (Uniform Resource Identifiers; for instance, http://oreilly.com/) and accessed via HTTP you might want to stick with ordinary HTTP rather than using WCF. Not only do you get the benefits of normal HTTP caching when reading data, but it may also simplify security—you might be able to take whatever mechanism you use to log people into the website and secure access to web pages, and use it to secure the resources you fetch programmatically.

Using WCF typically requires less effort than designing a RESTful service—you can get up and running with a good deal less thought and forward planning (although you might not consider a lack of thought and planning to be a good thing for your particular application). But if the communication you require with your server doesn’t sound like it fits well into a method-call-like style, you’ll probably want to consider alternatives to WCF.

Occasionally, neither WCF nor plain HTTP will be the best approach when connecting a web UI to a service. With Silverlight, you have the option to use TCP or UDP sockets from the web browser. (The UDP support is somewhat constrained. Silverlight 4, the current version at the time of writing this, only supports UDP for multicast client scenarios.) This is a lot more work, but it can support more flexible communication patterns—you’re not constrained to the request/response style offered by HTTP. Games and chat applications might need this flexibility, because it provides a way for the server to notify the client anytime something interesting happens. Sockets can also offer lower communication latency than HTTP, which can be important for games.

Fashionable though web applications are, they’re not the only kind of distributed system. Traditional Windows applications built with WPF or Windows Forms are still widely used, as they can offer some considerable advantages over web applications for both users and developers. Obviously, they’re an option only if all your end users are running Windows, but for many applications that’s a reasonable assumption. Assuming clients are running Windows, the main downside of this kind of application is that it’s hard to control deployment compared to a web application. With web applications, you only have to update an application on the server, and all your clients will be using the new version the next time they request a new page.

To update a classic Windows application, you need to somehow get a new version of the program onto the end users’ machines. Since it’s rarely practical to install a new version on every single user’s machine simultaneously, you need to handle the possibility of having several different versions of the client software all trying to talk to your server. The extent to which this can cause problems will depend on how much control you have over the client computers.

You won’t necessarily write the code at both ends of a connection. You might build a .NET client which talks to a web service provided by someone else. For example, you could write a WPF frontend to an online social media site such as Twitter, or a Silverlight client that accesses an external site such as Digg.

In this case, your choice of communication technology will be determined largely by the service you’re connecting to. If it presents information in a way that WCF is able to consume, use WCF. How would you know that this is the case? You could try asking the service provider’s support staff if their service works with WCF, but if they’re not sure, it’ll be down to the nature of the service. If your service provider uses the so-called WS-* family of web service standards, there’s a good chance WCF will be able to talk to the service.

If WCF works in your scenario, that’s great, but when it is not an option, use .NET’s HTTP-based APIs. Unless, of course, the service in question is not HTTP-based, and requires you to work directly with TCP or UDP, in which case you would use sockets. In short, you’re at the mercy of the server, and you’ll just have to pick whichever option happens to work.

Note that because Silverlight’s version of WCF is considerably more limited than the full .NET Framework version, a Silverlight client is more likely to have to drop down to the HTTP APIs than a full .NET client.

If you are writing a web service in .NET that you would like to be accessible to client programs written by people other than you, the choice of technology will be determined by two things: the nature of the service and the demands of your clients.^[26] If it’s something that fits very naturally with HTTP—for example, you are building a service for retrieving bitmaps—writing it as an ordinary ASP.NET application may be the best bet (in which case, refer to Chapter 21). But for services that feel more like a set of remotely invocable methods, WCF is likely to be the best bet. You can configure WCF to support a wide range of different network protocols even for a single service, thus supporting a wide range of clients.

As with the other application types, you would use sockets only if your application has unusual requirements that cannot easily be met using the communication patterns offered by HTTP.

So having looked at some common scenarios and seen which communication options are more or less likely to fit, let’s look at how to use those options.

We’ll start with the server for our chat application. If you want to build your own copy of the project as you read, open Visual Studio’s New Project dialog (Ctrl-Shift-N) and in the template list on the left, select Visual C#→WCF. Choose the WCF Service Library project template. Call the project ChatServerLibrary. Ensure that the “Create directory for solution” checkbox is checked, and call the solution WcfChat.

This project will produce a DLL as its output, because the WCF Service Library project template doesn’t commit to hosting the WCF service in any particular container application. WCF can run inside IIS, a Windows Service, a console application, or indeed pretty much any .NET application. If you want to use a particular kind of host, you can just create the relevant type of project—for example, instead of creating a WCF Service Library, you could create an ASP.NET web application project if you wanted to host your WCF service in there. (You can add a WCF service as a new item to an existing web project, so you don’t need a WCF-specific project type.) But there are a couple of benefits to this library-based template: as you’ll see shortly, it provides an easy way to do simple manual testing of the service. Also, it means you can host the service in multiple different host applications, which can be useful for automated testing—you can test the service without having to deploy it into its intended environment.

Visual Studio will have added a single service to the project, called Service1. This contains some example code that does things we don’t need in our chat application, so we’ll ignore that. (Feel free to delete them if you’re building your own version as you read this.) We’ll add a new WCF Service item to the project with the Add New Item dialog, called ChatService. Visual Studio adds two files to the project: ChatService.cs and IChatService.cs. This reflects the fact that WCF makes a distinction between the code that implements a service, and the contract for that service.

When two systems communicate over a network, they need to agree on what information is to be sent back and forth. WCF formalizes this with what it calls contracts. So the IChatService interface added by the wizard represents a service contract. The service contract defines the operations the service offers. As Example 13-1 shows, the interface is marked with a ServiceContract attribute to make it clear that it’s a contract definition.

[ServiceContract]
public interface IChatService
{
    [OperationContract]
    void DoWork();
}

Each method in the interface that defines an operation offered by the service must be marked with an OperationContract. You might have thought that it would be enough that the interface is marked as ServiceContract—why do we also need to annotate each method? WCF requires you to be explicit so that it’s always obvious when you’re defining some aspect of your system that will be visible across the network. A method call to a local object is a quite different kind of operation than using a remote service—the performance and reliability characteristics are poles apart—so it’s important for such boundaries to be clearly visible in the code.

Our service is designed to let people chat, so it will need to provide clients with a way to send a short bit of text, which we’ll refer to as a note. (A more obvious name would be message, but that would introduce ambiguity—WCF sends messages to and from the server for every operation, so to call one of the pieces of information that crops up in certain messages a message would be confusing.) To keep things simple, we’ll just have one big chat room where everyone can see every note; we’re not going to support private conversations. To support sending notes, we’ll get rid of the DoWork method provided by Visual Studio, and replace it with the code in Example 13-2.

[OperationContract]
void PostNote(string from, string note);

If you attempt to build your project in Visual Studio, you’ll get a compiler error:

error CS0535: 'ChatServerLibrary.ChatService' does not implement interface
 member 'ChatServerLibrary.IChatService.PostNote(string, string)'

Remember that Visual Studio added two files: IChatService.cs (the contract) and ChatService.cs (the service implementation). The compiler is pointing out to us that our service implementation no longer conforms to the contract for the service. So in ChatService.cs, we need to replace the DoWork method with this code:

public void PostNote(string from, string note)
{
    Debug.WriteLine("{0}: {1}", from, note);
}

For this to compile, you’ll need to add a using System.Diagnostics; directive to the top of your file.

You can now build and run the application—either press F5 or choose Debug→Start Debugging. Normally, you’d get an error if you tried to run a library project, because you can’t run a DLL. However, Visual Studio knows this is a WCF project, and it has a special feature for running and testing WCF libraries. When you run the project, you’ll see a balloon pop up in the taskbar notification area, as Figure 13-3 shows.

Figure 13-3. WCF test service host

The WCF Service Host (or WcfSvcHost, as it’s abbreviated in the pop up) is a program provided by Visual Studio that loads your WCF DLL and makes its services available for local access for debugging purposes. Visual Studio also launches a second program, the WCF Test Client—this is a Windows application that provides a UI for invoking operations on your service to try it out. As Figure 13-4 shows, it presents a tree view listing all the services defined by your project, and all the operations available in each service. (If you’ve deleted the unwanted IService1 mentioned earlier in your code, you’ll only see one service.)

Figure 13-4. Services listed in the WCF Test Client

The test client has found both the original Service1 service that we chose to ignore and the ChatService we added. Double-clicking on the PostNote item that represents the operation we defined for the chat service shows a tab on the right that lets us try out the service—the test client’s job is to let us try invoking service operations without having to write a whole program just to do that. Figure 13-5 shows this tab with arguments. If you look at the Value column, you’ll see arguments for the from and note parameters of the PostNote operation—you can just type these directly into the Value column.

Clicking the Invoke button invokes the PostNote operation on the service. We can verify that the information typed into the WCF Test Client made it through, by looking in Visual Studio’s Output window—that’s where text sent to Debug.WriteLine appears. (There’s an item on the View menu to make the Output window visible, if it’s not already open.) The Output window gets fairly busy, so you might have to look quite carefully, but somewhere in the noise, you’ll see that the from and note argument values are both shown, for example:

Ian: Hello, world

Figure 13-5. Passing arguments with the WCF Test Client

Once the test client has received a response from the service, it indicates this in the bottom half of the tab. Our PostNote operation has a return type of void, which means that it sends back an empty response. (It still sends a response to report that the operation has finished. It just contains no data.)

You may be curious to know what the messages being sent between the client and the server look like. And if you’re not, we’d recommend becoming curious about such things. It’s difficult to design good, nontrivial distributed systems (and impossible to diagnose problems with them) if you don’t know what the messages they send look like. Sadly, some developers are happy to be ignorant about this sort of thing, but they frequently get stuck and have to ask for help from people who know what they’re doing anytime something goes wrong. If you’d rather be one of the wizards who can fix these problems, you need to learn what the messages that go over the network really look like. You can see the messages in the WCF Test Client by clicking on the XML tab at the bottom. It’s beyond the scope of this book about C# to explain the structure of these WCF messages in detail, but it’s easy to see where the data you sent ended up in this example. If you want to learn more, the book Learning WCF by Michele Leroux Bustamante (O’Reilly) would be a good place to start, or for a more advanced treatment, you could try Programming WCF Services by Juval Lowy (O’Reilly).

The WCF Service Host and Test Client are useful for very simple interactive testing, but a real, useful service needs to be hosted somewhere more permanent. So next, we’ll look at how .NET programs can host WCF services.

WCF services are flexible about their location—any ordinary .NET application can host WCF services, so there’s no such thing as a specialized WCF Service Host project template in Visual Studio. You can host WCF services inside ASP.NET web applications, Windows Services, console applications, or even applications with GUIs built with Windows Forms or WPF. Any process that can accept incoming network connections should work, so about the only place you can’t host a WCF service is in a process where security constraints prevent inbound connections, such as a web browser. (For example, Silverlight clients can make outbound WCF connections, but they can’t host a service that accepts incoming connections.)

ASP.NET web applications are a particularly popular host environment for WCF services, because ASP.NET solves a lot of the problems you need to solve for an online service. Web applications automatically become available when a machine starts up—there’s no need for anyone to log in and start a program. ASP.NET provides a robust hosting environment—it’s able to restart after errors, and integrate into diagnostic management systems so that system administrators can discover when problems occur. There are well-understood ways to load-balance web applications across multiple servers. ASP.NET can make use of IIS security features such as integrated authentication.

However, ASP.NET is not always the right choice. A WCF service hosted in a web application can’t use the full range of protocols supported by WCF—incoming messages have to arrive by HTTP. Also, web applications usually get to run code only while they are actively handling a request from a client. If you need to perform long-running work that continues even when there are no clients connected right now, a web application host might be a bad idea, because in some configurations ASP.NET will restart web applications from time to time, or may even shut them down completely when they’ve had no incoming requests lately. So in some situations it might make more sense to write your own host. A Windows Service might be a good bet, as it can start automatically when the machine starts.

Sometimes it’s useful to host a WCF service inside a normal Windows application. Imagine a WPF application providing some sort of advertising display on a screen in a shop window—it could be useful to build a WCF service into this to enable the display to be controlled without needing physical access to the machine.

The techniques for hosting look much the same in all cases. And since we won’t be getting on to ASP.NET until later in the book, we’ll keep it simple by hosting our service in a console application. It’ll be easy enough to move it into different hosting environments later because the service itself is in a separate DLL project—we could just add it to a Windows Service or a web application.

Regardless of the type of host, one of the most important parts of WCF hosting is the configuration file.

<system.web>
  <compilation debug="true" />
</system.web>

<service name="ChatServerLibrary.ChatService">

<endpoint address=""
          binding="wsHttpBinding"
          contract="ChatServerLibrary.IChatService">
  <identity>
    <dns value="localhost" />
  </identity>
</endpoint>

<endpoint address="mex"
          binding="mexHttpBinding"
          contract="IMetadataExchange" />

<host>
  <baseAddresses>
    <add baseAddress=
"http://localhost:8732/Design_Time_Addresses/ChatServerLibrary/ChatService/" />
  </baseAddresses>
</host>

http://localhost:8732/Design_Time_Addresses/ChatServerLibrary/ChatService/mex

netsh http show urlacl

<behaviors>
  <serviceBehaviors>
    <behavior>
      <serviceMetadata httpGetEnabled="True" />
      <serviceDebug includeExceptionDetailInFaults="False" />
    </behavior>
  </serviceBehaviors>
</behaviors>

static void Main(string[] args)
{
    using (ServiceHost host = new ServiceHost(typeof(ChatService)))
    {
        host.Open();

        Console.WriteLine("Service ready");
        Console.ReadKey();
    }
}

http://localhost:8732/Design_Time_Addresses/ChatServerLibrary/ChatService/

We need to create a client program to talk to our service. Again, to keep things simple we’ll make it a console application. We’ll add this to the same solution, calling the project ChatClient. (Obviously, you’ll need to stop the ChatHost program first if you’re trying this out and it’s still running in the debugger.)

When you right-click on a project’s References item in Visual Studio’s Solution Explorer, you’re offered an Add Service Reference menu item as well as the normal Add Reference entry. We’re going to use that to connect our client to our server via WCF.

The Add Service Reference dialog offers a Discover button (shown in Figure 13-6) which attempts to locate services in your current solution. Disappointingly, if we were to click it with our code as it is now, it would report that it didn’t find any services. That’s because we wrote all the hosting code by hand for ChatHost—Visual Studio doesn’t realize that our console application is hosting services. It usually looks only in web projects—if we’d hosted the service in an ASP.NET web application, it would have found it. But with the approach we’re taking here, it needs a little help.

For Visual Studio to be able to connect to our console-hosted service we need the service to be up and running before the Add Service Reference dialog is open. The easiest way to do this is to run the project, without debugging it. Instead of pressing F5, we choose Debug→Start Without Debugging, or we press Ctrl-F5. This runs the ChatHost program without debugging, leaving Visual Studio free for other tasks, such as adding a service reference.

We’ll need the address of the service handy, and since it’s quite long, it’s easiest to open our host’s App.config and copy the service address to the clipboard. (It’s the baseAddress attribute in the <host> section.) Then we can go to the ChatClient project and add a Service Reference. If we paste the address of the service into the Address box and then click the Go button, after a few seconds we’ll see the Services panel on the left display a ChatService entry. Expanding this shows an IChatService item representing the contract, and selecting this shows the one operation available in our contract, PostNote, as Figure 13-6 shows.

Figure 13-6. Add Service Reference

While the list of services, contracts, and operations in the Add Service Reference dialog is useful for verifying that we have the service we wanted, the significance of the information here goes a little deeper—it’s part of an important feature of how systems communicate in WCF. Remember that we defined a contract earlier, to describe the operations our service provides to its clients. For the client to communicate successfully with the server, it also needs a copy of that contract. So the best way to think of the Add Service Reference dialog is that it’s a tool for getting hold of the contract from a service.

This is the purpose of the metadata exchange entry we saw earlier when we looked at the configuration Visual Studio generated for our WCF service. Metadata exchange is just a fancy way of saying that a service provides a way for a client to discover the contract and related information about the service. The Add Service Reference dialog uses this information to configure a client application to communicate with the service, and to provide it with a copy of the contract.

To see the results of this, we’ll finish with this dialog. In the Namespace text box near the bottom, we’ll type ChatService—Visual Studio will put the contract and any other types relating to this service into this namespace. When we click OK a Service References item appears in the project in the Solution Explorer, and it will contain an entry called ChatService. (Now that we’ve done this, we can stop the service host console window we ran earlier.)

Visual Studio generates some code when adding a service reference. By default, it hides this, but we can take a look at it. At the top of the Solution Explorer, there’s a toolbar, and if you hover your mouse pointer over the buttons you’ll find that one has a tool tip of Show All Files. This button toggles each time you click it. When it’s pressed in, the ChatService service reference can be expanded, as Figure 13-7 shows.

Figure 13-7. Generated files in a service reference

The most interesting file in here is Reference.cs, inside the Reference.svcmap item. Inside this file, near the top, there’s a copy of IChatService—the contract we wrote earlier:

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel",
                                                "4.0.0.0")]
[System.ServiceModel.ServiceContractAttribute(
       ConfigurationName="ChatService.IChatService"]
public interface IChatService
{

    [System.ServiceModel.OperationContractAttribute(
         Action="http://tempuri.org/IChatService/PostNote",
         ReplyAction="http://tempuri.org/IChatService/PostNoteResponse")]
    void PostNote(string from, string note);
}

It looks a little more complex than the original, because Visual Studio has annotated it with various attributes, but it’s simply being explicit about the values that WCF fills in by default.^[27] Aside from these extra details, you can see that it is essentially a copy of the original contract.

Proxy

Looking further through the Reference.cs file generated by adding the service reference, the next most interesting feature after the contract is a class called ChatServiceClient. This implements IChatService, because it acts as a proxy for the service. If we want to communicate with the service, all we need to do is create an instance of this proxy and invoke the method representing the operation we’d like to perform. So if we add a using ChatClient.ChatService; directive to the top of Program.cs in ChatClient, we can then modify its Main method as shown in Example 13-5.

Example 13-5. Invoking a web service with a WCF proxy

static void Main(string[] args)
{
    using (ChatServiceClient chatProxy = new ChatServiceClient())
    {

        chatProxy.PostNote("Ian", "Hello again, world");
    }
}

Notice the using statement—it’s important to ensure that you dispose of WCF proxies when you have finished using them. When the client calls this method on the proxy, WCF builds a message containing the inputs, and it sends that to the service. Over in the service (which is running in a separate process, perhaps on a different machine) WCF will receive that message, unpack the inputs, and pass them to the PostNote method in the ChatService class.

To try this out, we’re going to need to run both the client and the server simultaneously. This means configuring the solution in Visual Studio a little differently. If you right-click on the WcfChat solution in the Solution Explorer and select Set Startup Projects, the dialog that opens offers three radio buttons. If you select the Multiple Startup Projects radio button, you can choose which of your projects you’d like to run when debugging. In this case, we want to change the Action for both the ChatClient and ChatHost projects from None to Start. (We leave the ChatServerLibrary Action as None—we don’t need to run that project, because our ChatHost project hosts the server library.) Also, we want to give the service a head start so that it’s running before the client tries to use it, so select ChatHost and click the up arrow next to the list, to tell Visual Studio to run it first. (In theory, this is not a reliable technique, because there’s no guarantee that the server will get enough of a head start. In practice, it appears to work well enough for this sort of debugging exercise.) Figure 13-8 shows how these settings should look.

Figure 13-8. Starting multiple projects simultaneously

If we run the program by pressing F5, two console windows will open, one for the client and one for the service.

Note

If you’re following along, it’s possible that you’ll see an AddressAlreadyInUseException with an error message complaining that “Another application has already registered this URL with HTTP.SYS.” This usually means you have a copy of ChatHost still running—somewhere on your desktop you’ll find a console window running the service host. Or possibly, the WCF Service Host is still running. This error occurs when you launch a second copy of the service because it tries to listen on the same address as the first, and only one program can receive requests on a particular URL at any one time.

Visual Studio displays the message in its Output window because of the call to Debug.WriteLine in PostNote, just like it did when using the WCF Test Client earlier, verifying that the proxy was able to invoke an operation on the service. (You might need to look carefully to see this—the message can get buried among the various other notifications that appear in the Output window.)

Notice that in Example 13-5 we didn’t need to tell the proxy what address to use. That’s because the Add Service Reference dialog imported more than just the contract definition. It adds information to the ChatClient project’s App.config file, shown in all its gory detail in Example 13-6.

Example 13-6. Generated client-side App.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.serviceModel>
        <bindings>
            <wsHttpBinding>
                <binding name="WSHttpBinding_IChatService"
                    closeTimeout="00:01:00" openTimeout="00:01:00"
                    receiveTimeout="00:10:00" sendTimeout="00:01:00"
                    bypassProxyOnLocal="false" transactionFlow="false"
                    hostNameComparisonMode="StrongWildcard"
                    maxBufferPoolSize="524288" maxReceivedMessageSize="65536"
                    messageEncoding="Text" textEncoding="utf-8"
                    useDefaultWebProxy="true"
                    allowCookies="false">
                    <readerQuotas maxDepth="32" maxStringContentLength="8192"
                        maxArrayLength="16384"
                        maxBytesPerRead="4096" maxNameTableCharCount="16384" />
                    <reliableSession ordered="true"
                        inactivityTimeout="00:10:00" enabled="false" />
                    <security mode="Message">
                        <transport clientCredentialType="Windows"
                            proxyCredentialType="None" realm="" />
                        <message clientCredentialType="Windows"
                            negotiateServiceCredential="true"
                            algorithmSuite="Default" />
                    </security>
                </binding>
            </wsHttpBinding>
        </bindings>
        <client>
            <endpoint address="http://localhost:8732/Design_Time_Addresses/
                                  ChatServerLibrary/ChatService/"
                binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_IChatService"
                contract="ChatService.IChatService"
                name="WSHttpBinding_IChatService">
                <identity>
                    <userPrincipalName value="[email protected]" />
                </identity>
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

Like the service configuration we examined earlier, this also has an <endpoint> element with an address, binding, and contract, although being on the client side, this <endpoint> appears inside a <client> element instead of a <service> element. The proxy gets the address from this endpoint definition.

Note

You can provide the proxy with an address from code if you want to. It offers various constructor overloads, some of which accept a URL. But if you don’t provide one, it will look in the configuration file.

Notice that the endpoint also has a bindingConfiguration attribute—this refers to a <binding> element earlier in the file that contains information on exactly how the wsHttpBinding should be configured. There was nothing like this in the service, because we were just using the defaults. But the Add Service Reference dialog always generates a binding configuration entry, even if you happen to be using the defaults.

Our “chat” application is demonstrating the ability for the client to send a note to the server, but it’s not complete yet. The client needs a couple of extra features. To make our conversation a bit less one-sided, we should be able to see notes written by other people. And unless our conversations are all going to be exceptionally brief, we need to be able to type in more than just one note.

We’ll fix that second problem by modifying the code in Example 13-5. We’ll put the call to the proxy inside a loop, and we’ll also ask for the user’s name, so we can support notes from people who may not be called Ian (see Example 13-7).

Example 13-7. Client with input loop

static void Main(string[] args)
{
    ChatServiceClient chatProxy = new ChatServiceClient();

    Console.WriteLine("Please enter your name:");
    string name = Console.ReadLine();
    while (true)
    {
        Console.WriteLine("Type a note (or hit enter to quit):");
        string note = Console.ReadLine();
        if (string.IsNullOrEmpty(note))
        {
            break;
        }
        chatProxy.PostNote(name, note);
    }
}

We’ll also modify the server so that it prints out the note, rather than sending it to the debug output—that’ll make it a bit easier to see when notes are coming in. So change PostNote in ChatService to this:

public void PostNote(string from, string note)
{
    Console.WriteLine("{0}: {1}", from, note);
}

If you run both programs again by pressing F5, the client program will ask you to type in your name, and will then let you type in as many notes as you like. Each new note will be sent to the server, and you should see the notes appear in the server console window.

This is an improvement, but there’s still no way for the client to find out when other users have typed notes. For this, we’ll need to add bidirectional communication.

The contract for our chat service is a one-sided affair—it’s all about the notes the client sends to the server. But WCF supports duplex contracts, which provide a means for the server to call the client back. (Note that there are some issues with HTTP that can make duplex communication tricky—see the sidebar on the next page.) A duplex contract involves two interfaces—as well as an interface that the server implements, we also define an interface that the client must implement if it wants to use the service. In our example, the service wants to notify clients whenever any user posts a note. So the client-side interface, shown in Example 13-8, looks pretty similar to our current server interface.

public interface IChatClient
{
    [OperationContract]
    void NotePosted(string from, string note);
}

Notice that while methods in a callback interface require the usual OperationContract attribute, the interface itself does not need to be marked with ServiceContract. That’s because this callback interface is not a contract in its own right—it’s one half of a duplex contract. So we need to modify the existing IChatService to associate it with this new callback interface (see Example 13-9).

[ServiceContract(
    CallbackContract=typeof(IChatClient),
    SessionMode=SessionMode.Required)]
public interface IChatService
{
    [OperationContract]
    bool Connect(string name);

    [OperationContract]
    void PostNote(string note);

    [OperationContract]
    void Disconnect();
}

By setting the ServiceContract attribute’s CallbackContract property, we’ve declared that this is a duplex contract, and have identified the interface that defines the client side of the contract. Example 13-9 also makes a couple of other changes that turn out to be necessary for our service to work as intended: we’ve set the SessionMode property of the ServiceContract attribute, and we’ve added a couple of extra methods to enable clients to connect and disconnect. We’ve also removed the string name argument from PostNote—as you’ll see, this will turn out to be redundant. All of these changes are related to sessions.

[ServiceBehavior(
    InstanceContextMode=InstanceContextMode.Single,
    ConcurrencyMode=ConcurrencyMode.Reentrant)]
public class ChatService : IChatService
{

private Dictionary<IChatClient, string> clientsAndNames =
     new Dictionary<IChatClient, string>();

public bool Connect(string name)
{
    if (clientsAndNames.ContainsValue(name))
    {
        // Name already in use, so refuse connection
        return false;
    }

    IChatClient clientCallback =
        OperationContext.Current.GetCallbackChannel<IChatClient>();

    // clientsAndNames is shared state, but we're not locking
    // here, because we're relying on ConcurrentMode.Reentrant
    // to give us messages one at a time.
    clientsAndNames.Add(clientCallback, name);
    Console.WriteLine(name + " connected");

    return true;
}

OperationContext.Current.GetCallbackChannel<IChatClient>()

public void PostNote(string note)
{
    IChatClient clientCallback =
        OperationContext.Current.GetCallbackChannel<IChatClient>();
    string name = clientsAndNames[clientCallback];

    Console.WriteLine("{0}: {1}", name, note);

    // ToArray() makes copy of the collection. This avoids an
    // exception due to the collection being modified if we have
    // to disconnect a client part way through the loop.
    KeyValuePair<IChatClient, string>[] copiedNames =
        clientsAndNames.ToArray();
    foreach (KeyValuePair<IChatClient, string> client in copiedNames)
    {
        // Avoid sending the message back to the client that just sent
        // it - they already know what they just typed.
        if (client.Key != clientCallback)
        {
            Console.WriteLine("Sending note to {0}", client.Value);
            try
            {
                client.Key.NotePosted(name, note);
            }
            catch (Exception x)
            {
                Console.WriteLine("Error: {0}", x);
                DisconnectClient(client.Key);
            }
        }
    }
}

private void DisconnectClient(IChatClient clientCallback)
{
    string name = clientsAndNames[clientCallback];
    Console.WriteLine(name + " disconnected");
    clientsAndNames.Remove(clientCallback);
}

public void Disconnect()
{
    IChatClient clientCallback =
        OperationContext.Current.GetCallbackChannel<IChatClient>();
    DisconnectClient(clientCallback);
}

<endpoint address=""
          binding="wsHttpBinding"
          contract="ChatServerLibrary.IChatService">
</endpoint>

error CS1729: 'ChatClient.ChatService.ChatServiceClient' does not contain
a constructor that takes 0 arguments

[CallbackBehavior(ConcurrencyMode=ConcurrencyMode.Reentrant)]
class ChatCallback : IChatServiceCallback
{
    public void NotePosted(string from, string note)
    {
        Console.WriteLine("{0}: {1}", from, note);
    }
}

ChatCallback callbackObject = new ChatCallback();
InstanceContext clientContext = new InstanceContext(callbackObject);
ChatServiceClient chatProxy = new ChatServiceClient(clientContext);

Console.WriteLine("Please enter your name:");
bool ok = false;
while (!ok)
{
    string name = Console.ReadLine();
    ok = chatProxy.Connect(name);
    if (!ok)
    {
        Console.WriteLine("That name is taken. Please try another.");
    }
}

chatProxy.PostNote(note);

chatProxy.Disconnect();

Service ready
Ian connected
Matthew connected

The most common starting point for client-side HTTP code is the WebClient class in the System.Net namespace. It offers a few ways of working with HTTP, starting from very simple but inflexible methods, through to relatively complex mechanisms that give you complete control over detailed aspects of HTTP. We’ll start with the simplest ones.

Uri blog =
   new Uri("http://www.interact-sw.co.uk/iangblog/");

WebClient client = new WebClient();
string pageContent = client.DownloadString("http://oreilly.com/");

Console.WriteLine(pageContent);

byte[] data =
   client.DownloadData("http://oreilly.com/images/oreilly/oreilly_large.gif");

client.DownloadFile("http://oreilly.com/", @"c:	emporeilly.html");

client.DownloadFileCompleted += OnDownloadComplete;
client.DownloadFileAsync(new Uri ("http://oreilly.com/"), @"c:	emp");

...

static void OnDownloadComplete(object sender, AsyncCompletedEventArgs e)
{
    MessageBox.Show("Download complete");
}

WebClient client = new WebClient();
Stream feedStm = client.OpenRead("http://feeds.feedburner.com/oreilly/news");
XDocument feedXml = XDocument.Load(feedStm);

string ns = "http://www.w3.org/2005/Atom";
var entries = from entryElement in feedXml.Descendants(XName.Get("entry", ns))
              select new
              {
                  Title = entryElement.Element(XName.Get("title", ns)).Value,
                  Link = entryElement.Element(XName.Get("link", ns)).
                                Attribute("href").Value
              };
foreach (var entry in entries)
{
    Console.WriteLine("{0}: {1}", entry.Title, entry.Link);
}

WebRequest and WebResponse are abstract base classes for a family of classes that provide the most detailed level of control over web requests. The concrete HttpWebRequest and HttpWebResponse classes add details specific to HTTP, and .NET also offers specialized FtpWebRequest/Response and FileWebRequest/Response classes. This section will mainly focus on the HTTP classes.

The main limitation with the WebClient-based mechanisms we’ve explored so far is that they focus on the content of the request or the response. They don’t provide any way to work with standard HTTP features such as the content type header, the UserAgent string, cache settings, or proxy configuration. But if you use HttpWebRequest and HttpWebResponse, all the detailed aspects of HTTP are available to you.

The cost of this power is additional verbosity. The main difference is that you end up with one object to represent the request and one to represent the response, in addition to streams representing the data being sent or received. Moreover, the only way to access the data with these classes is through streams. To do the same job as Example 13-11—fetching the data from a particular URL into a string—requires the rather more complex code shown in Example 13-13.

HttpWebRequest req = (HttpWebRequest) WebRequest.Create("http://oreilly.com/");
using (HttpWebResponse resp = (HttpWebResponse) req.GetResponse())
using (Stream respStream = resp.GetResponseStream())
using (StreamReader reader = new StreamReader(respStream))
{
    string pageContent = reader.ReadToEnd();
    Console.WriteLine(pageContent);
}

The two casts on the first two lines of Example 13-13 are a little messy, but are, unfortunately, usually necessary. The WebRequest family of classes is extensible to multiple protocols, so most of the methods are declared as returning the abstract base types, rather than the concrete types—the exact type returned depends on the kind of URL you use. So if you need access to a protocol-specific feature, you end up with a cast. In fact, Example 13-13 isn’t using anything protocol-specific, so we could have avoided the casts by declaring req and resp as WebRequest and WebResponse, respectively. However, the usual reason for using these classes is that you do in fact want access to HTTP-specific information. For example, you might want to simulate a particular web browser by setting the user agent string, as shown in Example 13-14.

HttpWebRequest req = (HttpWebRequest) WebRequest.Create("http://oreilly.com/");
req.UserAgent = "Mozilla/5.0 (iPod; U; CPU iPhone OS 2_2_1 like Mac OS X; en-us)
AppleWebKit/525.18.1 (KHTML, like Gecko) Mobile/5H11a";

... as before

This code has been split across multiple lines, as the user agent string is too wide to fit. This would let you discover what response a website would send if the request came from an Apple iPhone. (Many websites adapt their content for different devices.)

As you’d expect, asynchronous operation is available so that you can avoid blocking the current thread while waiting for network operations to complete. But it looks slightly different from the WebClient mechanisms we’ve seen so far, because of the way in which the methods you call can change when the request gets sent. No network communication happens at the point where you create the request, so there is no asynchronous method for that. Remember, the request object represents all the settings you’d like to use for your HTTP request, so it won’t actually attempt to send anything until you’ve finished setting the request’s properties and tell it you’re ready to proceed.

There are two ways in which you can cause an HttpWebRequest to send the request. Asking for the response object will cause this, but so will asking for a request stream—the request’s GetStream method returns a write-only stream that can be used to supply the body of the request for POST or similar verbs (much like WebClient.OpenWrite). This stream will start sending data over the network as soon as your code writes data into the stream—it doesn’t wait until you close the stream to send the data all in one go. (For all it knows, you might be planning to send gigabytes of data.) This means that by the time it returns the stream, it needs to be ready to start sending data, which means that the initial phases of the HTTP request must be complete—for example, if the request is going to fail for some reason (e.g., the server is down, or the client machine has lost its network connection), there’s no point in attempting to provide the data for the request. So you’ll be notified of failures of this kind when you ask for the stream.

The upshot of all this is that GetStream is a blocking method—it won’t return until the server has been contacted and the request is underway. So there’s an asynchronous version of this. But WebRequest doesn’t support the event-based pattern that WebClient uses. Instead, it uses the more complex but slightly more flexible method-based Asynchronous Programming Model, in which you call BeginGetRequestStream, passing in a delegate to a method that the request will call back once it’s ready to proceed, at which point you call EndGetRequestStream. This Begin/End pattern is very common in .NET and will be discussed in Chapter 16.

The second way in which the sending of the request can be triggered is to ask for the response object—if you haven’t already asked for the request stream (e.g., because you’re doing a GET, so there is no request body) the request will be sent at this point. So GetResponse also has an asynchronous option. Again, this uses the method-based asynchronous pattern. Example 13-15 shows a version of Example 13-13 modified to get the response object asynchronously.

HttpWebRequest req = (HttpWebRequest) WebRequest.Create("http://oreilly.com/");
req.BeginGetResponse(delegate(IAsyncResult asyncResult)
{
    using (HttpWebResponse resp = (HttpWebResponse)
                                      req.EndGetResponse(asyncResult))
    using (Stream respStream = resp.GetResponseStream())
    using (StreamReader reader = new StreamReader(respStream))
    {
        string pageContent = reader.ReadToEnd();
        Console.WriteLine(pageContent);
    }
}, null);

This example uses an anonymous method as the completion callback, which allows the code to retain a similar structure to the original, synchronous version. But you need to be mindful that the code that handles the response in Example 13-15 is now a separate method, and could run some considerable length of time after the call to BeginGetResponse returns, and probably on a different thread. So as with the event-based pattern, you’ll need to ensure that your application runs for long enough for the operation to complete—having some outstanding asynchronous operations in progress will not keep your process alive if all of the nonbackground threads exit.

Example 13-14 shows just one of the HTTP protocol features you can customize—the UserAgent string. Many similar settings are available, many of which are quite obscure, so we won’t go through all of them here. That’s what the MSDN reference is for. But we will cover the most common cases.

HttpWebRequest request =
    (HttpWebRequest) WebRequest.Create("http://intraweb/");
request.Credentials = CredentialCache.DefaultCredentials;

...

HttpWebRequest request =
    (HttpWebRequest) WebRequest.Create("https://intraweb/");
request.Credentials = new NetworkCredential("user1", "p@ssw0rd");

...

<configuration>
  <system.net>
    <defaultProxy enabled="false" />
  </system.net>
</configuration>

HttpWebRequest request =
    (HttpWebRequest) WebRequest.Create("https://intraweb/");
request.Proxy = new WebProxy("http://corpwebproxy/");

HttpRequestCachePolicy cachePolicy = new HttpRequestCachePolicy(
    HttpRequestCacheLevel.CacheIfAvailable);
HttpWebRequest request =
    (HttpWebRequest) WebRequest.Create("https://intraweb/");
request.CachePolicy = cachePolicy;

CookieContainer container = new CookieContainer();

Uri address = new Uri("http://amazon.com/");
HttpWebRequest req = (HttpWebRequest) WebRequest.Create(address);
HttpWebResponse resp = (HttpWebResponse) req.GetResponse();

CookieCollection cookies = resp.Cookies;
container.Add(address, cookies);

Uri address = new Uri("http://oreilly.com/");
HttpWebRequest newReq = (HttpWebRequest) WebRequest.Create(address);
newReq.CookieContainer = container;

The Internet uses a family of protocols typically known collectively as TCP/IP. The lowest level is IP, which is short for Internet Protocol. This is the means by which all network traffic flows across the Internet—when you buy an Internet connection, you’re buying the ability to deliver information from your computer to the Internet, and vice versa, via IP.

IP’s main job is the ability to get packets (as individual messages are called in networking) of data between different computer networks (hence internet). For example, data sent by a web server in a data center out of its network port somehow needs to make its way to your home WiFi network. These networks are connected together by routers, whose job is to work out where to send IP packets next; there are well-defined rules for how they should do this, ensuring that data ends up at the machine it’s meant for. This process depends on the IP address—a number that identifies a machine in a way that makes it possible for routers to work out how to route messages to that machine.

If you’re using sockets, you will need to work with IP addresses because they’re how you identify the machine you’d like to communicate with. You can typically just treat them as opaque identifiers, wrapped by the IPAddress class in the System.Net namespace. But there’s one aspect of IP addressing that it’s worth being aware of: the distinction between IPv4 and IPv6 addresses. See the sidebar below.

While the Internet protocol uses numbers to identify machines, users are more familiar with names such as oreilly.com and www.microsoft.com. The Internet has a system called the Domain Name Service (DNS)—your Internet service provider gives you access to this as part of your connection—whose job is to convert these textual names into the IP addresses required to communicate with the machines (or hosts, as the entities associated with IP addresses are conventionally called). Example 13-22 uses the Dns class in the System.Net namespace to look up the IP addresses for a particular hostname. DNS can associate multiple addresses with a name; for example, a DNS name may have both an IPv4 and an IPv6 address. This code loops through all the addresses, printing their type and value. (If you call ToString() on an IPAddress, which is what Console.WriteLine will do in Example 13-22, it’ll return the standard string representation for the numeric address.)

IPHostEntry hostDnsEntry = Dns.GetHostEntry("localhost");
foreach(IPAddress address in hostDnsEntry.AddressList)
{
    Console.WriteLine("Type: {0}, Address: {1}", address.AddressFamily,
                                                 address);
}

This example looks up the special hostname localhost, which always refers to the local machine on which the program is running. Both IPv4 and IPv6 define special addresses that are reserved to refer to the local machine, so if you run Example 13-22, you’ll see that it prints out two addresses, one for IPv6 and one for IPv4:

Type: InterNetworkV6, Address: ::1
Type: InterNetwork, Address: 127.0.0.1

Many DNS entries don’t have an IPv6 address, and if you modify Example 13-22 to look up such an address (e.g., at the time of this writing, w3.org has only an IPv4 address) you’ll see just one address back from GetHostEntry:

Type: InterNetwork, Address: 128.30.52.45

Armed with an IP address for the machine we want to talk to, we now have enough information for the Internet to deliver IP packets to the target machine. But there are a couple of issues to resolve. First, there’s the question of how the receiving machine will know what to do with the packet when it arrives. Second, there’s the problem that the Internet is fundamentally unreliable. TCP (the Transmission Control Protocol) offers a solution to both of these problems.

The Internet does not guarantee to deliver all IP packets. It can’t. Suppose you are using a machine connected to the Internet with a 100 Mbps connection and you try to send data at full speed to a machine that is connected with a 56 Kb modem. (Remember those? In some parts of the world, they’re still used. If you get a chance, try using a modern website via a 56 Kb dial-up connection, and then marvel at the fact that 56 kbps modems were once considered really fast.) As we send data to this bandwidth-impoverished machine, the routers between us and them will initially try to manage the speed difference—a router connecting a fast network to a slower network will store incoming packets from the fast network in its memory, and they queue up while it plays them out in slow motion to the target network. But eventually it’ll run out of memory, at which point it’ll just start discarding packets.

At busy times of the day, packets may get discarded even if both ends of the connection can operate at the same speed—perhaps the route the traffic needs to take through the Internet between the two networks includes busy links that just don’t have the bandwidth to support all the traffic that all of the ISP’s customers are trying to send. So network congestion can also cause packet loss, even in the absence of speed mismatches.

The upshot of this is that IP is not a reliable protocol—you get what’s sometimes called a best effort service. In attempting to deliver your data, the Internet will give it its best shot, but there are no guarantees. (You may have a service level agreement with your ISP that makes statistical guarantees about the proportion of data it will successfully deliver to and from the boundaries of the ISP’s network infrastructure, but there are no guarantees for any single packet, nor can your ISP guarantee what will happen to your data once it has been passed off to someone else’s network.)

To add to the fun, IP doesn’t even guarantee to deliver messages in the same order you sent them. ISPs might have multiple routes through their network to ensure reliability in the face of individual link failures, or just to ensure enough bandwidth to cope with high loads. So if you send a series of IP packets to the same computer, not all of those packets will necessarily take the same route—they might be split across two or more routes. Some of those routes may prove to be quicker, meaning that the packets can arrive at their destination in a different order than you sent them.

Writing networked applications can be challenging if you have no idea whether any particular message will be received, nor any way of knowing in what order the ones that do arrive will turn up. So to make life easier, we have the Transmission Control Protocol—the TCP in TCP/IP. This is a protocol that sits on top of IP and adds some useful features. It provides support for connections—rather than each packet being handled in isolation, each transmission is part of the sequence of communication occurring over the connection. TCP puts sequence numbers into each IP packet so that it can detect when packets arrived out of order. And finally, the receiving machine acknowledges receipt of each message. Clients use this to work out how fast the messages are getting through, which enables them to send data at a rate that matches the network’s ability to deliver, avoiding problems with mismatched network speeds and network congestion. And clients also use this to work out when data didn’t get through and needs to be resent.

These features enable TCP to offer a data transmission service that sends data in order, at a rate that will not try to exceed the capacity of the network routes available and in a fashion that is reliable in the face of occasional packet loss. A socket is usually just an API on top of a TCP connection that presents a stream-style API—your program can write data into a socket stream, and the TCP/IP networking code running on the computers at both ends uses TCP to ensure that the program at the receiving end has another socket stream from which it can read the exact same sequence of bytes you wrote into the stream. The programs don’t need to know about out-of-order delivery or packet loss. As long as the networks are not hopelessly lossy, it looks like there is perfectly reliable in-order transmission. TCP sockets are symmetrical, in that both ends can send and receive data. And the directions are independent—communication can be full duplex, so there’s no need for the two ends to take it in turns.

TCP also solves the problem of how the receiving computer knows what it’s supposed to do with incoming data. A single computer may offer many network services—a small company might run the intranet web server, file server, and email server on the same computer, for example. So TCP adds the concept of port numbers. A service on a target machine will be associated with a particular number. There’s a central administrative body called IANA—the Internet Assigned Numbers Authority—which (among other things) assigns and publishes port numbers for common services. For example, IANA has designated port 80 as the TCP port on which HTTP servers usually accept incoming requests. When a web browser (or the WebClient class we saw earlier) fetches a resource via HTTP, it does so by opening a TCP connection to port 80.

Let’s look at a real example. We’re going to connect to a service using a very old and very simple protocol called Daytime Protocol. This hasn’t changed since its specification was published in 1983—you can find its definition in a document called RFC867 at http://www.faqs.org/rfcs/rfc867.html. It’s remarkably simple: clients open a TCP connection to port 13 on a server that offers the daytime service, and the server will send back the time of day as text and then close the connection. The specification is pretty vague about the format—it says this:

There is no specific syntax for the daytime.  It is recommended that
   it be limited to the ASCII printing characters, space, carriage
   return, and line feed.  The daytime should be just one line.

It then goes on to give examples of a couple of popular formats, but servers are free to do pretty much anything they like.

This is a service that cannot be accessed with the WebClient or any of the WebRequest family of classes—those types expect data to be layered inside HTTP (or sometimes another higher-level protocol such as FTP), but Daytime Protocol just makes very basic, direct use of plain TCP. So we need to use sockets if we want to access such a service.

The U.S. government’s National Institute of Standards and Technology (NIST) lists a few servers that offer this daytime service. Once such machine, located in Redmond, Washington, has the DNS name of time-nw.nist.gov. We’ll use that. To start with, we need to look up its IP address, which we’ll do using a similar technique to Example 13-22:

IPHostEntry hostDnsEntry = Dns.GetHostEntry("time-nw.nist.gov");
IPAddress serverIp = hostDnsEntry.AddressList[0];

Next, we need to open a TCP connection to port 13 (the daytime service port) on that machine. To do this, we’ll need a Socket object.

The System.Net.Sockets namespace defines the Socket class, which makes the socket features of the underlying operating system available from .NET. We use a Socket when we want to open a TCP connection to a remote service:

Socket daytimeSocket = new Socket(
    serverIp.AddressFamily,
    SocketType.Stream,
    ProtocolType.Tcp);

The Socket constructor needs three pieces of information. It needs to know the address family we will use to identify the server (e.g., IPv4 or IPv6). It also needs to know what style of communication we’re expecting—we’re asking for stream-like communication. (Some protocols support some other styles of communication, but with TCP you always specify Stream here.) Finally, we specify the specific protocol we’d like to use—TCP in this case.

Note that we don’t specify where we’re connecting to yet. That information doesn’t go in the constructor because not all sockets work the same way—some protocols support transmission patterns other than simple point-to-point connections. So the Socket class requires that we first say what sort of socket we want before going on to say what we’re trying to communicate with. We supply that information when we connect to the service:

daytimeSocket.Connect(serverIp, 13);

Remember, port 13 is the port number allocated by IANA for the daytime service. We’re going to retrieve the time of day as text from this service, so we declare a variable to hold the result:

string data;

Sockets represent all data as bytes. (Or more precisely, octets, which are 8-bit bytes. Back in the old days, some computers used other byte sizes, and you occasionally come across evidence of this—for example, some parts of the Internet email system guarantee to transfer 8-bit bytes, and may truncate your data to seven bits per byte.) The Daytime Protocol specification says that the service will return text using the ASCII encoding, so we need something that can convert a stream of bytes containing ASCII into a .NET string. Example 13-23 does this.

using (Stream timeServiceStream = new NetworkStream(daytimeSocket, true))
using (StreamReader timeServiceReader = new StreamReader(timeServiceStream,
                                                         Encoding.ASCII))
{
    data = timeServiceReader.ReadToEnd();
}

A few things are going on here. First, we constructed a NetworkStream—this class derives from Stream, and it’s how .NET lets us treat a socket-based connection in the same way as any other Stream. In general, the use of streams is optional because the Socket class provides methods that let you read and write data directly. But in this example, getting an actual Stream object is useful because we can plug it into a StreamReader. StreamReader takes a stream that contains text and can convert the bytes in that stream into string objects. Example 13-23 uses the StreamReader class’s ReadToEnd method—this asks to read all of the data in the stream to the very end and to return it as a single string.

Notice that the first line of Example 13-23 passes true as a second argument to the NetworkStream constructor. This tells the NetworkStream that we’d like it to take ownership of the Socket object—once we are done with the NetworkStream and call Dispose on it, it will shut down the Socket object for us. That’ll happen at the end of the block for the using statement here. This is important: we must close connections when we have finished with them, because otherwise, we could end up hogging resources on the server unnecessarily.

Having fetched the data and closed the socket, we finally print out the data:

Console.WriteLine(data);

Example 13-24 shows the whole example.

IPHostEntry hostDnsEntry = Dns.GetHostEntry("time-nw.nist.gov");
IPAddress serverIp = hostDnsEntry.AddressList[0];

Socket daytimeSocket = new Socket(
    serverIp.AddressFamily,
    SocketType.Stream,
    ProtocolType.Tcp);

daytimeSocket.Connect(serverIp, 13);
string data;
using (Stream timeServiceStream = new NetworkStream(daytimeSocket, true))
using (StreamReader timeServiceReader = new StreamReader(timeServiceStream))
{
    data = timeServiceReader.ReadToEnd();
}
Console.WriteLine(data);

If you run the program, you’ll see something like this:

55059 09-08-16 06:29:42 50 0 0 912.5 UTC(NIST) *

It’s not strictly relevant to the use of sockets, but if you’re interested, here’s what the numbers this particular server returns all mean. The first number is the number of days that have elapsed since midnight on November 17, 1858. (If you’re curious to know why anyone might find that useful, search the Web for “Modified Julian Date”.) The set of three numbers that follows are the year, month, and date (2009, August 16 in this example), followed by the time of day as UTC (time zone zero, or as we British authors like to call it, Greenwich Mean Time). The 50 signifies that daylight saving time is in effect where the server is located, and the following two zeros indicate respectively that no leap second will be added this month and that the server believes it is not currently experiencing any problems. The next number indicates that the server is deliberately advancing times by 912.5 ms to compensate for transmission delays in the Internet.

That’s all you need to do to use a service with sockets—construct a suitably configured socket, call Connect, and then read data. If the service you’re using expects to be sent data, you can also write data into the NetworkStream. Obviously, you need to be prepared for errors—the Connect method will throw an exception if it is unable to connect to the service, and you should also be prepared to get errors anytime you try to read or write data with a socket; even if you connect successfully, parts of the network may later fail, severing the connection to the service. Again, .NET indicates this by throwing exceptions.

We’ve looked at only half of the story so far—what if you wanted to write a program that implements a service like the daytime service? You can do this with the Socket class too, but it’s a little more involved.

To implement a TCP-based service, we need to make sure our program is ready to receive requests when they come in. If a computer receives an incoming TCP connection request for some port number and no programs are currently listening for connections on that port number, it will simply reject the request. So the first thing we need to do is create a socket that listens for incoming connections (see Example 13-25).

using (Socket daytimeListener = new Socket(
    AddressFamily.InterNetworkV6,
    SocketType.Stream,
    ProtocolType.Tcp))
{
    daytimeListener.SetSocketOption(
        SocketOptionLevel.IPv6, (SocketOptionName) 27, 0);

    IPEndPoint daytimeEndpoint = new IPEndPoint(IPAddress.IPv6Any, 13);
    daytimeListener.Bind(daytimeEndpoint);

    daytimeListener.Listen(20);
    ...

As with the client side, we create a Socket object, once again specifying the address family, socket type, and protocol. (In this particular example, the lifetime we require for the Socket happens to be the same as the lifetime of our Main method, so a using statement is an appropriate way to manage the socket’s disposal.) Whereas with the client we could just use whichever IP address type came back from Dns.GetHostEntry, when we write a server we need to state which sort of address we want to listen on. Example 13-25 chooses the InterNetworkV6 family to enable the use of IPv6. If you want to support just IPv4 you can specify InterNetwork. In fact, this example supports both kinds of address—the call to SetSocketOption after the constructor puts this socket into dual mode, meaning that it’s able to accept connections through either IPv4 or IPv6. (The magic number 27 that appears in the call corresponds to a value defined by the Windows SDK that doesn’t currently have an equivalent entry in the SocketOptionName enumeration. So unfortunately, this is just a magic incantation that you need to know in order to enable a socket to accept incoming connections on either IP version.)

Next, we call Bind—this is how our application claims ownership of a particular TCP port number. We’ve built an IPEndPoint object that specified port 13—the port number for the daytime service—and also indicates which of the local machine’s addresses we’d like to listen on. Machines often have multiple addresses—in fact, a connected machine usually has at least two IPv4 and two IPv6 addresses. Earlier we saw the special machine name localhost, and this corresponds to special IPv4 and IPv6 addresses. Even a completely disconnected machine has these addresses—the IPv4 address 127.0.0.1 and the IPv6 address ::1 always refer to the local machine. On top of this, a machine usually gets both an IPv4 and an IPv6 address when it connects to a network.

It’s possible to create sockets that listen on only the local addresses. That might not sound very useful, as it means that you cannot connect to those sockets over the network. In fact, this is quite handy for software developers. You can run services on your machine that are inaccessible over the network but which programs running locally on your machine can still connect to. This may allay the concerns of your IT administrators who don’t like the idea of desktop machines running web servers or other services because they (quite reasonably) consider such things to be a security risk. If you configure a service to listen on only these local addresses, it won’t be visible on the network, making it less likely to be a security liability. The test web server that Visual Studio can set up for ASP.NET web projects works this way—it uses only a local address, so it is accessible only to browsers running on the same machine. Note that this technique is not very useful outside of a developer machine. A local socket cannot be secured, so it will be accessible to any user logged in to the machine. For a developer box that’s fine, but on server systems, this might constitute a security risk. So you should avoid using local sockets.

Example 13-25 chooses the special address IPAddress.IPv6Any, which means that the socket will accept incoming connections directed to any of the computer’s IPv6 addresses. And since we’ve configured this to be a dual-mode socket, it will also accept incoming connections for any of the computer’s IPv4 addresses too.

If some other program on the computer is already using TCP port 13, the call to Bind will throw an exception—any particular port number can be owned by only one process on the machine at any one time. If Bind succeeds the port is now ours, and so we can call Listen to indicate that we’re ready for incoming connection requests.

As you can see from the last line of Example 13-25, Listen takes a single argument. This indicates the maximum backlog for this socket. The backlog allows for the situation where new connections arrive faster than our server can handle them. As you’ll see shortly, we need to execute some code to accept each incoming connection, and at busy times, we might lag behind—if a new connection request comes in before we’ve managed to accept the last one, that new request goes into the backlog queue. If the number of requests in the backlog gets as high as the number we pass to Listen, the OS will start rejecting any further requests until our application catches up.

Our socket is now in a listening state, which means that if client programs start trying to connect to our computer on port 13, the OS knows those connections are destined for our program. The next thing our code has to do is accept those connections. Example 13-26 does this in a loop so that it can keep accepting connection requests for as long as the program runs.

while (true)
{
    Socket incomingConnection = daytimeListener.Accept();
    using (NetworkStream connectionStream =
                        new NetworkStream(incomingConnection, true))
    using (StreamWriter writer = new StreamWriter(connectionStream))
    {
        writer.WriteLine(DateTime.Now);
    }
}

This code calls Accept on the listening Socket. If there are currently no clients trying to connect to the service, this call will block—it won’t return until there’s a client. Once at least one client is attempting to use the service, this will return, handing back another Socket object. The Socket API is designed to allow multiple simultaneous connections to a single service, and so each call to Accept returns a new Socket. Your server will end up with one Socket object for each distinct connected client, plus the one listening Socket.

Example 13-26 chooses to deal with the clients one at a time—the loop accepts a single connection, sends a response, closes the connection, and then moves on to the next client. So this particular server will have up to two active Socket objects at any one time—the one for the client connection it’s currently handling, and the one Socket that is listening for incoming connections. You don’t need to do this—it’s very common to accept new connections on a listening socket when you already have open connections that came from the same socket. (For example, a web server does not insist on finishing the processing of whatever request it’s handling at the moment before starting work on the next one. It’s common for a server to have hundreds of inbound connections open simultaneously.) But since this particular service can do all the work it needs to do and then close the connection immediately, it doesn’t have any particular reason to open several connections simultaneously.

The code that does the work here is pretty similar to the client code we saw in Example 13-24. As before, we create a NetworkStream, passing true to indicate that we want to close the Socket when we dispose the stream. This time we create a StreamWriter instead of a StreamReader, because we’re now implementing the server, and it’s going to be sending data rather than receiving it. We call the writer’s WriteLine method, passing the current date and time, which, as you may recall, was the whole point of this service in the first place. Example 13-27 shows the completed code.

using (Socket daytimeListener = new Socket(
    AddressFamily.InterNetworkV6,
    SocketType.Stream,
    ProtocolType.Tcp))
{
    daytimeListener.SetSocketOption(SocketOptionLevel.IPv6,
                                    (SocketOptionName) 27, 0);

    IPEndPoint daytimeEndpoint = new IPEndPoint(IPAddress.IPv6Any, 13);
    daytimeListener.Bind(daytimeEndpoint);
    daytimeListener.Listen(20);

    while (true)
    {
        Socket incomingConnection = daytimeListener.Accept();
        using (NetworkStream connectionStream =
                            new NetworkStream(incomingConnection, true))
        using (StreamWriter writer = new StreamWriter(connectionStream,
                                                        Encoding.ASCII))
        {
            writer.WriteLine(DateTime.Now);
        }
    }
}

The first time you run this code, you can expect to see the warning dialog shown in Figure 13-9 (unless you’ve disabled your Windows Firewall). By default, the Windows Firewall will notify you when programs start listening for incoming network connections out of the blue. Typically, a program that has a legitimate need to accept connections will register itself with the firewall when it’s installed, so when a program that the firewall knows nothing about suddenly starts listening for incoming connections, that’s likely to be a sign of trouble—it’s exactly the sort of thing that malware would do if it wanted to make your machine available to hackers for distributing spam or launching distributed denial of service attacks. Of course, in this case, you know that the code is legitimate because you just wrote it, and the reason your program hasn’t gone through the official route of registering itself during installation is that you only just wrote the code, and you haven’t written the Windows Installer .msi yet. So as a developer, you expect to see this sort of warning for your own programs when they listen for incoming connections. (You didn’t see this for the WCF example earlier because it was using the specially reserved design-time address space that Visual Studio sets up when you install it. But that works only for HTTP—there’s no equivalent for sockets.) You just need to click Unblock, and you shouldn’t see this warning again for this particular program.

Figure 13-9. Firewall warning when listening for connections

To test this program, you can use the client program you wrote earlier. The simplest approach will be to run two copies of Visual Studio, one for the client and one for the server. (Or you could configure Visual Studio to run both projects, as we did earlier.) Run the server first. Then go to the client, modify the line that specifies the machine name—replace time-nw.nist.gov with localhost—and then run the client. It should print out the current time and date. The format will be different from the one used by the NIST server—it’ll be the default used by the DateTime type. But that’s fine, because the Daytime Protocol specification says we’re free to use any format we like as long as it’s ASCII and it fits on a single line.

And that’s it for basic socket use. Sockets also support asynchronous versions of all the methods—in fact, they support both the event-based and the method-based asynchronous styles we encountered earlier. Since you’ve already seen this kind of code in action, we won’t show it again here, but we’ll come back to asynchronous programming techniques later in the book.