WCF Web-HTTP-FormatierungWCF Web HTTP formatting

Mit dem WCF-Web-HTTP-Programmiermodell können Sie dynamisch das beste Format für einen Dienstvorgang bestimmen, in dem dieser seine Antwort zurückgibt.The WCF Web HTTP programming model allows you to dynamically determine the best format for a service operation to return its response in. Es werden zwei Methoden zum Bestimmen eines entsprechenden Formats unterstützt: automatisch und explizit.Two methods for determining an appropriate format are supported: automatic and explicit.

Automatische FormatierungAutomatic formatting

Wenn Sie aktiviert ist, wählt die automatische Formatierung das beste Format aus, in dem die Antwort zurückgegeben wird.When enabled, automatic formatting chooses the best format in which to return the response. Das beste Format wird bestimmt, indem Folgendes in der unten angegebenen Reihenfolge überprüft wird:It determines the best format by checking the following, in order:

  1. Medientypen im Accept-Header der AnforderungsnachrichtThe media types in the request message’s Accept header.

  2. Inhaltstyp der AnforderungsnachrichtThe content-type of the request message.

  3. Standardformateinstellung des VorgangsThe default format setting in the operation.

  4. Standardformateinstellung unter WebHttpBehaviorThe default format setting in the WebHttpBehavior.

Falls die Anforderungsnachricht einen Accept-Header enthält, sucht die Windows Communication Foundation (WCF)Windows Communication Foundation (WCF)-Infrastruktur nach einem Typ, der unterstützt wird.If the request message contains an Accept header the Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) infrastructure searches for a type that it supports. Wenn der Accept-Header Prioritäten für seine Medientypen angibt, werden diese beachtet.If the Accept header specifies priorities for its media types, they are honored. Wird im Accept-Header kein geeignetes Format gefunden, wird der Inhaltstyp der Anforderungsnachricht verwendet.If no suitable format is found in the Accept header, the content-type of the request message is used. Wird kein geeigneter Inhaltstyp angegeben, wird die Standardformateinstellung für den Vorgang verwendet.If no suitable content-type is specified, the default format setting for the operation is used. Das Standardformat wird mit dem ResponseFormat-Parameter der Attribute WebGetAttribute und WebInvokeAttribute festgelegt.The default format is set with the ResponseFormat parameter of the WebGetAttribute and WebInvokeAttribute attributes. Falls für den Vorgang kein Standardformat angegeben ist, wird der Wert der DefaultOutgoingResponseFormat-Eigenschaft verwendet.If no default format is specified on the operation, the value of the DefaultOutgoingResponseFormat property is used. Die automatische Formatierung verwendet die AutomaticFormatSelectionEnabled-Eigenschaft.Automatic formatting relies on the AutomaticFormatSelectionEnabled property. Wenn diese Eigenschaft auf true festgelegt wird, bestimmte die WCFWCF-Infrastruktur das beste Format.When this property is set to true, the WCFWCF infrastructure determines the best format to use. Die automatische Formatauswahl ist standardmäßig deaktiviert, um die Abwärtskompatibilität sicherzustellen.Automatic format selection is disabled by default for backwards compatibility. Sie können die automatische Formatauswahl programmgesteuert oder per Konfiguration aktivieren.Automatic format selection can be enabled programmatically or through configuration. Im folgenden Beispiel wird gezeigt, wie Sie die automatische Formatauswahl im Code aktivieren.The following example shows how to enable automatic format selection in code.

// This code assumes the service name is MyService and the service contract is IMyContract     
Uri baseAddress = new Uri("http://localhost:8000");  

WebServiceHost host = new WebServiceHost(typeof(MyService), baseAddress)  
try  
{  
   ServiceEndpoint sep = host.AddServiceEndpoint(typeof(IMyContract), new WebHttpBinding(), "");  
   // Check it see if the WebHttpBehavior already exists  
   WebHttpBehavior whb = sep.Behaviors.Find<WebHttpBehavior>();  

   if (whb != null)  
   {  
      whb.AutomaticFormatSelectionEnabled = true;  
   }  
   else  
   {  
      WebHttpBehavior webBehavior = new WebHttpBehavior();  
      webBehavior.AutomaticFormatSelectionEnabled = true;  
      sep.Behaviors.Add(webBehavior);  
   }  
         // Open host to start listening for messages  
   host.Open();        

  // ...  
}  
  catch(CommunicationException ex)  
  {  
     Console.WriteLine("An exception occurred: " + ex.Message());  
  }  

Sie können die automatische Formatierung auch per Konfiguration aktivieren.Automatic formatting can also be enabled through configuration. Legen Sie dazu die AutomaticFormatSelectionEnabled-Eigenschaft direkt unter WebHttpBehavior festlegen oder WebHttpEndpoint verwenden.You can set the AutomaticFormatSelectionEnabled property directly on the WebHttpBehavior or using the WebHttpEndpoint. Im folgenden Beispiel wird gezeigt, wie Sie die automatische Formatauswahl unter WebHttpBehavior aktivieren.The following example shows how to enable the automatic format selection on the WebHttpBehavior.

<system.serviceModel>  
  <behaviors>  
    <endpointBehaviors>  
      <behavior>  
        <webHttp automaticFormatSelectionEnabled="true" />  
      </behavior>  
    </endpointBehaviors>  
  </behaviors>  
  <standardEndpoints>  
    <webHttpEndpoint>  
      <!-- the "" standard endpoint is used by WebServiceHost for auto creating a web endpoint. -->  
      <standardEndpoint name="" helpEnabled="true" />  
    </webHttpEndpoint>  
  </standardEndpoints>  
