MessageEncodingBindingElement 類別

定義

繫結項目,可指定用於編碼訊息的訊息版本。The binding element that specifies the message version used to encode messages.

public ref class MessageEncodingBindingElement abstract : System::ServiceModel::Channels::BindingElement
public abstract class MessageEncodingBindingElement : System.ServiceModel.Channels.BindingElement
type MessageEncodingBindingElement = class
    inherit BindingElement
Public MustInherit Class MessageEncodingBindingElement
Inherits BindingElement
繼承
MessageEncodingBindingElement
衍生

範例

下列程式碼範例會示範如何實作衍生自 MessageEncodingBindingElement 的類別: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
}

備註

編碼是將訊息轉換成位元組序列的處理序,Encoding is the process of transforming a message into a sequence of bytes. 解碼則是相反的處理序。Decoding is the reverse process. Windows Communication Foundation (WCF) 包含 SOAP 訊息的三種編碼類型:文字、二進位和訊息傳輸最佳化機制 (MTOM)。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:

覆寫 Encoder,以傳回自訂 MessageEncoder 的執行個體。Override the Encoder to return an instance of your custom MessageEncoder. 覆寫 CreateMessageEncoderFactory 方法,以傳回這個處理站的執行個體。Override the CreateMessageEncoderFactory method to return an instance of this factory.

任何衍生自 MessageEncodingBindingElement 的型別都會負責更新針對服務所產生之 WSDL 文件中的 SOAP 繫結版本。Any type that derives from MessageEncodingBindingElement is responsible for updating the version of the SOAP binding in the WSDL document generated for the service. 藉由實作 ExportEndpoint(WsdlExporter, WsdlEndpointConversionContext) 方法來修改產生的 WSDL,即可完成此動作。This is done by implementing the ExportEndpoint(WsdlExporter, WsdlEndpointConversionContext) method to modify the generated WSDL.

Windows Communication Foundation (WCF)提供三種類型的繫結項目,衍生自可提供文字、二進位和訊息傳輸優化機制(MTOM)編碼的 MessageEncodingBindingElement 類別。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:互通性最佳、但效率最差的 XML 訊息編碼器。TextMessageEncodingBindingElement: the most interoperable, but the least efficient encoder for XML messages. Web 服務或 Web 服務用戶端通常可以瞭解文字 XML。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:表示繫結項目,指定用於二進位 XML 訊息的字元編碼和訊息版本控制。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:表示繫結項目,該專案會使用訊息傳輸優化機制(MTOM)編碼,指定用於訊息的字元編碼和訊息版本控制。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 是在 WCF 訊息中傳輸二進位資料的有效技術。MTOM is an efficient technology for transmitting binary data in WCF messages. MTOM 編碼器會嘗試在效率和互通性之間保持平衡。The MTOM encoder attempts to balance efficiency and interoperability. MTOM 編碼方式會以文字格式傳輸大部分的 XML,但是在傳輸大型區塊的二進位資料時,會依照原狀來傳送 (不轉換成文字),好讓這些資料最佳化。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.

建構函式

MessageEncodingBindingElement()

初始化 MessageEncodingBindingElement 類別的新執行個體。Initializes a new instance of the MessageEncodingBindingElement class.

MessageEncodingBindingElement(MessageEncodingBindingElement)

初始化從現有項目初始化之 MessageEncodingBindingElement 類別的新執行個體。Initializes a new instance of the MessageEncodingBindingElement class initialized from an existing element.

屬性

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.

方法

BuildChannelFactory<TChannel>(BindingContext)

初始化通道處理站,以便從繫結內容產生指定型別的通道。Initializes a channel factory for producing channels of a specified type from the binding context.

(繼承來源 BindingElement)
BuildChannelListener<TChannel>(BindingContext)

初始化通道接聽項,以便從繫結內容接受指定之類型的通道。Initializes a channel listener to accept channels of a specified type from the binding context.

(繼承來源 BindingElement)
CanBuildChannelFactory<TChannel>(BindingContext)

傳回值,指出繫結項目是否可以建置 (Build) 特定通道類型的通道處理站。Returns a value that indicates whether the binding element can build a channel factory for a specific type of channel.

(繼承來源 BindingElement)
CanBuildChannelListener<TChannel>(BindingContext)

傳回值,指出繫結項目是否可以建置特定通道型別的通道接聽程式。Returns a value that indicates whether the binding element can build a listener for a specific type of channel.

(繼承來源 BindingElement)
Clone()

在衍生類別中覆寫時,傳回繫結項目物件的複本。When overridden in a derived class, returns a copy of the binding element object.

(繼承來源 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.

(繼承來源 Object)
GetHashCode()

做為預設雜湊函式。Serves as the default hash function.

(繼承來源 Object)
GetProperty<T>(BindingContext)

從通道堆疊的適當層次中,傳回要求的型別物件 (如果有的話)。Returns the typed object requested, if present, from the appropriate layer in the channel stack.

GetType()

取得目前執行個體的 TypeGets the Type of the current instance.

(繼承來源 Object)
MemberwiseClone()

建立目前 Object 的淺層複製。Creates a shallow copy of the current Object.

(繼承來源 Object)
ToString()

傳回代表目前物件的字串。Returns a string that represents the current object.

(繼承來源 Object)

適用於