System.Runtime.Serialization.Formatters.Soap.SoapFormatter Class

Summary

Serializes and deserializes an object, or an entire graph of connected objects, in SOAP format.

C# Syntax:

public sealed class SoapFormatter : IRemotingFormatter, IFormatter

The SoapFormatter and BinaryFormatter classes implement the IRemotingFormatter interface to support remote procedure calls (RPCs), and the IFormatter interface (inherited by the IRemotingFormatter) to support serialization of a graph of objects. The SoapFormatter class also supports RPCs with ISoapMessage objects, without using the IRemotingFormatter functionality.

During RPCs, the IRemotingFormatter interface allows the specification of two separate object graphs: the graph of objects to serialize, and an additional graph containing an array of header objects that convey information about the remote function call (for example, transaction ID or a method signature). For proper serialization, the root object of the first graph must be an object that implements either the IMethodCallMessage interface or the IMethodReturnMessage interface.

During deserialization of an RPC, a HeaderHandler delegate is specified to the BinaryFormatter.Deserialize method of the formatter. The remoting infrastructure uses the HeaderHandler delegate to produce an object that supports the ISerializable interface. This object contains the information stored in the headers, and becomes the root of the graph returned by the deserializer.

The SoapFormatter can also handle RPCs that are produced with objects implementing the ISoapMessage interface. To create an RPC without using the IRemotingFormatter functionality, place an object that supports the ISoapMessage interface at the root of a graph being serialized. To deserialize an RPC created in this manner the SoapFormatter.TopObject property must be set to another object that supports the ISoapMessage interface, and contains the relevant remote call information.

System.Runtime.Serialization.Formatters.Soap Namespace

System.Runtime.Serialization.Formatters.Soap.SoapFormatter Member List:

Public Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the SoapFormatter class with default property values.
ctor #2	Overloaded: .ctor(ISurrogateSelector selector, StreamingContext context) Initializes a new instance of the SoapFormatter class with the specified ISurrogateSelector and StreamingContext.

Public Properties

AssemblyFormat	Read-write Gets or sets the format in which assembly names are serialized.
Binder	Read-write Gets or sets the SerializationBinder that controls the binding of a serialized object to a type.
Context	Read-write Gets or sets the StreamingContext used with this SoapFormatter.
SurrogateSelector	Read-write Gets or sets the SurrogateSelector that controls type substitution during serialization and deserialization.
TopObject	Read-write Gets or sets the ISoapMessage into which the SOAP top object is deserialized.
TypeFormat	Read-write Gets or sets the format in which type descriptions are laid out in the serialized stream.

Public Methods

Deserialize	Overloaded: Deserialize(Stream serializationStream) Deserializes the data on the provided stream and reconstitutes the graph of objects.
Deserialize	Overloaded: Deserialize(Stream serializationStream, HeaderHandler handler) Deserializes the stream into an object graph, with any headers in that stream being handled by the given HeaderHandler.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Serialize	Overloaded: Serialize(Stream serializationStream, object graph) Serializes an object, or graph of objects with the specified root to the given Stream.
Serialize	Overloaded: Serialize(Stream serializationStream, object graph, Header[] headers) Serializes an object, or graph of objects with the specified root to the given Stream in the SOAP RPC (Remote Procedure Call) format.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Runtime.Serialization.Formatters.Soap.SoapFormatter

System.Runtime.Serialization.Formatters.Soap.SoapFormatter Member Details

Summary

Initializes a new instance of the SoapFormatter class with default property values.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public SoapFormatter();

The following table shows the initial property values for an instance of SoapFormatter.

Property	Value
SoapFormatter.SurrogateSelector	null .
SoapFormatter.Context	A new StreamingContext initialized to specify that the serialized data can be transmitted to or received from any of the other contexts.

Return to top

Summary

Initializes a new instance of the SoapFormatter class with the specified ISurrogateSelector and StreamingContext.

C# Syntax:

public SoapFormatter(    ISurrogateSelector selector,    StreamingContext context );

selector

The ISurrogateSelector to use with the new instance of SoapFormatter. Can be null.

context

The StreamingContext that holds the source and destination of the serialization. If the context parameter is null, then the SoapFormatter.Context defaults to StreamingContextStates.CrossMachine.

Objects are serialized to, or deserialized from, the specified Stream.

