Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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

NameDescription
System_CAPS_protmethodMessageEncodingBindingElement()

Initializes a new instance of the MessageEncodingBindingElement class.

System_CAPS_protmethodMessageEncodingBindingElement(MessageEncodingBindingElement)

Initializes a new instance of the MessageEncodingBindingElement class initialized from an existing element.

NameDescription
System_CAPS_pubpropertyMessageVersion

When 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.

NameDescription
System_CAPS_pubmethodBuildChannelFactory<TChannel>(BindingContext)

Initializes a channel factory for producing channels of a specified type from the binding context.(Inherited from BindingElement.)

System_CAPS_pubmethodBuildChannelListener<TChannel>(BindingContext)

Initializes a channel listener to accept channels of a specified type from the binding context.(Inherited from BindingElement.)

System_CAPS_pubmethodCanBuildChannelFactory<TChannel>(BindingContext)

Returns a value that indicates whether the binding element can build a channel factory for a specific type of channel.(Inherited from BindingElement.)

System_CAPS_pubmethodCanBuildChannelListener<TChannel>(BindingContext)

Returns a value that indicates whether the binding element can build a listener for a specific type of channel.(Inherited from BindingElement.)

System_CAPS_pubmethodClone()

When overridden in a derived class, returns a copy of the binding element object.(Inherited from BindingElement.)

System_CAPS_pubmethodCreateMessageEncoderFactory()

When overridden in a derived class, creates a factory for producing message encoders.

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetProperty<T>(BindingContext)

Returns the typed object requested, if present, from the appropriate layer in the channel stack.(Overrides BindingElement.GetProperty<T>(BindingContext).)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

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
}

Universal Windows Platform
Available since 8
.NET Framework
Available since 3.0
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0

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

Return to top
Show:
© 2017 Microsoft