WebServicesClientProtocol Class
Specifies the class client proxies derive from when using the Web Services Enhancements (WSE). Defines the class that client proxies derive from when using the Web Services Enhancements (WSE).
Namespace: Microsoft.Web.Services2
Assembly: Microsoft.Web.Services2 (in microsoft.web.services2.dll)
Usage
'Usage
Dim webServicesClientProtocol1 As New WebServicesClientProtocol()
Syntax
'Declaration
Public Class WebServicesClientProtocol
Inherits SoapHttpClientProtocol
public class WebServicesClientProtocol : SoapHttpClientProtocol
public ref class WebServicesClientProtocol : public SoapHttpClientProtocol
public class WebServicesClientProtocol extends SoapHttpClientProtocol
public class WebServicesClientProtocol extends SoapHttpClientProtocol
Example
The following code example communicates with a Web service using a SOAP message digitally signed with an X.509 certificate.
private void buttonAdd_Click(object sender, System.EventArgs e)
{
int a =3, b=3;
// Get the X509 certificate.
X509SecurityToken token = GetSecurityToken();
// Verify an X509 certificate was returned.
if (token == null)
return;
// Call the method that communicates with the XML Web service.
try
{
// Create a new instance of the proxy class.
AddNumbers serviceProxy = new AddNumbers();
// Get the SoapContext for the SOAP request.
SoapContext requestContext = serviceProxy.RequestSoapContext;
// Expire this message one minute after it is sent.
requestContext.Security.Timestamp.TtlInSeconds = 60;
// Create an WS-Security SOAP header.
Security security = new Security();
// Add the X509 certificate to the WS-Security header.
security.Tokens.Add(token);
// Sign the message using the X509 certificate.
security.Elements.Add(new Signature(token));
// Add the WS-Security header to the SOAP message.
requestContext.Security.Add(security);
// Call the method that communicates with the XML Web service.
int sum = serviceProxy.AddInt(a, b);
// If we got here, the message was successfully processed.
string message = string.Format("{0} + {1} = {2}", a, b, sum);
// Display a MessageBox containing the results from the XML Web service.
MessageBox.Show(message, "Success!", MessageBoxButtons.OK, MessageBoxIcon.Information);
}
catch (System.Web.Services.Protocols.SoapException se)
{
Error("SOAP Exception caught while invoking an XML Web service.", se);
}
catch (Exception ex)
{
Error("Exception caught while invoking an XML Web service.", ex);
return;
}
}
// Gets the security token for signing messages.
public X509SecurityToken GetSecurityToken()
{
if (securityToken == null)
{
X509CertificateStore store = X509CertificateStore.LocalMachineStore(X509CertificateStore.MyStore);
bool open = store.OpenRead();
try
{
// Display dialog for user to select the certificate from the local machine's certificate store.
X509Certificate cert = store.SelectCertificate(this.Handle, "Select Certificate", "Choose a Certificate below for signing.");
// Verify user chose a certificate.
if (cert == null)
{
Error("You chose not to select an X509 certificate for signing your messages.");
securityToken = null;
}
// Verify user has the private key and the certifcate supports digital signatures.
else if (!cert.SupportsDigitalSignature || (cert.GetPrivateKeyFile() != null)
{
Error("The certificate must support digital signatures and have a private key available.");
securityToken = null;
}
else
{
securityToken = new X509SecurityToken(cert);
}
}
finally
{
// Close the certificate store.
if (store != null) { store.Close(); }
}
}
return securityToken;
}
// Displays a MessageBox to the user containing the cause of an exception.
private void Error(string s)
{
Error(s, null);
}
// Displays a MessageBox to the user containing the cause of an exception.
private void Error(string s, Exception e)
{
StringBuilder sb = new StringBuilder();
sb.Append(s);
if (e != null)
{
sb.Append("\r\n");
sb.Append(e.Message);
sb.Append("\r\n");
sb.Append(e.StackTrace);
}
if (e is System.Web.Services.Protocols.SoapException)
{
System.Web.Services.Protocols.SoapException se = e as System.Web.Services.Protocols.SoapException;
sb.Append("\r\n");
sb.Append("SOAP-Fault code: " + se.Code.ToString());
}
MessageBox.Show(sb.ToString(), "Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
}
The following code example communicates with an XML Web service using a SOAP message digitally signed with an X.509 certificate.
private void buttonAdd_Click(object sender, System.EventArgs e)
{
int a =3, b=3;
// Gets the X.509 certificate.
X509SecurityToken token = GetSecurityToken();
// Verifies that an X.509 certificate was returned.
if (token == null)
return;
// Calls the method that communicates with the XML Web service.
try
{
// Create a new instance of the proxy class.
AddNumbers serviceProxy = new AddNumbers();
// Gets the SoapContext for the SOAP request.
SoapContext requestContext = serviceProxy.RequestSoapContext;
// Sets this message to expire one minute after it is sent.
requestContext.Security.Timestamp.Ttl = 60000;
// Adds the X.509 certificate to the WS-Security header.
requestContext.Security.Tokens.Add(token);
// Signs the message using the X.509 certificate.
requestContext.Security.Elements.Add(new Signature(token));
// Calls the method that communicates with the XML Web service.
int sum = serviceProxy.AddInt(a, b);
// If we get here, the message was successfully processed.
string message = string.Format("{0} + {1} = {2}", a, b, sum);
// Displays a MessageBox containing the results from the XML Web service.
MessageBox.Show(message, "Success!", MessageBoxButtons.OK, MessageBoxIcon.Information);
}
catch (System.Web.Services.Protocols.SoapException se)
{
Error("SOAP exception caught while invoking a Web service.", se);
}
catch (Exception ex)
{
Error("Exception caught while invoking a Web service.", ex);
return;
}
}
public X509SecurityToken GetSecurityToken()
{
X509SecurityToken securityToken = null;
X509CertificateStore store =
X509CertificateStore.CurrentUserStore(
X509CertificateStore.MyStore);
bool open = store.OpenRead();
try
{
byte[] certHash = {0x98, 0xec, 0x08, 0x4b, 0xa5, 0x7a,
0x6c, 0x2f, 0x39, 0x26, 0xb3, 0x0a,
0x58, 0xbf, 0x65, 0x25, 0x61, 0xc5,
0x64, 0x59};
X509CertificateCollection certs =
store.FindCertificateByHash(certHash);
Microsoft.Web.Services2.Security.X509.X509Certificate cert =
((Microsoft.Web.Services2.Security.X509.X509Certificate) certs[0]);
if (cert == null)
{
MessageBox.Show(
"You chose not to select an X.509 " +
"certificate for signing your messages.");
securityToken = null;
}
else if (!cert.SupportsDigitalSignature ||
(cert.Key == null))
{
MessageBox.Show(
"The certificate must support digital " +
"signatures and have a private key available.");
securityToken = null;
}
else
{
securityToken = new X509SecurityToken(cert);
}
}
finally
{
if (store != null)
store.Close();
}
return securityToken;
}
Remarks
When you build an XML Web service client, whether you use Visual Studio .NET or not, a proxy class is generated to communicate with the XML Web service. When you are using Visual Studio .NET, that proxy class is generated when a Web Reference is made or updated. If the .NET Framework SDK is used without Visual Studio .NET the proxy class is generated using the Web Services Description Language (Wsdl.exe) tool. Either way, the proxy class derives from System.Web.Services.Protocols.SoapHttpClientProtocol by default. To use the functionality of the WSE, change that to WebServicesClientProtocol.
This class provides access to the SoapContext for both SOAP requests and SOAP responses for XML Web service clients with the RequestSoapContext and ResponseSoapContext properties respectively. This SoapContext provides access to the contents of SOAP headers defined in the WS-Security, WS-Routing, and WS-Timestamp specifications.
Whenever the constructor is called or the Url property is set, there is a referral cache look-up to see if the specified URL contains a referral in the referral cache.
If an instance of the WebServicesClientProtocol is cast or converted to System.Web.Services.Protocols.SoapHttpClientProtocol, then the values of all properties of this class that are not members of the System.Web.Services.Protocols.SoapHttpClientProtocol are lost. This includes the RequestSoapContext and ResponseSoapContext properties.
Remarks
When you build an XML Web service client, whether you use Visual Studio .NET or not, a proxy class is generated to communicate with the XML Web service. When you are using Visual Studio .NET, that proxy class is generated when a Web Reference is made or updated. If the .NET Framework SDK is used without Visual Studio .NET, the proxy class is generated using the Web Services Description Language (Wsdl.exe) tool. Either way, the proxy class derives from System.Web.Services.Protocols.SoapHttpClientProtocol by default. To use the functionality of the WSE, change the base class to WebServicesClientProtocol.
This class provides access to the SoapContext for both SOAP requests and SOAP responses for XML Web service clients with the RequestSoapContextand ResponseSoapContext properties respectively. The SoapContext provides access to the contents of SOAP headers defined in the WS-Security and WS-Routing specifications.
Whenever the constructor is called or the Url property is set, there is a referral cache lookup to see if the specified URL contains a referral in the referral cache.
If an instance of the WebServicesClientProtocol is cast or converted to System.Web.Services.Protocols.SoapHttpClientProtocol, then the values of all properties of this class that are not members of the System.Web.Services.Protocols.SoapHttpClientProtocol are lost. This includes the RequestSoapContext and ResponseSoapContext properties.
Inheritance Hierarchy
System.Object
System.MarshalByRefObject
System.ComponentModel.Component
System.Web.Services.Protocols.WebClientProtocol
System.Web.Services.Protocols.HttpWebClientProtocol
System.Web.Services.Protocols.SoapHttpClientProtocol
Microsoft.Web.Services2.WebServicesClientProtocol
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Platforms
Development Platforms
Windows XP Home Edition, Windows XP Professional, Windows Server 2003, Windows Longhorn, and Windows 2000
Target Platforms
Windows 2000, Windows 2000 Server, Windows 2000 Advanced Server, Windows XP Home Edition, Windows XP Professional, Windows Server 2003, Windows Longhorn, Pocket PC, Windows CE, Smart Phone
See Also
Reference
Microsoft.Web.Services2 Namespace
SoapContext
SoapContext