StreamStream

Das Streambeispiel zeigt die Verwendung des Kommunikationsstream-Übertragungsmodus.The Stream sample demonstrates the use of streaming transfer mode communication. Der Dienst macht mehrere Vorgänge verfügbar, die Streams senden und empfangen.The service exposes several operations that send and receive streams. Dieses Beispiel ist selbst gehostet.This sample is self-hosted. Sowohl der Client als auch der Dienst sind Konsolenprogramme.Both the client and service are console programs.

Hinweis

Die Setupprozedur und die Buildanweisungen für dieses Beispiel befinden sich am Ende dieses Themas.The setup procedure and build instructions for this sample are located at the end of this topic.

Windows Communication Foundation (WCF) können in zwei Übertragungsmodi kommunizieren: gepuffert oder per streaming.Windows Communication Foundation (WCF) can communicate in two transfer modes—buffered or streaming. Im standardmäßigen gepufferten Übertragungsmodus müssen Nachrichten vollständig übertragen worden sein, bevor sie vom Empfänger gelesen werden können.In the default buffered transfer mode, a message must be completely delivered before a receiver can read it. Im Streaming-Übertragungsmodus kann der Empfänger mit der Verarbeitung der Nachricht beginnen, bevor diese vollständig übertragen wurde.In the streaming transfer mode, the receiver can begin to process the message before it is completely delivered. Der Streamingmodus ist hilfreich, wenn die zu übergebenden Informationen sehr umfangreich sind und hintereinander verarbeitet werden können.The streaming mode is useful when the information that is passed is lengthy and can be processed serially. Der Streamingmodus ist auch dann nützlich, wenn eine Nachricht zu groß ist, um als Ganzes gepuffert zu werden.Streaming mode is also useful when the message is too large to be entirely buffered.

Streaming und DienstverträgeStreaming and Service Contracts

Streaming ist es wert, beim Entwerfen eines Dienstvertrags in Betracht gezogen zu werden.Streaming is something to be considered when designing a service contract. Wenn ein Vorgang Daten in großem Umfang empfängt oder zurückgibt, sollte man in Betracht ziehen, diese Daten zu streamen, um eine übermäßige Auslastung des Arbeitsspeichers durch das Puffern ein- oder ausgehender Nachrichten zu vermeiden.If an operation receives or returns large amounts of data, you should consider streaming this data to avoid high memory utilization due to buffering of input or output messages. Zum Übertragen von Daten im Streamingmodus muss der Parameter, der die Daten enthält, der einzige Parameter in der Nachricht sein.To stream data, the parameter that holds that data must be the only parameter in the message. Wenn beispielsweise die Eingabenachricht im Streamingmodus übertragen werden soll, muss der Vorgang genau einen Eingabeparameter haben.For example, if the input message is the one to be streamed, the operation must have exactly one input parameter. Ebenso gilt, wenn die Ausgabenachricht im Streamingmodus übertragen werden soll, muss der Vorgang entweder genau einen Ausgabeparameter oder einen Rückgabewert haben.Similarly, if the output message is to be streamed, the operation must have either exactly one output parameter or a return value. In beiden Fällen muss der Parameter- oder Rückgabewerttyp Stream, Message oder IXmlSerializable sein.In either case, the parameter or return value type must be either Stream, Message, or IXmlSerializable. Nachfolgend ist der in diesem Streamingbeispiel verwendete Dienstvertrag aufgeführt.The following is the service contract used in this streaming sample.

[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]  
public interface IStreamingSample  
{  
    [OperationContract]  
    Stream GetStream(string data);  
    [OperationContract]  
    bool UploadStream(Stream stream);  
    [OperationContract]  
    Stream EchoStream(Stream stream);  
    [OperationContract]  
    Stream GetReversedStream();  

}  

