• Article

Configuring Web Service Usage in Silverlight Clients

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Silverlight version 4 provides a rich platform to write Internet applications. One of its key features is to enable the applications to communicate with Web services by using generated proxies. Silverlight 4 has added Web client configuration support that enables deployment-time configuration, such as changing the address of the targeted service endpoints or various settings, without having to rebuild and redeploy the binaries.

For Silverlight 4 applications, the client configuration file contains a subset of Windows Communication Foundation (WCF) client configuration. The Silverlight 4 configuration file must be named ServiceReferences.ClientConfig, and also must be packaged and deployed along with the application. The XAP file is a container of other files, similar to a Compressed Folder (“.zip”). If configuration needs to change at deployment time, it is possible to uncompress the XAP file, change the desired configuration setting, and compress the results into a new XAP file, all without recompiling the application.

Cc197941.note(en-us,VS.95).gifNote:
This topic focuses on configuring the default <customBinding> with <binaryMessageEncoding>.

Configuring a Silverlight Client

The Add Service Reference tool automatically generates the client configuration that is contained in the ServiceReferences.ClientConfig file.

Note that this file has a subset of the contents of the .NET Framework 3.0 configuration file that is used to configure the Windows Communication Foundation (WCF) client proxy. For more information about the WCF client configuration file, see Configuring Client Behaviors. Configuration consists of a <bindings> section and a <client> section, as can be seen in the following example. These sections are contained within the <system.serviceModel> element. The elements that configure the client to access the Service1 Web service that has an IService contract are contained within the <endpoint> element of the <client> element. The value of the bindingConfiguration attribute identifies the name of the binding used to configure the endpoint.

<configuration>
    <system.serviceModel>
        <bindings>
            <customBinding>
                <binding name="CustomBinding_Service1">
                    <binaryMessageEncoding />
                    <httpTransport 
                      maxReceivedMessageSize="2147483647" 
                      maxBufferSize="2147483647" />
                </binding>
            </customBinding>
        </bindings>
        <client>
            <endpoint 
              address="http://example1.com/Service1.svc" 
              binding="customBinding"
              bindingConfiguration="CustomBinding_Service1"
              contract="ServiceReference1.Service1"
              name="CustomBinding_Service1" />
        </client>
    </system.serviceModel>
</configuration>

Note that HTTP and HTTPS URLs are both supported, but the security mode must be properly configured. For more information, see the Configuring the Security Mode section below.

Configuring the Service Address

The address attribute of the service <endpoint> element identifies the address of the service. You can change the value of the address attribute if the service moves. For example, if the service moves from http://example1.com/Service1.svc to http://example2.com/Service1.svc when deployed, the following code shows how you would reconfigure the <endpoint>. What it illustrates is that you only have to change the value of the address attribute.

<endpoint 
   address="http://example2.com/Service1.svc"
   binding="customBinding"
   bindingConfiguration="CustomBinding_Service1"
   contract="ServiceReference1.Service1"
   name="CustomBinding_Service1" />

Silverlight 4 supports the resolution of relative service addresses. Provided the Silverlight XAP package is hosted at http://example2.com/application/ClientBin/Application.xap, the following addresses resolve as indicated:

If a service has more than one Silverlight-compatible endpoint, multiple <endpoint> elements might be present with the same contract attribute. The endpoints have different endpoint names, identified by the name attribute. Typically, the endpoints are distinguished by having different addresses specified by their respective address attributes. For example:

<client>
   <endpoint 
      address="http://uk.example.com/Service1.svc"
      binding="customBinding"
      bindingConfiguration="CustomBinding_Service1"
      contract="ServiceReference1.Service1"
      name="EuropeDataCenter" />
   <endpoint 
      address="http://jpn.example.com/Service1.svc"
      binding="customBinding"
      bindingConfiguration="CustomBinding_Service1"
      contract="ServiceReference1.Service1"
      name="AsiaDataCenter" />
    </client>

If multiple endpoints are configured, it is important to specify the endpoint name because it is required as a constructor argument when creating the proxy. For example, var p = new CustomerClient(“EuropeDataCenter”);. If you do not do this, an exception will occur. An exception will also occur if no endpoints are present in the configuration and you attempt to use a proxy constructor that takes an endpoint name or that takes no parameters.

Configuring Quotas, Time-outs, and Encoding

The <binding> element specifies how the Silverlight client will communicate with the service. Consider the basicHttpBinding, for example, which is one of the two system-provided bindings that can be configured in Silverlight version 4, and corresponds to the BasicHttpBinding that enables SOAP 1.1 over HTTP (or HTTPS). (The other standard binding available is the PollingDuplexHttpBinding, which configures a service endpoint for duplex communication with a polling client, but this binding must be configured in code, not in the ServiceReferences.ClientConfig file.)

The bindingConfiguration attribute specifies, by name, a particular configuration that affects how to communicate with the service. These configurations are found in the <binding> elements under the <basicHttpBinding> element in the <bindings> section. The point is that there might be more than one such <binding> element and they are identified by distinct name attributes.

You can change quota and time-out settings for the client by using the binding configuration. For example, you can change the value of the maximum size for the buffer that receives messages by specifying a new value for the maxBufferSize binding attribute, or you can change the value of the maximum size for a message that can be received by specifying a new value for the maxReceivedMessageSize. The values are specified in bytes. For example, to receive messages as large as 1 megabyte, you might use the following:

<binding 
   name="BasicHttpBinding_IService" 
   closeTimeout="00:59:00" 
   openTimeout="00:53:00" 
   receiveTimeout="00:15:00" 
   sendTimeout="00:21:00" 
   maxBufferSize="1048576" 
   maxReceivedMessageSize="1048576" 
   textEncoding="utf-8" >
   <security mode="None" />
</binding>
Cc197941.Warning(en-us,VS.95).gif Caution:
This value of receiveTimeout is not being respected in Silverlight 4 and setting it will not affect the behavior of the application.

The limit on the received message size is intended to limit exposure to DoS-style attacks. Note also that if you want to send large messages from Silverlight, it is the receiving side (that is, the service) that must be configured with sufficiently large quotas. For more information, see Additional Security Considerations for Service Access.

Binding configuration also enables you to configure time-outs for opening a channel to the service, sending a message, receiving a reply, and closing a channel. The values are specified in the hours:minutes:seconds format.

Last, the textEncoding attribute enables you to configure the character encoding (for example, UTF8 or UTF16) to be used for sending messages. You need to ensure that the service you are communicating with supports the character encoding you choose.

Configuring the Security Mode

When using a standard binding in Silverlight 4 such as the BasicHttpBinding, the <security> element inside the <binding> of <basicHttpBinding> (Silverlight) element specifies the security mode to be configured within the <basicHttpBinding> (Silverlight) element. In Silverlight 4, the security mode for this standard binding must be configured as follows:

  • For HTTP addresses: <security mode="None" /> or <security mode="TransportCredentialOnly" />.

  • For HTTPS addresses: <security mode="Transport" /> or <security mode=" TransportWithMessageCredential" />.

For information about the use of these security modes, see BasicHttpSecurityMode and <security>.

When using a CustomBinding, transport-level security is controlled by switching between <httpTransport> (Silverlight) and <httpsTransport /> transport binding elements inside the <binding> of <customBinding> (Silverlight) element.

See Also