1 Notes on the Soap Client
2 ------------------------
4 * Preparing an invocation.
6 To send a SOAP request to a remote server, applications will
7 instantiate a class created by the WSDL compiler that derives
8 from SoapHttpClientProtocol.
10 The classes generated are fairly simple, they contain stubs
11 for all of the methods generated just pass the name of the
12 method and the arguments they receive to the protected
13 Invoke() method on SoapHttpClientProtocol.
15 To invoke a method on a SOAP server it is necessary to
16 instantiate the generated class, and possibly configure the
17 Url property of it (to point to the right server) and then
20 SoapHttpClientProtocol will create a SoapClientMessage based
21 on this information. The SoapClientMessage class is used to
22 pass the information to hooks or extensions in the .NET
23 Framework. These hooks are invoked at various phases to
24 customize the SOAP message.
26 For the first pass of our implementation, we will not invoke
27 any of those hooks. They are required for things like WSS,
28 but we do not need this now.
30 A WebRequest object of type POST is created, and we will use
31 this to send our Soap message.
33 * Creating the SOAP request
35 The SOAP request is fairly simple; For our initial
36 implementation we will only support the schema encoding.
38 For each stub method, we need to create an XmlSerializer for
39 the parameter values, and another one for the return value.
41 The encoding is fairly simple, see the post on
42 mono-serialization-list for a sample program.
44 * Processing the return value.
50 Methods.cs extracts class and method information: it basically
51 pulls all the attributes that can be applied to the class and
52 methods, and stores them into TypeStubInfo and MethodStubInfo.
54 Also, serializers for input and output types are created and
55 stored into the MethodStubInfo.
57 There is a cache managed by TypeStubManager (it has to be
58 threadsafe, as SoapHttpClientProtocol will call this and will
59 require thread safe semantics).
61 The cache tracks types, and types track their methods. This
62 information needs to be computed ahead of time, due to the
63 possible name-clash resolution that VisualStudio uses.
65 * Current shortcomings and problems.
67 * Need a cache that maps (type, method-name) to the
68 precomputed MethodMetadata. The type has to be a derived
69 class from SoapHttpClientProtocol.
71 * We do not support SoapExtensions.
73 * We do not support extracting the parameter information and
74 pass the result attribute names to the XmlSerializer, as specified in
75 `Customizing SOAP Messages/Customizing the SOAP Message with XML Serialization'
77 * We do not pass the SoapClientMessage as we should to any
80 * Ignored elements in the MethodStubInfo:
81 * ParameterStyle, have to understand what this does.
87 VisualStudio does not allow method overloaded in web
88 services, it requires that:
90 [WebMethod (MethodName="AlternateName")]
95 [WebMethod] public string A () {}
96 [WebMethod] public string A (int b) {}
100 [WebMethod] public string A () {}
101 [WebMethod (MethodName="B")] public string A (int b) {}
103 The generated stubs though for "Invoke" does not use the
104 actual name of the web method in the call to "Invoke", it
105 uses a sequential number:
107 [System.Web.Services.WebMethodAttribute(MessageName="A1")]
108 [System.Web.Services.Protocols.SoapDocumentMethodAttribute("http://tempuri.org/B", RequestElementName="B", RequestNamespace="http://tempuri.org/", ResponseElementName="BResponse", ResponseNamespace="http://tempuri.org/", Use=System.Web.Services.Description.SoapBindingUse.Literal, ParameterStyle=System.Web.Services.Protocols.SoapParameterStyle.Wrapped)]
109 [return: System.Xml.Serialization.XmlElementAttribute("BResult")]
110 public string A(int a) {
111 object[] results = this.Invoke("A1", new object[] {
113 return ((string)(results[0]));
117 public System.IAsyncResult BeginA1(int a, System.AsyncCallback callback, object asyncState) {
118 return this.BeginInvoke("A1", new object[] {
119 a}, callback, asyncState);
123 public string EndA1(System.IAsyncResult asyncResult) {
124 object[] results = this.EndInvoke(asyncResult);
125 return ((string)(results[0]));
129 The above is interesting, because it means that the method to
130 invoke on the target should be pulled from
131 `RequestElementName', if the value is not found, then we use
132 the name of the method provided.