Der GetStream-Vorgang empfängt Eingabedaten als Zeichenfolge, die gepuffert wird, und gibt einen Stream zurück, der im Streamingmodus übertragen wird.The GetStream operation receives some input data as a string, which is buffered, and returns a Stream, which is streamed. Umgekehrt nimmt UploadStream einen (per Streaming übertragenen) Stream entgegen und gibt einen (gepufferten) bool zurück.Conversely, UploadStream takes in a Stream (streamed) and returns a bool (buffered). EchoStream akzeptiert und gibt einen Wert des Typs Stream zurück und ist ein Beispiel für einen Vorgang, dessen Eingabe- und Ausgabenachrichten per Streaming übertragen werden.EchoStream takes and returns Stream and is an example of an operation whose input and output messages are both streamed. GetReversedStream akzeptiert keine Eingaben und gibt einen Stream-Wert (im Streamingmodus) zurück.Finally, GetReversedStream takes no inputs and returns a Stream (streamed).

Aktivieren von StreamübertragungenEnabling Streamed Transfers

Wenn Sie Vorgangsverträge wie oben beschrieben definieren, können Sie Streaming auf Programmiermodellebene durchführen.Defining operation contracts as previously described provides streaming at the programming model level. Wenn Sie an dieser Stelle aufhören, wird immer noch der gesamte Nachrichteninhalt vom Transport gepuffert.If you stop there, the transport still buffers the entire message content. Zum Aktivieren von Transportstreaming müssen Sie im Bindungselement des Transports einen Übertragungsmodus auswählen.To enable transport streaming, select a transfer mode on the binding element of the transport. Das Bindungselement weist eine TransferMode-Eigenschaft auf, die auf Buffered, Streamed, StreamedRequest oder StreamedResponse festgelegt werden kann.The binding element has a TransferMode property that can be set to Buffered, Streamed, StreamedRequest, or StreamedResponse. Wenn Sie den Übertragungsmodus auf Streamed festlegen, wird ein Kommunikationsstream in beide Richtungen ermöglicht.Setting the transfer mode to Streamed enables streaming communication in both directions. Wenn Sie den Übertragungsmodus auf StreamedRequest oder StreamedResponse festlegen, wird ein Kommunikationsstream nur in der jeweiligen Richtung (Anforderung bzw. Antwort) ermöglicht.Setting the transfer mode to StreamedRequest or StreamedResponse enables streaming communication in only the request or response, respectively.

Die basicHttpBinding macht die TransferMode-Eigenschaft für die Bindung verfügbar, wie dies ebenso bei NetTcpBinding und NetNamedPipeBinding der Fall ist.The basicHttpBinding exposes the TransferMode property on the binding as does NetTcpBinding and NetNamedPipeBinding. Für andere Transporte müssen Sie eine benutzerdefinierte Bindung erstellen, um den Übertragungsmodus festzulegen.For other transports, you must create a custom binding to set the transfer mode.

Der folgende Konfigurationscode aus dem Beispiel zeigt, wie die TransferMode-Eigenschaft in der basicHttpBinding und eine benutzerdefinierte HTTP-Bindung auf den Streamingmodus festgelegt wird.The following configuration code from the sample shows setting the TransferMode property to streaming on the basicHttpBinding and a custom HTTP binding:

<!-- An example basicHttpBinding using streaming. -->  
<basicHttpBinding>  
  <binding name="HttpStreaming" maxReceivedMessageSize="67108864"  
           transferMode="Streamed"/>  
</basicHttpBinding>  
<!-- An example customBinding using HTTP and streaming.-->  
<customBinding>  
  <binding name="Soap12">  
    <textMessageEncoding messageVersion="Soap12WSAddressing10" />  
    <httpTransport transferMode="Streamed"  
                   maxReceivedMessageSize="67108864"/>  
  </binding>  
</customBinding>  

Zusätzlich zum Festlegen des transferMode auf Streamed legt der oben aufgeführte Konfigurationscode die maxReceivedMessageSize auf 64 MB fest.In addition to setting the transferMode to Streamed, the previous configuration code sets the maxReceivedMessageSize to 64MB. Als Schutzmechanismus legt maxReceivedMessageSize einen Höchstwert für die maximal zulässige Größe von Nachrichten beim Empfang fest.As a defense mechanism, maxReceivedMessageSize places a cap on the maximum allowable size of messages on receive. Die Standardeinstellung von maxReceivedMessageSize ist 64 KB, was normalerweise zu niedrig für die Verwendung des Streamingmodus ist.The default maxReceivedMessageSize is 64 KB, which is usually too low for streaming scenarios.

