ServiceBehaviorAttribute.InstanceContextMode Property

Definition

取得或設定值,這個值會指出何時建立新的服務物件。Gets or sets the value that indicates when new service objects are created.

public:
 property System::ServiceModel::InstanceContextMode InstanceContextMode { System::ServiceModel::InstanceContextMode get(); void set(System::ServiceModel::InstanceContextMode value); };
public System.ServiceModel.InstanceContextMode InstanceContextMode { get; set; }
member this.InstanceContextMode : System.ServiceModel.InstanceContextMode with get, set
Public Property InstanceContextMode As InstanceContextMode

Property Value

InstanceContextMode

其中一個 InstanceContextMode 值;預設值為 PerSessionOne of the InstanceContextMode values; the default value is PerSession.

Exceptions

該值不是其中一個 InstanceContextMode 值。The value is not one of the InstanceContextMode values.

Examples

下列程式碼範例會示範 ServiceBehaviorAttribute 屬性。The following code example demonstrates the ServiceBehaviorAttribute properties. BehaviorService 類別會使用 ServiceBehaviorAttribute 屬性指出:The BehaviorService class uses the ServiceBehaviorAttribute attribute to indicate that:

  • 實作方法會在 UI 執行緒上叫用。Implementation methods are invoked on the UI thread.

  • 每個工作階段都有一個服務物件。There is one service object for each session.

  • 該服務為單一執行緒服務,而且不支援可重新進入的呼叫。The service is single-threaded and does not support reentrant calls.

此外,位於作業層級的 OperationBehaviorAttribute 值表示 TxWork 方法會自動登記在流動異動中或建立新異動來執行工作,並且表示如果沒有發生未處理的例外狀況,則會自動認可這項異動。Furthermore, at the operation level, the OperationBehaviorAttribute values indicate that the TxWork method automatically enlists in flowed transactions or creates a new transaction to do the work, and that the transaction is committed automatically if an unhandled exception does not occur.

using System;
using System.ServiceModel;
using System.Transactions;

namespace Microsoft.WCF.Documentation
{
  [ServiceContract(
    Namespace="http://microsoft.wcf.documentation",
    SessionMode=SessionMode.Required
  )]
  public interface IBehaviorService
  {
    [OperationContract]
    string TxWork(string message);
  }

  // Note: To use the TransactionIsolationLevel property, you
  // must add a reference to the System.Transactions.dll assembly.
  /* The following service implementation:
   *   -- Processes messages on one thread at a time
   *   -- Creates one service object per session
   *   -- Releases the service object when the transaction commits
   */
  [ServiceBehavior(
    ConcurrencyMode=ConcurrencyMode.Single,
    InstanceContextMode=InstanceContextMode.PerSession,
    ReleaseServiceInstanceOnTransactionComplete=true
  )]
  public class BehaviorService : IBehaviorService, IDisposable
  {
    Guid myID;

    public BehaviorService()
    {
      myID = Guid.NewGuid();
      Console.WriteLine(
        "Object "
        + myID.ToString()
        + " created.");
    }

    /*
     * The following operation-level behaviors are specified:
     *   -- The executing transaction is committed when
     *        the operation completes without an
     *        unhandled exception
     *   -- Always executes under a flowed transaction.
     */
    [OperationBehavior(
      TransactionAutoComplete = true,
      TransactionScopeRequired = true
    )]
    [TransactionFlow(TransactionFlowOption.Mandatory)]
    public string TxWork(string message)
    {
      // Do some transactable work.
      Console.WriteLine("TxWork called with: " + message);
      // Display transaction information.

      TransactionInformation info = Transaction.Current.TransactionInformation;
      Console.WriteLine("The distributed tx ID: {0}.", info.DistributedIdentifier);
      Console.WriteLine("The tx status: {0}.", info.Status);
      return String.Format("Hello. This was object {0}.",myID.ToString()) ;
    }

    public void Dispose()
    {
      Console.WriteLine(
        "Service "
        + myID.ToString()
        + " is being recycled."
      );
    }
  }
}
Imports System.ServiceModel
Imports System.Transactions

Namespace Microsoft.WCF.Documentation
  <ServiceContract(Namespace:="http://microsoft.wcf.documentation", SessionMode:=SessionMode.Required)> _
  Public Interface IBehaviorService
    <OperationContract> _
    Function TxWork(ByVal message As String) As String
  End Interface

  ' Note: To use the TransactionIsolationLevel property, you 
  ' must add a reference to the System.Transactions.dll assembly.
'   The following service implementation:
'   *   -- Processes messages on one thread at a time
'   *   -- Creates one service object per session
'   *   -- Releases the service object when the transaction commits
'   
    <ServiceBehavior(ConcurrencyMode:=ConcurrencyMode.Single, InstanceContextMode:=InstanceContextMode.PerSession, _
                     ReleaseServiceInstanceOnTransactionComplete:=True)> _
    Public Class BehaviorService
        Implements IBehaviorService, IDisposable
        Private myID As Guid

        Public Sub New()
            myID = Guid.NewGuid()
            Console.WriteLine("Object " & myID.ToString() & " created.")
        End Sub

        '    
        '     * The following operation-level behaviors are specified:
        '     *   -- The executing transaction is committed when
        '     *        the operation completes without an 
        '     *        unhandled exception
        '     *   -- Always executes under a flowed transaction.
        '     
        <OperationBehavior(TransactionAutoComplete:=True, TransactionScopeRequired:=True), TransactionFlow(TransactionFlowOption.Mandatory)> _
        Public Function TxWork(ByVal message As String) As String Implements IBehaviorService.TxWork
            ' Do some transactable work.
            Console.WriteLine("TxWork called with: " & message)
            ' Display transaction information.

            Dim info As TransactionInformation = Transaction.Current.TransactionInformation
            Console.WriteLine("The distributed tx ID: {0}.", info.DistributedIdentifier)
            Console.WriteLine("The tx status: {0}.", info.Status)
            Return String.Format("Hello. This was object {0}.", myID.ToString())
        End Function

        Public Sub Dispose() Implements IDisposable.Dispose
            Console.WriteLine("Service " & myID.ToString() & " is being recycled.")
        End Sub
    End Class
