クライアントのランタイム動作の指定Specifying Client Run-Time Behavior

クライアント アプリケーションに合わせて実行時の動作を変更するのには、Windows Communication Foundation (WCF) サービスと同様、Windows Communication Foundation (WCF) クライアントを構成できます。Windows Communication Foundation (WCF) clients, like Windows Communication Foundation (WCF) services, can be configured to modify the run-time behavior to suit the client application. クライアントのランタイム動作を指定する際には、3 つの属性を使用できます。Three attributes are available for specifying client run-time behavior. 双方向クライアント コールバック オブジェクトは、CallbackBehaviorAttribute 属性と CallbackDebugBehavior 属性を使用して、そのランタイム動作を変更できます。Duplex client callback objects can use the CallbackBehaviorAttribute and CallbackDebugBehavior attributes to modify their run-time behavior. もう 1 つの属性 ClientViaBehavior は、論理送信先を直接のネットワーク送信先と区別するために使用できます。The other attribute, ClientViaBehavior, can be used to separate the logical destination from the immediate network destination. さらに、双方向クライアントのコールバック型では、サービス側の動作の一部を使用できます。In addition, duplex client callback types can use some of the service-side behaviors. 詳細については、次を参照してください。サービスの実行時の動作を指定するします。For more information, see Specifying Service Run-Time Behavior.

CallbackBehaviorAttribute の使用Using the CallbackBehaviorAttribute

CallbackBehaviorAttribute クラスを使用して、クライアント アプリケーションのコールバック コントラクト実装の実行動作を構成または拡張できます。You can configure or extend the execution behavior of a callback contract implementation in a client application by using the CallbackBehaviorAttribute class. この属性は、インスタンス化動作とトランザクションの設定を除き、ServiceBehaviorAttribute クラスと同様の機能をコールバック クラスに対して実行します。This attribute performs a similar function for the callback class as the ServiceBehaviorAttribute class, with the exception of instancing behavior and transaction settings.

CallbackBehaviorAttribute クラスは、コールバック コントラクトを実装するクラスに適用する必要があります。The CallbackBehaviorAttribute class must be applied to the class that implements the callback contract. 双方向以外のコントラクト実装に適用した場合は、実行時に InvalidOperationException 例外がスローされます。If applied to a nonduplex contract implementation, an InvalidOperationException exception is thrown at run time. CallbackBehaviorAttribute オブジェクトを使用してマーシャリングするスレッドを決定するコールバック オブジェクトの SynchronizationContext クラス、メッセージ検証を実施する ValidateMustUnderstand プロパティ、およびデバッグのために例外を IncludeExceptionDetailInFaults オブジェクトとしてサービスに返す FaultException プロパティのコード例を次に示します。The following code example shows a CallbackBehaviorAttribute class on a callback object that uses the SynchronizationContext object to determine the thread to marshal to, the ValidateMustUnderstand property to enforce message validation, and the IncludeExceptionDetailInFaults property to return exceptions as FaultException objects to the service for debugging purposes.

using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Threading;

namespace Microsoft.WCF.Documentation
{
  [CallbackBehaviorAttribute(
   IncludeExceptionDetailInFaults= true, 
    UseSynchronizationContext=true,
    ValidateMustUnderstand=true
  )]
  public class Client : SampleDuplexHelloCallback
  {
    AutoResetEvent waitHandle;

    public Client()
    {
      waitHandle = new AutoResetEvent(false);
    }

    public void Run()
    {
      // Picks up configuration from the configuration file.
      SampleDuplexHelloClient wcfClient
        = new SampleDuplexHelloClient(new InstanceContext(this), "WSDualHttpBinding_SampleDuplexHello");
      try
      {
        Console.ForegroundColor = ConsoleColor.White;
        Console.WriteLine("Enter a greeting to send and press ENTER: ");
        Console.Write(">>> ");
        Console.ForegroundColor = ConsoleColor.Green;
        string greeting = Console.ReadLine();
        Console.ForegroundColor = ConsoleColor.White;
        Console.WriteLine("Called service with: \r\n\t" + greeting);
        wcfClient.Hello(greeting);
        Console.WriteLine("Execution passes service call and moves to the WaitHandle.");
        this.waitHandle.WaitOne();
        Console.ForegroundColor = ConsoleColor.Blue;
        Console.WriteLine("Set was called.");
        Console.Write("Press ");
        Console.ForegroundColor = ConsoleColor.Red;
        Console.Write("ENTER");
        Console.ForegroundColor = ConsoleColor.Blue;
        Console.Write(" to exit...");
        Console.ReadLine();
      }
      catch (TimeoutException timeProblem)
      {
        Console.WriteLine("The service operation timed out. " + timeProblem.Message);
        Console.ReadLine();
      }
      catch (CommunicationException commProblem)
      {
        Console.WriteLine("There was a communication problem. " + commProblem.Message);
        Console.ReadLine();
      }
    }
    public static void Main()
    {
      Client client = new Client();
      client.Run();
    }

    public void Reply(string response)
    {
      Console.WriteLine("Received output.");
      Console.WriteLine("\r\n\t" + response);
      this.waitHandle.Set();
    }
  }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.ServiceModel
Imports System.ServiceModel.Channels
Imports System.Threading

Namespace Microsoft.WCF.Documentation
  <CallbackBehaviorAttribute(IncludeExceptionDetailInFaults:= True, UseSynchronizationContext:=True, ValidateMustUnderstand:=True)> _
  Public Class Client
      Implements SampleDuplexHelloCallback
    Private waitHandle As AutoResetEvent

