WebClientProtocol Class (System.Web.Services.Protocols)

Switch View :
Classic
Lightweight
ScriptFree
.NET Framework Class Library
WebClientProtocol Class

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

Specifies the base class for all XML Web service client proxies created using ASP.NET.

Inheritance Hierarchy
System.Object
  System.MarshalByRefObject
    System.ComponentModel.Component
      System.Web.Services.Protocols.WebClientProtocol
        System.Web.Services.Protocols.HttpWebClientProtocol

Namespace:  System.Web.Services.Protocols
Assembly:  System.Web.Services (in System.Web.Services.dll)
Syntax
Visual Basic

<ComVisibleAttribute(True)> _
Public MustInherit Class WebClientProtocol _
	Inherits Component
C#

[ComVisibleAttribute(true)]
public abstract class WebClientProtocol : Component
Visual C++

[ComVisibleAttribute(true)]
public ref class WebClientProtocol abstract : public Component
F#

[<AbstractClass>]
[<ComVisibleAttribute(true)>]
type WebClientProtocol =  
    class
        inherit Component
    end

The WebClientProtocol type exposes the following members.

Constructors
  Name Description
Protected method WebClientProtocol Initializes a new instance of the WebClientProtocol class.
Top
Properties
  Name Description
Protected property CanRaiseEvents Gets a value indicating whether the component can raise an event. (Inherited from Component.)
Public property ConnectionGroupName Gets or sets the name of the connection group for the request.
Public property Container Gets the IContainer that contains the Component. (Inherited from Component.)
Public property Credentials Gets or sets security credentials for XML Web service client authentication.
Protected property DesignMode Gets a value that indicates whether the Component is currently in design mode. (Inherited from Component.)
Protected property Events Gets the list of event handlers that are attached to this Component. (Inherited from Component.)
Public property PreAuthenticate Gets or sets whether pre-authentication is enabled.
Public property RequestEncoding The Encoding used to make the client request to the XML Web service.
Public property Site Gets or sets the ISite of the Component. (Inherited from Component.)
Public property Timeout Indicates the time an XML Web service client waits for the reply to a synchronous XML Web service request to arrive (in milliseconds).
Public property Url Gets or sets the base URL of the XML Web service the client is requesting.
Public property UseDefaultCredentials Gets or sets a value that indicates whether to set the Credentials property to the value of the CredentialCache.DefaultCredentials property.
Top
Methods
  Name Description
Public method Abort Cancels a request to an XML Web service method.
Protected method Static member AddToCache Add an instance of the client protocol handler to the cache.
Public method CreateObjRef Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
Public method Dispose() Releases all resources used by the Component. (Inherited from Component.)
Protected method Dispose(Boolean) Releases the unmanaged resources used by the Component and optionally releases the managed resources. (Inherited from Component.)
Public method Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected method Finalize Releases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection. (Inherited from Component.)
Protected method Static member GetFromCache Gets an instance of a client protocol handler from the cache.
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method GetLifetimeService Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected method GetService Returns an object that represents a service provided by the Component or by its Container. (Inherited from Component.)
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Protected method GetWebRequest Creates a WebRequest instance for the specified uri. This protected method is called by the XML Web service client infrastructure to get a new WebRequest transport object to transmit the XML Web service request.
Protected method GetWebResponse(WebRequest) Returns a response from a synchronous request to an XML Web service method.
Protected method GetWebResponse(WebRequest, IAsyncResult) Returns a response from an asynchronous request to an XML Web service method. This protected method is called by the XML Web service client infrastructure to get the response from an asynchronous XML Web service request.
Public method InitializeLifetimeService Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected method MemberwiseClone() Creates a shallow copy of the current Object. (Inherited from Object.)
Protected method MemberwiseClone(Boolean) Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
Public method ToString Returns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component.)
Top
Events
  Name Description
Public event Disposed Occurs when the component is disposed by a call to the Dispose method. (Inherited from Component.)
Top
Remarks

