Export (0) Print
Expand All

MessageEncodingBindingElement Class

The binding element that specifies the message version used to encode messages.

Namespace:  System.ServiceModel.Channels
Assembly:  System.ServiceModel (in System.ServiceModel.dll)

public abstract class MessageEncodingBindingElement : BindingElement

The MessageEncodingBindingElement type exposes the following members.

  NameDescription
Protected methodSupported by Portable Class LibraryMessageEncodingBindingElement()Initializes a new instance of the MessageEncodingBindingElement class.
Protected methodSupported by Portable Class LibraryMessageEncodingBindingElement(MessageEncodingBindingElement)Initializes a new instance of the MessageEncodingBindingElement class initialized from an existing element.
Top

  NameDescription
Public propertySupported by Portable Class LibraryMessageVersionWhen overridden in a derived class, gets or sets the message version that can be handled by the message encoders produced by the message encoder factory.
Top

  NameDescription
Public methodSupported by Portable Class LibraryBuildChannelFactory<TChannel>Initializes a channel factory for producing channels of a specified type from the binding context. (Inherited from BindingElement.)
Public methodBuildChannelListener<TChannel>Initializes a channel listener to accept channels of a specified type from the binding context. (Inherited from BindingElement.)
Public methodSupported by Portable Class LibraryCanBuildChannelFactory<TChannel>Returns a value that indicates whether the binding element can build a channel factory for a specific type of channel. (Inherited from BindingElement.)
Public methodCanBuildChannelListener<TChannel>Returns a value that indicates whether the binding element can build a listener for a specific type of channel. (Inherited from BindingElement.)
Public methodSupported by Portable Class LibraryCloneWhen overridden in a derived class, returns a copy of the binding element object. (Inherited from BindingElement.)
Public methodSupported by Portable Class LibraryCreateMessageEncoderFactoryWhen overridden in a derived class, creates a factory for producing message encoders.
Public methodSupported by Portable Class LibraryEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodSupported by Portable Class LibraryFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by Portable Class LibraryGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodSupported by Portable Class LibraryGetProperty<T>Returns the typed object requested, if present, from the appropriate layer in the channel stack. (Overrides BindingElement.GetProperty<T>(BindingContext).)
Public methodSupported by Portable Class LibraryGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by Portable Class LibraryMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by Portable Class LibraryToStringReturns a string that represents the current object. (Inherited from Object.)
Top

Encoding is the process of transforming a message into a sequence of bytes. Decoding is the reverse process. includes three types of encoding for SOAP messages: Text, Binary and Message Transmission Optimization Mechanism (MTOM).

Use this class if you want to implement a custom message encoder. To implement your own custom message encoder, you must provide custom implementations of the following three abstract base classes:

Override the Encoder to return an instance of your custom MessageEncoder. Override the CreateMessageEncoderFactory method to return an instance of this factory.

Any type that derives from MessageEncodingBindingElement is responsible for updating the version of the SOAP binding in the WSDL document generated for the service. This is done by implementing the ExportEndpoint(WsdlExporter, WsdlEndpointConversionContext) method to modify the generated WSDL.

provides three types of binding elements derived from the MessageEncodingBindingElement class that can provide for text, binary and Message Transmission Optimization Mechanism (MTOM) encoding.

  • TextMessageEncodingBindingElement: the most interoperable, but the least efficient encoder for XML messages. A Web service or Web service client can generally understand textual XML. However, transmitting large blocks of binary data as text is not efficient.

  • BinaryMessageEncodingBindingElement: represents the binding element that specifies the character encoding and message versioning used for binary-based XML messages. This is most efficient but least interoperable of the encoding options.

  • MTOMMessageEncodingBindingElement: represents the binding element that specifies the character encoding and message versioning used for a message using a Message Transmission Optimization Mechanism (MTOM) encoding. MTOM is an efficient technology for transmitting binary data in messages. The MTOM encoder attempts to balance efficiency and interoperability. The MTOM encoding transmits most XML in textual form, but optimizes large blocks of binary data by transmitting them as-is, without conversion to text.

The following code example shows how to implement a class derived from MessageEncodingBindingElement:


public class CustomTextMessageBindingElement : MessageEncodingBindingElement, IWsdlExportExtension
{
    private MessageVersion msgVersion;
    private string mediaType;
    private string encoding;
    private XmlDictionaryReaderQuotas readerQuotas;

