MessageEncodingBindingElement Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
The binding element that specifies the message version used to encode messages.
public ref class MessageEncodingBindingElement abstract : System::ServiceModel::Channels::BindingElementpublic abstract class MessageEncodingBindingElement : System.ServiceModel.Channels.BindingElementtype MessageEncodingBindingElement = class
inherit BindingElementPublic MustInherit Class MessageEncodingBindingElement
Inherits BindingElement- Inheritance
- Derived
Examples
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(nameof(encoding));
if (mediaType == null)
throw new ArgumentNullException(nameof(mediaType));
if (msgVersion == null)
throw new ArgumentNullException(nameof(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(nameof(value));
this.msgVersion = value;
}
}
public string MediaType
{
get
{
return this.mediaType;
}
set
{
if (value == null)
throw new ArgumentNullException(nameof(value));
this.mediaType = value;
}
}
public string Encoding
{
get
{
return this.encoding;
}
set
{
if (value == null)
throw new ArgumentNullException(nameof(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(nameof(context));
context.BindingParameters.Add(this);
return context.BuildInnerChannelFactory<TChannel>();
}
public override bool CanBuildChannelFactory<TChannel>(BindingContext context)
{
if (context == null)
throw new ArgumentNullException(nameof(context));
return context.CanBuildInnerChannelFactory<TChannel>();
}
public override IChannelListener<TChannel> BuildChannelListener<TChannel>(BindingContext context)
{
if (context == null)
throw new ArgumentNullException(nameof(context));
context.BindingParameters.Add(this);
return context.BuildInnerChannelListener<TChannel>();
}
public override bool CanBuildChannelListener<TChannel>(BindingContext context)
{
if (context == null)
throw new ArgumentNullException(nameof(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
}
Remarks
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.
Constructors
| MessageEncodingBindingElement() |
Initializes a new instance of the MessageEncodingBindingElement class. |
| MessageEncodingBindingElement(MessageEncodingBindingElement) |
Initializes a new instance of the MessageEncodingBindingElement class initialized from an existing element. |
Properties
| MessageVersion |
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. |
Methods
| BuildChannelFactory<TChannel>(BindingContext) |
Initializes a channel factory for producing channels of a specified type from the binding context. (Inherited from BindingElement) |
| BuildChannelListener<TChannel>(BindingContext) |
Initializes a channel listener to accept channels of a specified type from the binding context. (Inherited from BindingElement) |
| CanBuildChannelFactory<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) |
| CanBuildChannelListener<TChannel>(BindingContext) |
Returns a value that indicates whether the binding element can build a listener for a specific type of channel. (Inherited from BindingElement) |
| Clone() |
When overridden in a derived class, returns a copy of the binding element object. (Inherited from BindingElement) |
| CreateMessageEncoderFactory() |
When overridden in a derived class, creates a factory for producing message encoders. |
| Equals(Object) |
Determines whether the specified object is equal to the current object. (Inherited from Object) |
| GetHashCode() |
Serves as the default hash function. (Inherited from Object) |
| GetProperty<T>(BindingContext) |
Returns the typed object requested, if present, from the appropriate layer in the channel stack. |
| GetType() |
Gets the Type of the current instance. (Inherited from Object) |
| MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
| ToString() |
Returns a string that represents the current object. (Inherited from Object) |