The properties of the WebClientProtocol class are used to control the behavior of the transport used to transmit the XML Web service request and response. The properties on this class map to properties found on WebRequest. Instances of classes deriving from WebRequest, such as HttpWebRequest, are used as the transport mechanism for XML Web services created using ASP.NET.

To communicate with an XML Web service, you must create a proxy class deriving indirectly or directly from WebClientProtocol for the XML Web service you want to call. Instead of creating the proxy class manually, you can use the Wsdl.exe tool to create a proxy class for a given XML Web service's service description. Since WebClientProtocol is the base class for your client proxy, you will find its properties on your proxy classes. These properties are useful for controlling the request behavior of the underlying transport. For instance, use the Credentials property for calling authenticated XML Web services. Many of the WebClientProtocol properties are used to initialize the WebRequest object that is used to make the Web request.

Examples

The following example is an ASP.NET Web Form, which calls an XML Web service named Math. Within the EnterBtn_Click function, the Web Form sets proxy information and client credentials on the proxy class prior to calling the remote XML Web service method.

Security note Security Note

This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.
Visual Basic

<%@ Page Language="VB" %>
<%@ Import Namespace="System.Net" %>
<html>
    <script language="VB" runat="server">

        Sub EnterBtn_Click(src As Object, e As EventArgs)
            Dim math As New MyMath.Math()

            ' Set the client-side credentials using the Credentials property.
            Dim credentials As New NetworkCredential("Joe", "password", "mydomain")
            math.Credentials = credentials

            ' Do not allow the server to redirect the request.
            math.AllowAutoRedirect = False

            Dim iTotal As Integer = math.Add(Convert.ToInt32(Num1.Text), Convert.ToInt32(Num2.Text))
            Total.Text = "Total: " & iTotal.ToString()
        End Sub

    </script>

    <body>
       <form action="MathClient.aspx" runat=server>

          Enter the two numbers you want to add and then press the Total button.
          <p>
          Number 1: <asp:textbox id="Num1" runat=server/>  +
          Number 2: <asp:textbox id="Num2" runat=server/> =
          <asp:button text="Total" Onclick="EnterBtn_Click" runat=server/>
          <p>
          <asp:label id="Total"  runat=server/>

       </form>
    </body>
 </html>
C#

<%@ Page Language="C#" %>
<%@ Import Namespace="System.Net" %>
<html>
    <script language="C#" runat="server">
       void EnterBtn_Click(Object Src, EventArgs E) 
          {
             MyMath.Math math = new MyMath.Math();

             // Set the client-side credentials using the Credentials property.
             ICredentials credentials = new NetworkCredential("Joe","mydomain","password");
             math.Credentials = credentials;

             // Do not allow the server to redirect the request.
             math.AllowAutoRedirect = false;

             int total = math.Add(Convert.ToInt32(Num1.Text), Convert.ToInt32(Num2.Text));
             Total.Text = "Total: " + total.ToString();
         }

    </script>

    <body>
       <form action="MathClient.aspx" runat=server>

          Enter the two numbers you want to add and then press the Total button.
          <p>
          Number 1: <asp:textbox id="Num1" runat=server/>  +
          Number 2: <asp:textbox id="Num2" runat=server/> =
          <asp:button text="Total" Onclick="EnterBtn_Click" runat=server/>
          <p>
          <asp:label id="Total"  runat=server/>

       </form>
    </body>
 </html>
Version Information

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1
Platforms

Windows 8 Release Preview, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 SP2, Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Thread Safety

The properties on this class are copied into a new instance of a WebRequest object for each XML Web service method call. While you can call XML Web service methods on the same WebClientProtocol instance from different threads at the same time, there is no synchronization done to ensure that a consistent snapshot of the properties will get transferred to the WebRequest object. Therefore if you need to modify the properties and make concurrent method calls from different threads you should use a different instance of the XML Web service proxy or provide your own synchronization.

See Also

Reference

System.Web.Services.Protocols Namespace
SoapHttpClientProtocol
HttpWebRequest

Other Resources

Script Exploits Overview