End Namespace

基礎繫結程序必須支援流動異動,才能讓下列程式碼範例正確執行。The underlying binding must support flowed transactions for the following code example to execute properly. 例如,若要使用 WSHttpBinding 支援流動的交易,請透過程式碼或應用程式組態檔,將 TransactionFlow 屬性設定為 trueTo support flowed transactions using the WSHttpBinding, for example, set the TransactionFlow property to true in code or in an application configuration file. 下列程式碼範例會顯示先前範例的組態檔。The following code example shows the configuration file for the preceding sample.

<configuration>
  <system.serviceModel>
    <services>
      <service  
        name="Microsoft.WCF.Documentation.BehaviorService" 
        behaviorConfiguration="metadataAndDebugEnabled"
      >
        <host>
          <baseAddresses>
            <add baseAddress="http://localhost:8080/SampleService"/>
          </baseAddresses>
        </host>
        <!--
          Note:
            This example code uses the WSHttpBinding to support transactions using the 
            WS-AtomicTransactions (WS-AT) protocol. WSHttpBinding is configured to use the  
            protocol, but the protocol is not enabled on some computers. Use the xws_reg -wsat+ 
            command to enable the WS-AtomicTransactions protocol in the MSDTC service.          
          -->
        <endpoint 
           contract="Microsoft.WCF.Documentation.IBehaviorService"
           binding="wsHttpBinding"
           bindingConfiguration="wsHttpBindingWithTXFlow"
           address="http://localhost:8080/BehaviorService"
          />
        <endpoint 
           contract="Microsoft.WCF.Documentation.IBehaviorService"
           binding="netTcpBinding"
           bindingConfiguration="netTcpBindingWithTXFlow"
           address="net.tcp://localhost:8081/BehaviorService"
          />
        <endpoint
          address="mex"
          binding="mexHttpBinding"
          contract="IMetadataExchange"
        />
      </service>
    </services>
    <behaviors>
      <serviceBehaviors>
        <behavior name="metadataAndDebugEnabled">
          <serviceDebug
            includeExceptionDetailInFaults="true"
          />
          <serviceMetadata
            httpGetEnabled="true"
            httpGetUrl=""
          />
        </behavior>
      </serviceBehaviors>
    </behaviors>
    <!-- binding configuration - configures a WSHttpBinding to require transaction flow -->
    <bindings>
      <wsHttpBinding>
        <binding name="wsHttpBindingWithTXFlow" transactionFlow="true" />
      </wsHttpBinding>
      <netTcpBinding>
        <binding name="netTcpBindingWithTXFlow" transactionFlow="true" />
      </netTcpBinding>
    </bindings>
  </system.serviceModel>
</configuration>

Remarks

使用 InstanceContextMode 屬性,即可指定建立新服務物件的時機。Use the InstanceContextMode property to specify when new service objects are created. 由於服務物件不是直接連接至通訊通道,因此服務物件的存留期與用戶端和服務應用程式之間的通道的存留期無關。Because the service object is not directly connected to the communicating channel, the lifetime of the service objects is independent of the lifetime of the channel between a client and the service application. 預設值 PerSession,會在用戶端和服務應用程式之間建立新通訊工作階段時,指示服務應用程式建立新的服務物件。The default value, PerSession, instructs the service application to create a new service object when a new communication session is established between a client and the service application. 在相同工作階段中的後續呼叫會由相同物件處理。Subsequent calls in the same session are handled by the same object.

PerSession 表示每個服務物件都會處理來自一個用戶端通道的要求。PerSession indicates that each service object handles requests from one client channel.

Note

InstanceContextMode 屬性會與其他設定互動。The InstanceContextMode property interacts with some other settings. 例如,如果 InstanceContextMode 值是設定為 Single,這時除非您也將 ConcurrencyMode 值設定為 Multiple,否則您的服務一次只能處理一個訊息。For example, if the InstanceContextMode value is set to Single the result is that your service can only process one message at a time unless you also set the ConcurrencyMode value to Multiple. 這個屬性也會產生與 ServiceContractAttribute.SessionMode 屬性一起使用的行為。This property also produces behavior in combination with the ServiceContractAttribute.SessionMode property. 如需詳細資訊,請參閱會話、實例和並行For details, see Sessions, Instancing, and Concurrency.

對於單一存留期行為 (例如,如果主應用程式呼叫 ServiceHost 建構函式,並傳遞物件做為服務使用),服務類別必須將 InstanceContextMode 設定為 Single,否則會在執行階段擲回例外狀況。For singleton lifetime behavior (for example, if the host application calls the ServiceHost constructor and passes an object to use as the service), the service class must set InstanceContextMode to Single, or an exception is thrown at run time.

Applies to