NetHttpBinding

The NetHttpBinding sample demonstrates how to implement a binding that stacks HttpTransportBindingElement or the HttpsTransportBindingElement on top of the BinaryMessageEncodingBindingElement. The HTTP-based system-defined bindings that ship with Windows Communication Foundation (WCF), such as BasicHttpBinding or WsHttpBinding layer HTTP on top of the TextMessageEncodingBindingElement primarily to allow sending and receiving messages as Text/Xml to allow for interoperability. The TCP- and NamedPipe-based system-defined bindings that ship with Windows Communication Foundation (WCF), such as NetTcpBinding or NetNamedPipeBinding write and consume messages as binary. The binary format, though not interoperable, is more efficient and is tuned for performance.

Note

The setup procedure and build instructions for this sample are located at the end of this topic.

Note:

The samples may already be installed on your machine. Check for the following (default) directory before continuing. <InstallDrive>:\WF_WCF_Samples If this directory does not exist, go to Windows Communication Foundation (WCF) and Windows Workflow Foundation (WF) Samples for .NET Framework 4 to download all Windows Communication Foundation (WCF) and WF samples. This sample is located in the following directory. <InstallDrive>:\WF_WCF_Samples\WCF\Extensibility\Binding\NetHttpBinding

The sample demonstrates how you can use the architecture of WCF to combine binding elements that you want in your channel stack to configure your bindings the way you want them. The steps to create a custom binding are as follows:

1. Decide which of the binding elements you want to stack together to create your binding.

2. Make sure you know the order in which the binding elements must be stacked for the stack to work correctly. For example, you want to add the transport at the bottom of your stack.

3. Create your Binding class, which inherits from Binding. In this particular case, the NetHttpBinding also implements the ISecurityCapabilities interface because it allows the user of this binding to inspect the ProtectionLevel and whether their binding supports client and server authentication.

4. The binding exposes other properties that must be surfaced to the user to allow them to configure the constituent binding elements. For example, surface the BypassProxyOnLocal property so you can configure the same property on the underlying HTTP or HTTPS TransportBindingElement.

5. In the CreateBindingElements method, the sample demonstrates the order in which the binding elements must be stacked. For example, it adds the encoder first, and then the transport because the transport must be at the bottom of the binding stack.

6. Finally, implement the ApplyConfiguration method to allow the NetHttpBinding to be populated using configuration. In fact, there are several other classes that are required to allow your binding to be configurable from a configuration file. You can fortunately use the ConfigurationCodeGenerator tool to create these classes for you. The ConfigurationCodeGenerator tool is available as a WCF sample as well.

The NetHttpBinding Sample Service

The sample service that uses the NetHttpBinding is located in the service subdirectory. The binding used to configure the endpoint is the NetHttpBinding. The sample service is self-hosted using a Main method but could be hosted within Internet Information Services (IIS) as well.

The NetHttpBinding Sample Client

The client also configures its binding to the NetHttpBinding to connect to the service. The client demonstrates that it can configure the binding in code or configuration. The fact that it is able to configure the NetHttpBinding through configuration is made possible by the classes it added to expose the binding to configuration. As previously mentioned, the ConfigurationCodeGenerator tool can help you to generate these classes.

To set up and build the sample

1. Install ASP.NET 4.0 using the following command.

   %windir%\Microsoft.NET\Framework\v4.0.XXXXX\aspnet_regiis.exe /i /enable
   

2. Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.

3. To build the solution, follow the instructions in Building the Windows Communication Foundation Samples.

4. Make sure that the path includes the folder where Makecert.exe is located.

5. On the machine where server will be running, run Setup.bat from the sample install folder to create the server certificate and its issuer certificate required by the server.

6. On the same server machine, configure server certificate with HTTP.SYS following the instruction in the conceptual doc on Configuring HTTP and HTTPS.

To run the sample on the same machine

1. Launch Service.exe from service\bin. Service activity is displayed on the service console window.

2. Launch Client.exe from \client\bin. Client activity is displayed on the client console application.

3. Run Cleanup.bat to remove the certificates when you have finished with the sample.

To run the sample on across machines

1. Launch Service.exe from service\bin. Service activity is displayed on the service console window.

2. Because the server is self-hosted, you must specify an identity in the client's App.config file if you run the client and the server as domain users:

        <client>
          <endpoint
             name="EchoServer"
             address=
             https://localhost:8000/TestService/BinaryEncoderOverHTTP
             binding=
             "netHttpBinding" bindingConfiguration="netHttpBinding"
             contract=
             "Microsoft.ServiceModel.Samples.Client.IEchoService" >
             <identity>
                <userPrincipalName value="user_name@service_domain"/>
             </identity>
          </endpoint>
        </client>
   

3. Launch Client.exe from \client\bin: pass the HTTPS URL displayed in the service window as a command line parameter. Client activity is displayed on the client console application.

4. Run Cleanup.bat to remove the certificates when you have finished with the sample.