How to: Use Transport Security

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

The .NET Compact Framework version 3.5 supports the use of the HTTPS transport to connect to a Windows Communication Foundation (WCF) service on the desktop. It includes support for server authentication and client authentication.

This topic provides an example of the service configuration and shows how to modify client code for mutual authentication.

Note Note

For server authentication only, a client certificate is not required. Message security is also supported in the .NET Compact Framework 3.5, but it is not used in this example.

To create the WCF service for the desktop

  1. Create and install a server certificate and a client certificate.

    These steps are specific to the certificate generation tool you are using (for example, Makecert.exe) and are beyond the scope of this topic. The following tasks will be necessary:

    • Create a self-signed certificate and name it (for example, use your company name: company).

    • Create a server certificate signed by company. The server certificate name must match the URL host name used to access the service

    • Create a client certificate signed by company.

    Note Note

    We recommend that you install the server certificate into the local machine instead of installing it to the current user. Otherwise, if the service is hosted in Internet Information Services (IIS) and you install it to the current user, it will not work.

  2. Create a new Web service project.

  3. Replace the Web.config file with the example shown in this step. Modify the following elements and attributes in the file:

    • Change the service name attribute to the new service you are using.

    • Change the behaviorConfiguration attribute to refer to the new behavior name.

    • Change the endpoint contract attribute to refer to the service interface.

    Note Note

    Make sure that the binding attribute value for the <endpoint> element is "basicHttpBinding". The .NET Compact Framework supports text encoding, but not binary encoding.

    <?xml version="1.0" encoding="utf-8" ?>
            <endpoint address=""
                      contract="ICalculatorService" />
            <endpoint address="mex"
                      contract="IMetadataExchange" />
            <binding name="transport">
              <security mode="Transport">
                <transport clientCredentialType="Certificate" />
        <!--For debugging purposes set the includeExceptionDetailInFaults attribute to true-->
            <behavior name="MyServiceTypeBehaviors">
              <serviceMetadata httpsGetEnabled="True" httpsGetUrl=""/>
              <serviceDebug includeExceptionDetailInFaults="False" />
                   <authentication trustedStoreLocation="LocalMachine"
  4. In the source code for the WCF service, remove any parameters specified in the ServiceContract and OperationContract attributes from your code.

    Note Note

    This sample does not implement support for parameters specified in contracts such as ServiceContract and OperationContract. If you need parameter support for these contracts, you can use the WCF .NET Compact Framework ServiceModel Utility tool (NetCFSvcUtil.exe) to generate client code. This tool builds support for many of these parameters into applications that are based on the .NET Compact Framework. NetCFSvcUtil.exe is available in the Power Toys for .NET Compact Framework. For more information, see Power Toys for .NET Compact Framework.

    The following example shows the WCF service source code for a simplified calculator application.

    <ServiceContract()>  _
    Public Interface ICalculatorService
        <OperationContract()>  _
        Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double 
        '<OperationContract()>  _
        Function Subtract(ByVal n1 As Double, ByVal n2 As Double) As Double
    End Interface
    Public Class CalculatorService
        Implements ICalculatorService
        Public Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculatorService.Add
            Return n1 + n2
        End Function
        Public Function Subtract(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculatorService.Subtract
            Return n1 - n2
        End Function
    End Class
  5. Create a Web site or virtual directory and reference your Web service project. On the Web server, configure the service to require HTTPS and a client certificate.

    Note Note

    In IIS, you must specify the server certificate and the client certificate.

  6. Start the Web server.

    If you want to view Web Services Description Language (WSDL) output and run the service on localhost, browse to https://localhost/CalculatorService/Service.svc?wsdl. Use the same Web project name that you specified for the WCF service.

  7. Verify that you can access the directory from a desktop browser and a device browser by using HTTPS.

    You must make sure that certificates are configured correctly before you can access the service. The Web server may also have to be configured to handle requests for a WCF service.

To create the .NET Compact Framework client

  1. While the service is running, open a command line and navigate to the directory where the WCF service is located.

  2. From the command line, run the WCF ServiceModel Desktop Utility tool (SvcUtil.exe) to generate a WCF client proxy. The following example shows the command-line invocation for SvcUtil in which the service is hosted on localhost:

    svcutil.exe /language:c# https://localhost/CalculatorService/Service.svc
  3. Remove unsupported attributes and elements from the generated client proxy code, including the following:

    • All System.ServiceModel attributes.

    • References to the IClientChannel class.

    • References to <endpoint> configuration names.

    • Method implementations that call methods of the ServiceContract interface on the internal channel.

    For an example of this step, see How to: Use the HTTP Transport.

  4. Create a client project.

  5. Add the generated client proxy to the project.

  6. In the generated proxy code, change the fully-qualified reference to ClientBase(Of TChannel) to the user-defined ClientBase class.

  7. In the generated proxy code, add method implementations by invoking the Call method in the user-defined ClientBase class.

    Public Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculatorService.Add
        Return System.Convert.ToDouble(MyBase.Call("Add", "", New String() {"n1", "n2"}, New Object() {n1, n2}, GetType(Double)))
    End Function
  8. Add the base class for the proxy to the project. This class is named ClientBase.

    Change the base class reference of your client proxy to point to your implementation of ClientBase.

    Note Note

    In this example, the CustomBodyWriter class in ClientBase supports only primitive types. To support non-primitive types, you have to extend the OnWriteBodyContents method. For example, you could call a custom serializer to serialize message data. In this case, you would translate code attributes in the generated client proxy to attributes that the XML serializer could consume. In this scenario, you must first add the following switch when you run SvcUtil: /serializer:xmlserializer http://endpoint.

    The following code shows an example of the ClientBase class. A ClientCredentials object is used to specify the X.509 certificate used by the client, which is named testuser in this example.

    Public Class ClientBase(Of TChannel As Class)
        Private requestChannel As IRequestChannel
        Private messageVersion As MessageVersion
        Public Sub New(ByVal binding As System.ServiceModel.Channels.Binding, ByVal remoteAddress As System.ServiceModel.EndpointAddress)
            'this.remoteAddress = remoteAddress;
            Me.messageVersion = binding.MessageVersion
            Dim parameters = New System.ServiceModel.Channels.BindingParameterCollection()
            ' Specifies the X.509 certificate used by the client.
            Dim cc As New ClientCredentials()
            cc.ClientCertificate.SetCertificate(StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "testuser")
            Dim channelFactory As IChannelFactory(Of IRequestChannel)
            channelFactory = binding.BuildChannelFactory(Of IRequestChannel)(parameters)
            Me.requestChannel = channelFactory.CreateChannel(remoteAddress)
        End Sub
        Public Function [Call](ByVal op As String, ByVal action As String, ByVal varnames() As String, ByVal varvals() As Object, ByVal returntype As Type) As Object
            'Message msg =
            '      action,
            '      new CustomBodyWriter(op, varnames, varvals,
            '"<ns passed in from Proxy>"));
            Dim msg As Message = Message.CreateMessage(Me.messageVersion, action, New CustomBodyWriter(op, varnames, varvals, "<ns passed in from Proxy>"))
            Dim reply As Message = requestChannel.Request(msg, TimeSpan.MaxValue)
            Dim reader As XmlDictionaryReader = reply.GetReaderAtBodyContents()
            reader.ReadToFollowing(op + "Result")
            Return reader.ReadElementContentAs(returntype, Nothing)
        End Function
    End Class
    Friend Class CustomBodyWriter
        Inherits BodyWriter
        Private op As String
        Private varnames() As String
        Private varvals() As Object
        Private ns As String
        Public Sub New(ByVal op As String, ByVal varnames() As String, ByVal varvals() As Object, ByVal ns As String)
            Me.op = op
            Me.varnames = varnames
            Me.varvals = varvals
            Me.ns = ns
        End Sub
        Protected Overrides Sub OnWriteBodyContents(ByVal writer As XmlDictionaryWriter)
            writer.WriteStartElement(op, ns)
            Dim i As Integer
            For i = 0 To varnames.Length
                writer.WriteElementString(varnames(i), varvals(i).ToString())
            Next i
        End Sub
    End Class
  9. Add the following references to ClientBase.cs:

  10. Add a class to instantiate and use the client proxy.

    The following example uses the binding object to specify transport security over HTTPS and the use of a client certificate for authentication. It also shows code that invokes the client proxy.

    Class Program
        ''' <summary>
        ''' The main entry point for the application.
        ''' </summary>
        <MTAThread()> _
        Shared Sub Main()
            Dim serverAddress As String = CalculatorServiceClient.ServiceEndPoint.Uri.AbsoluteUri
            Dim binding As New BasicHttpBinding()
            ' Specifies transport security over HTTPS and the use of a
            ' client certificate for authentication.
            binding.Security.Mode = BasicHttpSecurityMode.Transport
            binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Certificate
            Dim proxy = New CalculatorServiceClient(binding, New EndpointAddress(serverAddress))
            MessageBox.Show("Add 3 + 6...")
            MessageBox.Show(proxy.Add(3, 6).ToString())
            MessageBox.Show("Subtract 8 - 3...")
            MessageBox.Show(proxy.Subtract(8, 3).ToString())
        End Sub
    End Class
  11. Make sure that the client certificate has been placed into the current user's certificate store on the device.

  12. Build the client application and deploy it to your device.

  13. When the WCF service is running and your device is connected to the network, start the client application on the device.

The source code for the WCF service requires references to the following namespaces:

The source code for the ClientBase class requires references to the following namespaces:

The source code for the class that contains the Main method in the client application requires references to the following namespaces:

This example implements transport security based on mutual authentication. It does not implement message security.