Verarbeiten von Daten bei deren StreamingübertragungProcessing Data As It Is Streamed

Bei den Vorgängen GetStream, UploadStream und EchoStream werden Daten direkt aus einer Datei gesendet oder empfangene Daten direkt in einer Datei gespeichert.The operations GetStream, UploadStream and EchoStream all deal with sending data directly from a file or saving received data directly to a file. In manchen Fällen ist es jedoch erforderlich, große Mengen von Daten zu senden oder zu empfangen und Teile dieser Daten dabei zu verarbeiten.However in some cases, there is a requirement to send or receive large amounts of data and perform some processing on chunks of the data as it is being sent or received. Eine Möglichkeit in solchen Situationen wäre, einen benutzerdefinierten Stream (eine Klasse, die sich von Stream ableitet) zu schreiben, der Daten verarbeitet, während diese gelesen oder geschrieben werden.One way to address such scenarios is to write a custom stream (a class that derives from Stream) that processes data as it is read or written. Der GetReversedStream-Vorgang und die ReverseStream-Klasse sind ein Beispiel für ein solches Vorgehen.The GetReversedStream operation and ReverseStream class are an example of this.

GetReversedStream erstellt eine neue Instanz der ReverseStream-Klasse und gibt eine Instanz dieser Klasse zurück.GetReversedStream creates and returns a new instance of ReverseStream. Die tatsächliche Verarbeitung erfolgt, wenn das System Daten aus diesem ReverseStream-Objekt liest.The actual processing happens as the system reads from that ReverseStream object. Die ReverseStream.Read-Implementierung liest eine Gruppe von Bytes aus der zugrunde liegenden Datei, invertiert die Reihenfolge der Bytes und gibt die invertierten Bytes zurück.The ReverseStream.Read implementation reads a chunk of bytes from the underlying file, reverses them, then returns the reversed bytes. Sie invertiert nicht den gesamten Dateiinhalt, sondern immer nur eine Gruppe von Bytes auf einmal.This does not reverse the entire file content; it reverses one chunk of bytes at a time. Dieses Beispiel zeigt, wie Sie das Verarbeiten eines Streams durchführen können, wenn der Inhalt aus dem Stream gelesen oder in den Stream geschrieben wird.This is an example to show how you can perform stream processing as the content is being read or written from and to the stream.

class ReverseStream : Stream  
{  

    FileStream inStream;  
    internal ReverseStream(string filePath)  
    {  
        //Opens the file and places a StreamReader around it.  
        inStream = File.OpenRead(filePath);  
    }  

    // Other methods removed for brevity.  

    public override int Read(byte[] buffer, int offset, int count)  
    {  
        int countRead=inStream.Read(buffer, offset,count);  
        ReverseBuffer(buffer, offset, countRead);  
        return countRead;  
    }  

    public override void Close()  
    {  
        inStream.Close();  
        base.Close();  
    }  
    protected override void Dispose(bool disposing)  
    {  
        inStream.Dispose();  
        base.Dispose(disposing);  
    }  
    void ReverseBuffer(byte[] buffer, int offset, int count)  
    {  
        int i, j;  
        for (i = offset, j = offset + count - 1; i < j; i++, j--)  
        {  
            byte currenti = buffer[i];  
            buffer[i] = buffer[j];  
            buffer[j] = currenti;  
        }  

    }  
}  

Ausführen des BeispielsRunning the Sample