The serialization or deserialization process uses the specified ISurrogateSelector to search for surrogates that are registered for the object types you want to deserialize. Surrogates are helpers that serialize and deserialize objects of specific classes. The default ISurrogateSelector cannot handle the serialization of objects that derive from the MarshalByRefObject for remoting purposes. In a remoting situation the specified ISurrogateSelector replaces the object derived from MarshalByRefObject with an ObjRef object that is serialized by the specified surrogate selector. Therefore, if you want to use remote objects, set the selector parameter to an instance of RemotingSurrogateSelector. If you do not need surrogates, set the selector parameter to be null.

Return to top

Summary

Gets or sets the format in which assembly names are serialized.

C# Syntax:

public FormatterAssemblyStyle AssemblyFormat {get; set;}

Return to top

Summary

Gets or sets the SerializationBinder that controls the binding of a serialized object to a type.

C# Syntax:

public SerializationBinder Binder {get; set;}

Implements:

IFormatter.Binder

Return to top

Summary

Gets or sets the StreamingContext used with this SoapFormatter.

C# Syntax:

public StreamingContext Context {get; set;}

Implements:

IFormatter.Context

The StreamingContext provides an enumeration that describes the source and the destination for a given serialized stream, as well as a way for serialization to retain that context and an additional caller-defined context.

Return to top

Summary

Gets or sets the SurrogateSelector that controls type substitution during serialization and deserialization.

C# Syntax:

public ISurrogateSelector SurrogateSelector {get; set;}

Implements:

IFormatter.SurrogateSelector

Used by System.Runtime.Remoting to generate ObjRef instances for MarshalByRefObject objects.

Return to top

Summary

Gets or sets the ISoapMessage into which the SOAP top object is deserialized.

C# Syntax:

public ISoapMessage TopObject {get; set;}

This property is used for SOAP remote procedure call (RPC) format, and specifies that the SOAP top record is a method called remotely, and not a common language runtime object type.

Return to top

Summary

Gets or sets the format in which type descriptions are laid out in the serialized stream.

C# Syntax:

public FormatterTypeStyle TypeFormat {get; set;}

Return to top

Summary

Deserializes the data on the provided stream and reconstitutes the graph of objects.

C# Syntax:

public object Deserialize(    Stream serializationStream );

serializationStream

The stream containing the data to deserialize.

Return Value:

The top object of the deserialized graph (root).

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.

Implements:

IFormatter.Deserialize

Note For successful deserialization, the current position in the stream must be at the beginning of the object graph.

Return to top

Summary

Deserializes the stream into an object graph, with any headers in that stream being handled by the given HeaderHandler.

C# Syntax:

public object Deserialize(    Stream serializationStream,    HeaderHandler handler );

serializationStream

The stream containing the data to deserialize.

handler

Delegate to handle any headers found on the stream. Can be null.

Return Value:

The top object of the deserialized graph (root).

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.
SerializationException	serializationStream supports seeking, and its length is 0.

Implements:

IRemotingFormatter.Deserialize

Headers are used only for specific remoting applications. The HeaderHandler parameter is one of two ways to return headers from a stream in SOAP RPC (Remote Procedure Call) format. The other way is to use the SoapFormatter.TopObject property.

Note In order for deserialization to succeed the current position in the stream must be at the beginning of the object graph.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~SoapFormatter();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Serializes an object, or graph of objects with the specified root to the given Stream.

C# Syntax:

public void Serialize(    Stream serializationStream,    object graph );

serializationStream

The stream onto which the formatter puts the data to serialize.

graph

The object, or root of the object graph, to serialize. All child objects of this root object are automatically serialized.

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.

Implements:

IFormatter.Serialize

Return to top

Summary

Serializes an object, or graph of objects with the specified root to the given Stream in the SOAP RPC (Remote Procedure Call) format.

C# Syntax:

public void Serialize(    Stream serializationStream,    object graph,    Header[] headers );

serializationStream

The stream onto which the formatter puts the data to serialize.

graph

The object, or root of the object graph, to serialize. All child objects of this root object are automatically serialized.

headers

Remoting headers to include in the serialization. Can be null.

Exceptions

Exception Type	Condition
ArgumentNullException	serializationStream is null.

Implements:

IRemotingFormatter.Serialize

Note Headers are used only for specific remoting applications.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page