</system.serviceModel>  

Im folgenden Beispiel wird gezeigt, wie Sie die automatische Formatauswahl mithilfe von WebHttpEndpoint aktivieren.The following example shows how to enable automatic format selection using WebHttpEndpoint.

<system.serviceModel>  
    <standardEndpoints>  
      <webHttpEndpoint>  
        <!-- the "" standard endpoint is used by WebServiceHost for auto creating a web endpoint. -->  
        <standardEndpoint name="" helpEnabled="true" automaticFormatSelectionEnabled="true"  />  
      </webHttpEndpoint>  
    </standardEndpoints>  
  </system.serviceModel>  

Explizite FormatierungExplicit formatting

Wie der Name bereits vermuten lässt, bestimmt bei der expliziten Formatierung der Entwickler das beste Format für die Verwendung im Vorgangscode.As the name implies, in explicit formatting the developer determines the best format to use within the operation code. Falls das beste Format XML oder JSON ist, legt der Entwickler Format auf Xml oder Json fest.If the best format is XML or JSON the developer sets Format to either Xml or Json. Falls die Format-Eigenschaft nicht explizit festgelegt wird, wird das Standardformat des Vorgangs verwendet.If the Format property is not explicitly set, then the operation’s default format is used.

Im folgenden Beispiel wird der Formatabfrage-Zeichenfolgenparameter für ein zu verwendendes Format überprüft.The following example checks the format query string parameter for a format to use. Wenn er angegeben wurde, wird das Format des Vorgangs mit Format festgelegt.If it has been specified, it sets the operation’s format using Format.

public class Service : IService  
{  
    [WebGet]  
     public string EchoWithGet(string s)  
    {  
         // if a format query string parameter has been specified, set the response format to that. If no such  
         // query string parameter exists the Accept header will be used  
        string formatQueryStringValue = WebOperationContext.Current.IncomingRequest.UriTemplateMatch.QueryParameters["format"];  
        if (!string.IsNullOrEmpty(formatQueryStringValue))  
        {  
             if (formatQueryStringValue.Equals("xml", System.StringComparison.OrdinalIgnoreCase))  
             {  
                  WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Xml;  
             }  
             else if (formatQueryStringValue.Equals("json", System.StringComparison.OrdinalIgnoreCase))  
            {  
                WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Json;  
            }  
            else  
            {  
                 throw new WebFaultException<string>(string.Format("Unsupported format '{0}'", formatQueryStringValue), HttpStatusCode.BadRequest);  
            }  
        }  
        return "You said " + s;  
    }  

Falls Sie andere Formate als XML oder JSON unterstützen müssen, definieren Sie für den Vorgang den Rückgabetyp Message.If you need to support formats other than XML or JSON, define your operation to have a return type of Message. Bestimmen Sie innerhalb des Vorgangscodes das passende Format, und erstellen SIe dann ein Message-Objekt, indem Sie eine der folgenden Methoden verwenden:Within the operation code, determine the appropriate format to use and then create a Message object using one of the following methods:

  • WebOperationContext.CreateAtom10Response

  • WebOperationContext.CreateJsonResponse

  • WebOperationContext.CreateStreamResponse

  • WebOperationContext.CreateTextResponse

  • WebOperationContext.CreateXmlResponse

Jede dieser Methoden verwendet Inhalt und erstellt eine Nachricht im passenden Format.Each of these methods takes content and creates a message with the appropriate format. Sie können die WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements-Methode verwenden, um eine Liste der vom Client bevorzugten Formate in der entsprechenden Reihenfolge abzurufen.The WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements method can be used to get a list of formats preferred by the client in order of decreasing preference. Das folgende Beispiel zeigt, wie Sie WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements verwenden, um das Format zu bestimmen. Anschließend wird die entsprechende Methode zum Erstellen der Antwortnachricht verwendet.The following example shows how to use WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements to determine the format to use and then uses the appropriate create response method to create the response message.

public class Service : IService  
{  
    public Message EchoListWithGet(string list)  
    {  
        List<string> returnList = new List<string>(list.Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries));  
        IList<ContentType> acceptHeaderElements = WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements();  
        for (int x = 0; x < acceptHeaderElements.Count; x++)  
        {  
            string normalizedMediaType = acceptHeaderElements[x].MediaType.ToLowerInvariant();  
            switch (normalizedMediaType)  
            {  
                case "image/jpeg": return CreateJpegResponse(returnList);  
                case "application/xhtml+xml": return CreateXhtmlResponse(returnList);  
                case "application/atom+xml": return CreateAtom10Response(returnList);  
                case "application/xml": return CreateXmlResponse(returnList);  
                case "application/json": return CreateJsonResponse(returnList);  
          }  
    }  

    // Default response format is XML  
    return CreateXmlResponse(returnList);  
    }  
}  

Siehe auchSee also

UriTemplate
UriTemplateMatch
WCF-Web-HTTP-ProgrammiermodellWCF Web HTTP Programming Model
UriTemplate und UriTemplateTableUriTemplate and UriTemplateTable
Überblick über das WCF-Web-HTTP-ProgrammiermodellWCF Web HTTP Programming Model Overview
Objektmodell für WCF-Web-HTTP-ProgrammierungWCF Web HTTP Programming Object Model