Zum Ausführen des Beispiels müssen Sie zuerst den Dienst und den Client nach den am Ende dieses Dokuments aufgeführten Anweisungen erstellen.To run the sample, first build both the service and the client by following the directions at the end of this document. Starten Sie dann den Dienst und den Client in zwei verschiedenen Konsolenfenstern.Then start the service and the client in two different console windows. Beim Starten wartet der Client, dass Sie die EINGABETASTE drücken, wenn der Dienst bereit ist.When the client starts, it waits for you to press ENTER when the service is ready. Dann ruft der Client die Methoden GetStream(), UploadStream() und GetReversedStream() erst über HTTP und dann über TCP auf.The client then calls the methods GetStream(), UploadStream() and GetReversedStream() first over HTTP and then over TCP. Nachfolgend sehen Sie eine Beispielausgabe aus dem Dienst und dann eine Beispielausgabe aus dem Client:Here is an example output from the service followed by example output from the client:

Dienstausgabe:Service Output:

The streaming service is ready.  
Press <ENTER> to terminate service.  

Saving to file D:\...\uploadedfile  
......................  
File D:\...\uploadedfile saved  
Saving to file D:\...\uploadedfile  
...............  
File D:\...\uploadedfile saved  

Clientausgabe:Client Output:

Press <ENTER> when service is ready  
------ Using HTTP ------   
Calling GetStream()  
Saving to file D:\...\clientfile  
......................  
Wrote 33405 bytes to stream  

File D:\...\clientfile saved  
Calling UploadStream()  
Calling GetReversedStream()  
Saving to file D:\...\clientfile  
......................  
Wrote 33405 bytes to stream  

File D:\...\clientfile saved  
------ Using Custom HTTP ------  
Calling GetStream()  
Saving to file D:\...\clientfile  
...............  
Wrote 33405 bytes to stream  

File D:\...\clientfile saved  
Calling UploadStream()  
Calling GetReversedStream()  
Saving to file D:\...\clientfile  
...............  
Wrote 33405 bytes to stream  

File D:\...\clientfile saved  

Press <ENTER> to terminate client.  

So können Sie das Beispiel einrichten, erstellen und ausführenTo set up, build, and run the sample

  1. Stellen Sie sicher, dass Sie ausgeführt haben die Setupprozedur für die Windows Communication Foundation-Beispiele zum einmaligen.Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.

  2. Um die C#- oder Visual Basic .NET-Edition der Projektmappe zu erstellen, befolgen Sie die unter Building the Windows Communication Foundation Samplesaufgeführten Anweisungen.To build the C# or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.

  3. Um das Beispiel in einer einzelnen oder computerübergreifenden Konfiguration ausführen möchten, folgen Sie den Anweisungen Ausführen der Windows Communication Foundation-Beispiele.To run the sample in a single- or cross-machine configuration, follow the instructions in Running the Windows Communication Foundation Samples.

Hinweis

Wenn Sie zur Neugenerierung der Konfiguration für dieses Beispiel die Datei Svcutil.exe verwenden, müssen Sie den Endpunktnamen in der Clientkonfiguration so ändern, dass er mit dem Clientcode übereinstimmt.If you use Svcutil.exe to regenerate the configuration for this sample, be sure to modify the endpoint name in the client configuration to match the client code.

Wichtig

Die Beispiele sind möglicherweise bereits auf dem Computer installiert.The samples may already be installed on your machine. Suchen Sie nach dem folgenden Verzeichnis (Standardverzeichnis), bevor Sie fortfahren.Check for the following (default) directory before continuing.

<InstallDrive>:\WF_WCF_Samples

Wenn dieses Verzeichnis nicht vorhanden ist, fahren Sie mit Windows Communication Foundation (WCF) und Windows Workflow Foundation (WF) Samples for .NET Framework 4 aller Windows Communication Foundation (WCF) herunterladen und WFWF Beispiele.If this directory does not exist, go to Windows Communication Foundation (WCF) and Windows Workflow Foundation (WF) Samples for .NET Framework 4 to download all Windows Communication Foundation (WCF) and WFWF samples. Dieses Beispiel befindet sich im folgenden Verzeichnis.This sample is located in the following directory.

<InstallDrive>:\WF_WCF_Samples\WCF\Basic\Contract\Service\Stream

Siehe auchSee Also