    Public Sub New()
      waitHandle = New AutoResetEvent(False)
    End Sub

    Public Sub Run()
      ' Picks up configuration from the configuration file.
      Dim wcfClient As New SampleDuplexHelloClient(New InstanceContext(Me), "WSDualHttpBinding_SampleDuplexHello")
      Try
        Console.ForegroundColor = ConsoleColor.White
        Console.WriteLine("Enter a greeting to send and press ENTER: ")
        Console.Write(">>> ")
        Console.ForegroundColor = ConsoleColor.Green
        Dim greeting As String = Console.ReadLine()
        Console.ForegroundColor = ConsoleColor.White
        Console.WriteLine("Called service with: " & Constants.vbCrLf & Constants.vbTab & greeting)
        wcfClient.Hello(greeting)
        Console.WriteLine("Execution passes service call and moves to the WaitHandle.")
        Me.waitHandle.WaitOne()
        Console.ForegroundColor = ConsoleColor.Blue
        Console.WriteLine("Set was called.")
        Console.Write("Press ")
        Console.ForegroundColor = ConsoleColor.Red
        Console.Write("ENTER")
        Console.ForegroundColor = ConsoleColor.Blue
        Console.Write(" to exit...")
        Console.ReadLine()
      Catch timeProblem As TimeoutException
        Console.WriteLine("The service operation timed out. " & timeProblem.Message)
        Console.ReadLine()
      Catch commProblem As CommunicationException
        Console.WriteLine("There was a communication problem. " & commProblem.Message)
        Console.ReadLine()
      End Try
    End Sub
    Public Shared Sub Main()
      Dim client As New Client()
      client.Run()
    End Sub

    Public Sub Reply(ByVal response As String) Implements SampleDuplexHelloCallback.Reply
      Console.WriteLine("Received output.")
      Console.WriteLine(Constants.vbCrLf & Constants.vbTab & response)
      Me.waitHandle.Set()
    End Sub
  End Class
End Namespace

CallbackDebugBehavior を使用したマネージド例外情報のフローの有効化Using CallbackDebugBehavior to Enable the Flow of Managed Exception Information

アプリケーション構成ファイルまたはプログラムで、IncludeExceptionDetailInFaults プロパティを true に設定すると、デバッグのためにクライアント コールバック オブジェクト内のマネージ例外情報をサービスに戻すフローを有効にできます。You can enable the flow of managed exception information in a client callback object back to the service for debugging purposes by setting the IncludeExceptionDetailInFaults property to true either programmatically or from an application configuration file.

マネージ例外情報をサービスに戻すのは、セキュリティ リスクになる可能性があります。これは、例外の詳細により、非承認のサービスで使用可能な内部クライアントの実装についての情報が公開されるからです。Returning managed exception information to services can be a security risk because exception details expose information about the internal client implementation that unauthorized services could use. さらに、CallbackDebugBehavior プロパティをプログラムで設定することはできますが、配置するときに IncludeExceptionDetailInFaults を無効にすることを忘れがちになります。In addition, although the CallbackDebugBehavior properties can also be set programmatically, it can be easy to forget to disable IncludeExceptionDetailInFaults when deploying.

セキュリティの問題にかかわるので、以下を強くお勧めします。Because of the security issues involved, it is strongly recommended that:

  • IncludeExceptionDetailInFaults プロパティの値を true に設定するには、アプリケーション構成ファイルを使用します。You use an application configuration file to set the value of the IncludeExceptionDetailInFaults property to true.

  • これは、制御されたデバッグ シナリオの場合に限って行います。You do so only in controlled debugging scenarios.

次のコード例は、クライアントをクライアントからのマネージ例外情報をコールバック オブジェクト返す SOAP メッセージでの WCF に指示する構成ファイルを示します。The following code example shows a client configuration file that instructs WCF to return managed exception information from a client callback object in SOAP messages.

  <client>
      <endpoint 
        address="http://localhost:8080/DuplexHello" 
        binding="wsDualHttpBinding"
        bindingConfiguration="WSDualHttpBinding_SampleDuplexHello"
        contract="SampleDuplexHello" 
        name="WSDualHttpBinding_SampleDuplexHello"
        behaviorConfiguration="enableCallbackDebug">
      </endpoint>
  </client>
<behaviors>
  <endpointBehaviors>
    <behavior name="enableCallbackDebug">
      <callbackDebug includeExceptionDetailInFaults="true"/>
    </behavior>
  </endpointBehaviors>
</behaviors>

ClientViaBehavior 動作の使用Using the ClientViaBehavior Behavior

ClientViaBehavior 動作を使用して、トランスポート チャネルを作成する対象の URI (Uniform Resource Identifier) を指定できます。You can use the ClientViaBehavior behavior to specify the Uniform Resource Identifier for which the transport channel should be created. この動作は、直接のネットワーク送信先が、メッセージの処理先と異なる場合に使用します。Use this behavior when the immediate network destination is not the intended processor of the message. これにより、呼び出し側のアプリケーションが最終的な送信先を知っているとは限らないとき、または送信先の Via ヘッダーがアドレスでないときに、複数のホップを経由するメッセージ交換が可能になります。This enables multiple-hop conversations when the calling application does not necessarily know the ultimate destination or when the destination Via header is not an address.

関連項目See also