XML Web service Type Marshaling
This section illustrates that various data types can be passed to and returned from Web Service methods. Because the XML Web services implementation is built on top of the XML Serialization architecture, it supports a significant number of data types. The following table lists the supported data types for Web Service methods when using the SOAP protocol (for example, using the proxy generated by the Web Services Description Language tool, WSDL.exe).
| Type | Description |
|---|---|
| Primitive Types | Standard primitive types. The complete list of supported primitives are String, Char, Byte, Boolean, Int16, Int32, Int64, UInt16, UInt32, UInt64, Single, Double, Guid, Decimal, DateTime (as XML's timeInstant), DateTime (as XML's date), DateTime (as XML's time), and XmlQualifiedName (as XML's QName). |
| Enum Types | Enumeration types, for example, "public enum color { red=1, blue=2 }" |
| Arrays of Primitives, Enums | Arrays of the above primitives, such as string[] and int[] |
| Classes and Structs | Class and struct types with public fields or properties. The public properties and fields are serialized. |
| Arrays of Classes (Structs) | Arrays of the above. |
| DataSet | ADO.NET DataSet Types (see the next section for an example). DataSets can also appear as fields in structs or classes.
Note: Microsoft Visual Studio .NET and the XSD.EXE SDK utility have support for "strong-typing" a DataSet. These tools generate a class that inherits from DataSet to produce DataSet1, adding several methods/properties/etc that are specific to a particular XML schema. If you pass DataSet, XML Web services always transmits the schema along with the data (so it knows what tables and columns you are passing), and their types (for example, int, string). If you pass a subclass of DataSet (for example, DataSet1), XML Web services assumes you are adding tables/columns in the constructor, and assumes that those tables/columns represent your schema. |
| Arrays of DataSet | Arrays of the above. |
| XmlNode | XmlNode is an in-memory representation of an XML fragment (like a lightweight XML document object model). For example, "<comment>This is<b>pretty</b> neat</comment>" could be stored in an XmlNode. You can pass XmlNodes as parameters, and they are added to the rest of the XML being passed to the XML Web service (the other parameters) in a SOAP-compliant manner. The same is true for return values. This allows you to pass or return XML whose structure changes from call to call, or where you may not know all the types being passed. XmlNode can also appear as fields in structs or classes. |
| Arrays of XmlNode | Arrays of above. |
Whether calling a XML Web service using SOAP or HTTP GET/POST, all the above types are supported for return values.
Parameters:
Both by-value and by-reference (in/out) parameters are supported when using the SOAP protocol. By-reference parameters can send the value both ways: up to the server, and back to the client. When passing input parameters to a XML Web service using HTTP GET/POST, only a limited set of data types are supported, and they must be by-value parameters. The supported types for HTTP GET/POST parameters are listed below:
| Type | Description |
|---|---|
| Primitive Types (limited) | Most standard primitive types. The complete list of supported primitives are Int32, String, Int16, Int64, Boolean, Single, Double, Decimal, DateTime, UInt16, UInt32, UInt64, and Currency. From the client's perspective, all these types turn into string. |
| Enum Types | Enumeration types, for example, "public enum color { red=1, blue=2 }". From the client's perspective, enums become classes with a static const string for each value. |
| Arrays of Primitives, Enums | Arrays of the above primitives, such as string[] and int[] |
The following example demonstrates the use of the types listed above, using a SOAP proxy generated from WSDL.exe. Note that because there is more than one public class defined in the .asmx file, you must specify which is to be treated as the WebService class using the "Class" attribute of the WebService directive:
<%@ WebService Language="C#" Class="DataTypes" %>
|
|
- The SayHello method shows returning a String from a service.
- The SayHelloName method returns a String, and also takes a String as a parameter.
- The GetIntArray method shows how to return an array of integers.
- The GetMode method returns an enum value.
- The GetOrder method returns a class (which is almost the same as a struct here).
- The GetOrders method returns an array of Order objects.
Using the WSDL.exe command line proxy generation tool, the marshaling of these data types is transparent to the consuming client application. A sample client application for the above XML Web service follows:
VB DataTypesClient.aspx
[Run Sample] |
[View Source]