    CustomTextMessageBindingElement(CustomTextMessageBindingElement binding)
        : this(binding.Encoding, binding.MediaType, binding.MessageVersion)
    {
        this.readerQuotas = new XmlDictionaryReaderQuotas();
        binding.ReaderQuotas.CopyTo(this.readerQuotas);
    }

    public CustomTextMessageBindingElement(string encoding, string mediaType,
        MessageVersion msgVersion)
    {
        if (encoding == null)
        	throw new ArgumentNullException("encoding");    

        if (mediaType == null)
        	throw new ArgumentNullException("mediaType");

        if (msgVersion == null)
        	throw new ArgumentNullException("msgVersion");

        this.msgVersion = msgVersion;
        this.mediaType = mediaType;
        this.encoding = encoding;
        this.readerQuotas = new XmlDictionaryReaderQuotas();
    }

    public CustomTextMessageBindingElement(string encoding, string mediaType)
        : this(encoding, mediaType, MessageVersion.Soap11WSAddressing10)
    {
    }

    public CustomTextMessageBindingElement(string encoding)
        : this(encoding, "text/xml")
    {

    }

    public CustomTextMessageBindingElement()
        : this("UTF-8")
    {
    }

    public override MessageVersion MessageVersion
    {
        get
        {
            return this.msgVersion;
        }

        set
        {
            if (value == null)
                throw new ArgumentNullException("value");
            this.msgVersion = value;
        }
    }


    public string MediaType
    {
        get
        {
            return this.mediaType;
        }

        set
        {
            if (value == null)
                throw new ArgumentNullException("value");
            this.mediaType = value;
        }
    }

    public string Encoding
    {
        get
        {
            return this.encoding;
        }

        set
        {
            if (value == null)
                throw new ArgumentNullException("value");
            this.encoding = value;
        }
    }

    // This encoder does not enforces any quotas for the unsecure messages. The 
    // quotas are enforced for the secure portions of messages when this encoder
    // is used in a binding that is configured with security. 
    public XmlDictionaryReaderQuotas ReaderQuotas
    {
        get
        {
            return this.readerQuotas;
        }
    }

    #region IMessageEncodingBindingElement Members
    public override MessageEncoderFactory CreateMessageEncoderFactory()
    {
        return new CustomTextMessageEncoderFactory(this.MediaType,
            this.Encoding, this.MessageVersion);
    }

    #endregion


    public override BindingElement Clone()
    {
        return new CustomTextMessageBindingElement(this);
    }

    public override IChannelFactory<TChannel> BuildChannelFactory<TChannel>(BindingContext context)
    {
        if (context == null)
            throw new ArgumentNullException("context");

        context.BindingParameters.Add(this);
        return context.BuildInnerChannelFactory<TChannel>();
    }

    public override bool CanBuildChannelFactory<TChannel>(BindingContext context)
    {
        if (context == null)
            throw new ArgumentNullException("context");

        return context.CanBuildInnerChannelFactory<TChannel>();
    }

    public override IChannelListener<TChannel> BuildChannelListener<TChannel>(BindingContext context)
    {
        if (context == null)
            throw new ArgumentNullException("context");

        context.BindingParameters.Add(this);
        return context.BuildInnerChannelListener<TChannel>();
    }

    public override bool CanBuildChannelListener<TChannel>(BindingContext context)
    {
        if (context == null)
            throw new ArgumentNullException("context");

        context.BindingParameters.Add(this);
        return context.CanBuildInnerChannelListener<TChannel>();
    }

    public override T GetProperty<T>(BindingContext context)
    {
        if (typeof(T) == typeof(XmlDictionaryReaderQuotas))
        {
            return (T)(object)this.readerQuotas;
        }
        else
        {
            return base.GetProperty<T>(context);
        }
    }

    #region IWsdlExportExtension Members

    void IWsdlExportExtension.ExportContract(WsdlExporter exporter, WsdlContractConversionContext context)
    {
    }

    void IWsdlExportExtension.ExportEndpoint(WsdlExporter exporter, WsdlEndpointConversionContext context)
    {
        // The MessageEncodingBindingElement is responsible for ensuring that the WSDL has the correct
        // SOAP version. We can delegate to the WCF implementation of TextMessageEncodingBindingElement for this.
        TextMessageEncodingBindingElement mebe = new TextMessageEncodingBindingElement();
        mebe.MessageVersion = this.msgVersion;
        ((IWsdlExportExtension)mebe).ExportEndpoint(exporter, context);
    }

    #endregion
}


.NET Framework

Supported in: 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Community Additions

ADD
Show:
© 2014 Microsoft