Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

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 LibrarySupported in .NET for Windows Store appsMessageEncodingBindingElement()Initializes a new instance of the MessageEncodingBindingElement class.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsMessageEncodingBindingElement(MessageEncodingBindingElement)Initializes a new instance of the MessageEncodingBindingElement class initialized from an existing element.
Top
  NameDescription
Public propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsMessageVersionWhen 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 LibrarySupported in .NET for Windows Store appsBuildChannelFactory<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 LibrarySupported in .NET for Windows Store appsCanBuildChannelFactory<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 LibrarySupported in .NET for Windows Store appsCloneWhen overridden in a derived class, returns a copy of the binding element object. (Inherited from BindingElement.)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreateMessageEncoderFactoryWhen overridden in a derived class, creates a factory for producing message encoders.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsFinalizeAllows 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 LibrarySupported in .NET for Windows Store appsGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetProperty<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 LibrarySupported in .NET for Windows Store appsGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsToStringReturns 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. Windows Communication Foundation (WCF) 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.

Windows Communication Foundation (WCF) 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 WCF 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.5.1, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone 8, Silverlight 8.1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.