Specifying Service Run-Time Behavior
Once you have designed a service contract (Designing Service Contracts) and implemented your service contract (Implementing Service Contracts) you can configure the operation behavior of the service runtime. This topic discusses system-provided service and operation behaviors and describes where to find more information to create new behaviors. While some behaviors are applied as attributes, many are applied using an application configuration file or programmatically. For more information about configuring your service application, see Configuring Services.
Overview
The contract defines the inputs, outputs, data types, and capabilities of a service of that type. Implementing a service contract creates a class that, when configured with a binding at an address, fulfills the contract it implements. Contractual, binding, and address information are all known by the client; without them, the client cannot make use of the service.
However, operation specifics, such as threading issues or instance management, are opaque to clients. Once you have implemented your service contract, you can configure a large number of operation characteristics by using behaviors. Behaviors are objects that modify the Windows Communication Foundation (WCF) runtime by either setting a runtime property or by inserting a customization type into the runtime. For more information about modifying the runtime by creating user-defined behaviors, see Extending ServiceHost and the Service Model Layer.
The System.ServiceModel.ServiceBehaviorAttribute and System.ServiceModel.OperationBehaviorAttribute attributes are the most widely useful behaviors and expose the most commonly requested operation features. Because they are attributes, you apply them to the service or operation implementation. Other behaviors, such as the System.ServiceModel.Description.ServiceMetadataBehavior or System.ServiceModel.Description.ServiceDebugBehavior, are typically applied using an application configuration file, although you can use them programmatically.
This topic provides an overview of the ServiceBehaviorAttribute and OperationBehaviorAttribute attributes, describes the various scopes at which behaviors can operate, and provides a quick description of many of the system-provided behaviors at the various scopes that may be of interest to WCF developers.
ServiceBehaviorAttribute and OperationBehaviorAttribute
The most important behaviors are the ServiceBehaviorAttribute and OperationBehaviorAttribute attributes, which you can use to control:
Instance lifetimes
Concurrency and synchronization support
Configuration behavior
Transaction behavior
Serialization behavior
Metadata transformation
Session lifetime
Address filtering and header processing
Impersonation
To use these attributes, mark the service or operation implementation with the attribute appropriate to that scope and set the properties. For example, the following code example shows an operation implementation that uses the System.ServiceModel.OperationBehaviorAttribute.Impersonation property to require that callers of this operation support impersonation.
Imports System.ServiceModel
Imports System.Threading
Namespace Microsoft.WCF.Documentation
<ServiceContract(Name:="SampleHello", Namespace:="http://microsoft.wcf.documentation")> _
Public Interface IHello
<OperationContract> _
Function Hello(ByVal greeting As String) As String
End Interface
Public Class HelloService
Implements IHello
Public Sub New()
Console.WriteLine("Service object created: " & Me.GetHashCode().ToString())
End Sub
Protected Overrides Sub Finalize()
Console.WriteLine("Service object destroyed: " & Me.GetHashCode().ToString())
End Sub
<OperationBehavior(Impersonation:=ImpersonationOption.Required)> _
Public Function Hello(ByVal greeting As String) As String Implements IHello.Hello
Console.WriteLine("Called by: " & Thread.CurrentPrincipal.Identity.Name)
Console.WriteLine("IsAuthenticated: " & Thread.CurrentPrincipal.Identity.IsAuthenticated.ToString())
Console.WriteLine("AuthenticationType: " & Thread.CurrentPrincipal.Identity.AuthenticationType.ToString())
Console.WriteLine("Caller sent: " & greeting)
Console.WriteLine("Sending back: Hi, " & Thread.CurrentPrincipal.Identity.Name)
Return "Hi, " & Thread.CurrentPrincipal.Identity.Name
End Function
End Class
End Namespace
using System;
using System.Collections.Generic;
using System.ServiceModel;
using System.Threading;
namespace Microsoft.WCF.Documentation
{
[ServiceContract(
Name="SampleHello",
Namespace="http://microsoft.wcf.documentation"
)]
public interface IHello
{
[OperationContract]
string Hello(string greeting);
}
public class HelloService : IHello
{
public HelloService()
{
Console.WriteLine("Service object created: " + this.GetHashCode().ToString());
}
~HelloService()
{
Console.WriteLine("Service object destroyed: " + this.GetHashCode().ToString());
}
[OperationBehavior(Impersonation=ImpersonationOption.Required)]
public string Hello(string greeting)
{
Console.WriteLine("Called by: " + Thread.CurrentPrincipal.Identity.Name);
Console.WriteLine("IsAuthenticated: " + Thread.CurrentPrincipal.Identity.IsAuthenticated.ToString());
Console.WriteLine("AuthenticationType: " + Thread.CurrentPrincipal.Identity.AuthenticationType.ToString());
Console.WriteLine("Caller sent: " + greeting);
Console.WriteLine("Sending back: Hi, " + Thread.CurrentPrincipal.Identity.Name);
return "Hi, " + Thread.CurrentPrincipal.Identity.Name;
}
}
}
Many of the properties require additional support from the binding. For example, an operation that requires a transaction from the client must be configured to use a binding that supports flowed transactions.
Well-Known Singleton Services
You can use the ServiceBehaviorAttribute and OperationBehaviorAttribute attributes to control certain lifetimes, both of the InstanceContext and of the service objects that implement the operations.
For example, the System.ServiceModel.ServiceBehaviorAttribute.InstanceContextMode property controls how often the InstanceContext is released, and the System.ServiceModel.OperationBehaviorAttribute.ReleaseInstanceMode and System.ServiceModel.ServiceBehaviorAttribute.ReleaseServiceInstanceOnTransactionComplete properties control when the service object is released.
However, you can also create a service object yourself and create the service host using that object. To do so, you must also set the System.ServiceModel.ServiceBehaviorAttribute.InstanceContextMode property to Single or an exception is thrown when the service host is opened.
Use the System.ServiceModel.ServiceHost.#ctor(System.Object,System.Uri[]) constructor to create such a service. It provides an alternative to implementing a custom System.ServiceModel.Dispatcher.IInstanceContextInitializer when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a default public constructor that has no parameters).
Note that when an object is provided to this constructor, some features related to the Windows Communication Foundation (WCF) instancing behavior work differently. For example, calling System.ServiceModel.InstanceContext.ReleaseServiceInstance has no effect when a well-known object instance is provided. Similarly, any other instance release mechanism is ignored. The ServiceHost class always behaves as if the System.ServiceModel.OperationBehaviorAttribute.ReleaseInstanceMode property is set to System.ServiceModel.ReleaseInstanceMode.None for all operations.
Other Service, Endpoint, Contract, and Operation Behaviors
Service behaviors, such as the ServiceBehaviorAttribute attribute, operate across an entire service. For example, if you set the System.ServiceModel.ServiceBehaviorAttribute.ConcurrencyMode property to System.ServiceModel.ConcurrencyMode.Multiple you must handle thread synchronization issues inside each operation in that service yourself. Endpoint behaviors operate across an endpoint; many of the system-provided endpoint behaviors are for client functionality. Contract behaviors operate at the contract level, and operation behaviors modify operation delivery.
Many of these behaviors are implemented on attributes, and you make use of them as you do the ServiceBehaviorAttribute and OperationBehaviorAttribute attributes—by applying them to the appropriate service class or operation implementation. Other behaviors, such as the ServiceMetadataBehavior or ServiceDebugBehavior objects, are typically applied using an application configuration file, although they can also be used programmatically.
For example, the publication of metadata is configured by using the ServiceMetadataBehavior object. The following application configuration file shows the most common usage.
<configuration>
<system.serviceModel>
<services>
<service
name="Microsoft.WCF.Documentation.SampleService"
behaviorConfiguration="metadataSupport"
>
<host>
<baseAddresses>
<add baseAddress="https://localhost:8080/ServiceMetadata" />
</baseAddresses>
</host>
<endpoint
address="/SampleService"
binding="wsHttpBinding"
contract="Microsoft.WCF.Documentation.ISampleService"
/>
<!-- Adds a WS-MetadataExchange endpoint at -->
<!-- "https://localhost:8080/ServiceMetadata/mex" -->
<endpoint
address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange"
/>
</service>
</services>
<behaviors>
<serviceBehaviors>
<behavior name="metadataSupport">
<!-- Enables the IMetadataExchange endpoint in services that -->
<!-- use "metadataSupport" in their behaviorConfiguration attribute. -->
<!-- In addition, the httpGetEnabled and httpGetUrl attributes publish -->
<!-- Service metadata for retrieval by HTTP/GET at the address -->
<!-- "https://localhost:8080/ServiceMetadata?wsdl" -->
<serviceMetadata httpGetEnabled="true" httpGetUrl=""/>
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>
<configuration>
<system.serviceModel>
<services>
<service
name="Microsoft.WCF.Documentation.SampleService"
behaviorConfiguration="metadataSupport"
>
<host>
<baseAddresses>
<add baseAddress="https://localhost:8080/SampleService" />
</baseAddresses>
</host>
<endpoint
address=""
binding="wsHttpBinding"
contract="Microsoft.WCF.Documentation.ISampleService"
/>
<!-- Adds a WS-MetadataExchange endpoint at -->
<!-- "https://localhost:8080/SampleService/mex" -->
<endpoint
address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange"
/>
</service>
</services>
<behaviors>
<serviceBehaviors>
<behavior name="metadataSupport">
<!-- Enables the IMetadataExchange endpoint in services that -->
<!-- use "metadataSupport" in their behaviorConfiguration attribute. -->
<!-- In addition, the httpGetEnabled and httpGetUrl attributes publish -->
<!-- Service metadata for retrieval by HTTP/GET at the address -->
<!-- "https://localhost:8080/SampleService?wsdl" -->
<serviceMetadata httpGetEnabled="true" httpGetUrl=""/>
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>
<configuration>
<system.serviceModel>
<services>
<service
name="Microsoft.WCF.Documentation.SampleService"
behaviorConfiguration="metadataSupport"
>
<host>
<baseAddresses>
<add baseAddress="https://localhost:8080/SampleService" />
</baseAddresses>
</host>
<endpoint
address=""
binding="wsHttpBinding"
contract="Microsoft.WCF.Documentation.ISampleService"
/>
<!-- Adds a WS-MetadataExchange endpoint at -->
<!-- "https://localhost:8080/SampleService/mex" -->
<endpoint
address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange"
/>
</service>
</services>
<behaviors>
<serviceBehaviors>
<behavior name="metadataSupport">
<!-- Enables the IMetadataExchange endpoint in services that -->
<!-- use "metadataSupport" in their behaviorConfiguration attribute. -->
<!-- In addition, the httpGetEnabled and httpGetUrl attributes publish -->
<!-- Service metadata for retrieval by HTTP/GET at the address -->
<!-- "https://localhost:8080/SampleService?wsdl" -->
<serviceMetadata httpGetEnabled="true" httpGetUrl=""/>
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>
<configuration>
<system.serviceModel>
<services>
<service
name="Microsoft.WCF.Documentation.SampleService"
behaviorConfiguration="metadataSupport"
>
<host>
<baseAddresses>
<add baseAddress="https://localhost:8080/SampleService" />
</baseAddresses>
</host>
<endpoint
address=""
binding="wsHttpBinding"
contract="Microsoft.WCF.Documentation.ISampleService"
/>
<!-- Adds a WS-MetadataExchange endpoint at -->
<!-- "https://localhost:8080/SampleService/mex" -->
<endpoint
address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange"
/>
</service>
</services>
<behaviors>
<serviceBehaviors>
<behavior name="metadataSupport">
<!-- Enables the IMetadataExchange endpoint in services that -->
<!-- use "metadataSupport" in their behaviorConfiguration attribute. -->
<!-- In addition, the httpGetEnabled and httpGetUrl attributes publish -->
<!-- Service metadata for retrieval by HTTP/GET at the address -->
<!-- "https://localhost:8080/SampleService?wsdl" -->
<serviceMetadata httpGetEnabled="true" httpGetUrl=""/>
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>
<configuration>
<system.serviceModel>
<services>
<service
name="Microsoft.WCF.Documentation.SampleService"
behaviorConfiguration="metadataSupport"
>
<host>
<baseAddresses>
<add baseAddress="https://localhost:8080/SampleService" />
</baseAddresses>
</host>
<endpoint
address=""
binding="wsHttpBinding"
contract="Microsoft.WCF.Documentation.ISampleService"
/>
<!-- Adds a WS-MetadataExchange endpoint at -->
<!-- "https://localhost:8080/SampleService/mex" -->
<endpoint
address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange"
/>
</service>
</services>
<behaviors>
<serviceBehaviors>
<behavior name="metadataSupport">
<!-- Enables the IMetadataExchange endpoint in services that -->
<!-- use "metadataSupport" in their behaviorConfiguration attribute. -->
<!-- In addition, the httpGetEnabled and httpGetUrl attributes publish -->
<!-- Service metadata for retrieval by HTTP/GET at the address -->
<!-- "https://localhost:8080/SampleService?wsdl" -->
<serviceMetadata httpGetEnabled="true" httpGetUrl=""/>
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>
The following sections describe many of the most useful system-provided behaviors that you can use to modify the runtime delivery of your service or client. See the reference topic to determine how to use each one.
Service Behaviors
The following behaviors operate on services.
AspNetCompatibilityRequirementsAttribute. Applied to a WCF service to indicate whether that service can be run in ASP.NET Compatibility Mode.
ServiceAuthorizationBehavior. Controls how the service authorizes client claims.
ServiceCredentials. Configures a service credential. Use this class to specify the credential for the service, such as an X.509 certificate.
ServiceDebugBehavior. Enables debugging and Help information features for a WCF service.
ServiceMetadataBehavior. Controls the publication of service metadata and associated information.
ServiceSecurityAuditBehavior. Specifies the audit behavior of security events.
ServiceThrottlingBehavior. Configures run-time throughput settings that enable you to tune service performance.
Endpoint Behaviors
The following behaviors operate on endpoints. Many of these behaviors are used in client applications.
CallbackBehaviorAttribute. Configures a callback service implementation in a duplex client application.
CallbackDebugBehavior. Enables service debugging for a WCF callback object.
ClientCredentials. Allows the user to configure client and service credentials as well as service credential authentication settings for use on the client.
ClientViaBehavior. Used by clients to specify the Uniform Resource Identifier (URI) for which the transport channel should be created.
MustUnderstandBehavior. Instructs WCF to disable the MustUnderstand processing.
SynchronousReceiveBehavior. Instructs the runtime to use a synchronous receive process for channels.
TransactedBatchingBehavior. Optimizes the receive operations for transports that support transactional receives.
Contract Behaviors
DeliveryRequirementsAttribute. Specifies the feature requirements that bindings must provide to the service or client implementation.
Operation Behaviors
The following operation behaviors specify serialization and transaction controls for operations.
DataContractSerializerOperationBehavior. Represents the run-time behavior of the System.Runtime.Serialization.DataContractSerializer.
XmlSerializerOperationBehavior. Controls run-time behavior of the XmlSerializer and associates it with an operation.
TransactionFlowAttribute. Specifies the level in which a service operation accepts a transaction header.
See Also
Tasks
How to: Control Service Instancing