Wcf

Windows Communication Foundation

Trigger On

• working on WCF services, bindings, or clients
• deciding whether a service should stay WCF or move to modern HTTP APIs
• reviewing transport, security, or interoperability settings

Workflow

1. Use WCF where SOAP, WS-* features, or multi-transport service requirements are real; do not rewrite those needs into HTTP-only guidance by accident. 2. Keep contracts, bindings, behaviors, and hosting configuration explicit because WCF complexity compounds through configuration indirection. 3. For new REST-style services, prefer modern ASP.NET Core APIs instead of extending WCF into a shape it is no longer best suited for. 4. Plan migrations per endpoint and capability: transport, security model, transaction requirements, metadata, and client compatibility. 5. Validate interoperability and deployment assumptions with the actual client ecosystem, not only local service startup. 6. When WCF coexists with ASP.NET, be explicit about which runtime behaviors are shared and which are not.

Deliver

• stable WCF service or client configuration
• realistic migration guidance to newer stacks where appropriate
• clear contract and binding ownership

Validate

• WCF is used for a reason the modern stack does not replace directly
• binding and security behavior are explicit
• interop is verified with real consumers

References

• migration.md - WCF to gRPC/REST/CoreWCF migration paths, decision framework, and endpoint-by-endpoint migration strategy
• patterns.md - WCF maintenance patterns for configuration, contracts, hosting, security, diagnostics, and client proxy management

WCF Migration Paths

This document covers migration strategies from WCF to modern .NET alternatives.

Migration Decision Framework

When to Migrate

• New feature development is blocked by .NET Framework dependencies
• Client ecosystem has moved to REST/gRPC
• WS-* features are no longer required by consumers
• Deployment targets require .NET 6+ or containerization
• Security requirements exceed WCF's maintenance window

When to Stay on WCF

• Active WS-Security, WS-ReliableMessaging, or WS-Transaction requirements
• Enterprise clients require WSDL-based contract discovery
• Named pipes or MSMQ transport dependencies with no equivalent
• Stable production system with no business driver for change

Migration Target Selection

gRPC Migration Path

Best for:

• High-performance internal service-to-service communication
• Streaming scenarios (client, server, or bidirectional)
• Strong contract-first development with .proto files
• Polyglot environments requiring cross-language interop

Migration steps: 1. Map WCF [DataContract] types to Protocol Buffer messages 2. Convert [ServiceContract] interfaces to gRPC service definitions 3. Replace [OperationContract] methods with gRPC rpc definitions 4. Migrate request-reply patterns to unary calls 5. Convert duplex contracts to bidirectional streaming 6. Update client proxies from ChannelFactory<T> to generated gRPC clients 7. Replace WCF behaviors with gRPC interceptors

Contract mapping:

WCF                          gRPC
---                          ----
[ServiceContract]       ->   service
[OperationContract]     ->   rpc
[DataContract]          ->   message
[DataMember]            ->   field
[FaultContract]         ->   Status + error details

REST/ASP.NET Core Migration Path

Best for:

• Public APIs with HTTP client expectations
• Browser-based consumers
• OpenAPI/Swagger documentation requirements
• Simple request-response patterns
• Teams familiar with MVC/Web API patterns

Migration steps: 1. Create ASP.NET Core Web API project 2. Map [ServiceContract] to controller classes 3. Convert [OperationContract] to action methods with HTTP verbs 4. Replace [DataContract] with POCOs or record types 5. Map WCF faults to HTTP status codes and problem details 6. Replace WSDL with OpenAPI specification 7. Update clients from WCF proxies to HttpClient or typed clients

HTTP verb mapping:

WCF Pattern                  HTTP Verb
-----------                  ---------
GetXxx operations       ->   GET
CreateXxx operations    ->   POST
UpdateXxx operations    ->   PUT/PATCH
DeleteXxx operations    ->   DELETE

CoreWCF Migration Path

Best for:

• Minimal code changes required
• Existing SOAP clients cannot be updated
• WS-* features still needed but .NET 6+ hosting required
• Bridge strategy during longer migration timelines

Migration steps: 1. Add CoreWCF NuGet packages to new .NET project 2. Copy service contracts and implementations 3. Update binding configurations to CoreWCF equivalents 4. Configure ASP.NET Core hosting for CoreWCF services 5. Test with existing SOAP clients 6. Gradually migrate endpoints to REST/gRPC as clients update

Supported bindings in CoreWCF:

• BasicHttpBinding
• NetTcpBinding
• WSHttpBinding (partial)
• NetHttpBinding
• WebHttpBinding

Endpoint-by-Endpoint Migration

Large WCF services should migrate incrementally:

1. Inventory phase

• List all endpoints with their bindings and contracts
• Identify client dependencies per endpoint
• Document WS-* feature usage per operation
• Assess security requirements per endpoint

2. Categorization phase

• Green: Simple request-reply, no WS-* features (migrate first)
• Yellow: Complex contracts but no hard WCF dependencies
• Red: Active WS-* requirements or inflexible clients

3. Parallel operation phase

• Run WCF and new endpoints simultaneously
• Route clients to new endpoints as they update
• Monitor both stacks during transition

4. Decommission phase

• Remove WCF endpoints when all clients have migrated
• Archive WCF configuration for reference
• Update documentation and runbooks

Security Model Migration

WCF to ASP.NET Core Security

WCF Security                 ASP.NET Core
------------                 ------------
Transport security      ->   HTTPS + TLS
Message security        ->   JWTs or API keys in headers
Windows auth            ->   Negotiate/NTLM middleware
Certificate auth        ->   Client certificate middleware
Username/password       ->   Basic auth or OAuth2 resource owner
WS-Federation           ->   OpenID Connect

WCF to gRPC Security

WCF Security                 gRPC
------------                 ----
Transport security      ->   TLS channel credentials
Windows auth            ->   Negotiate interceptor
Certificate auth        ->   SSL credentials with client cert
Token-based             ->   Metadata credentials (call/channel)

Transaction Migration

WCF [TransactionFlow] has no direct equivalent in gRPC or REST.

Options:

• Saga pattern for distributed transactions
• Outbox pattern for reliable messaging
• Idempotency keys for retry safety
• Eventual consistency with compensation logic

Client Migration Checklist

• [ ] Identify all WCF client applications
• [ ] Assess client update feasibility and timeline
• [ ] Generate new client code (gRPC protos, OpenAPI, HttpClient)
• [ ] Update authentication/authorization flows
• [ ] Test error handling and fault scenarios
• [ ] Validate timeout and retry behaviors
• [ ] Update monitoring and diagnostics
• [ ] Plan rollback procedures

WCF Maintenance Patterns

This document covers patterns for maintaining and operating WCF services on .NET Framework.

Configuration Management

Binding Configuration Best Practices

Keep bindings explicit rather than relying on defaults:

<bindings>
  <basicHttpBinding>
    <binding name="SecureBasicHttp"
             maxReceivedMessageSize="10485760"
             receiveTimeout="00:10:00"
             sendTimeout="00:01:00">
      <security mode="Transport">
        <transport clientCredentialType="None" />
      </security>
    </binding>
  </basicHttpBinding>
</bindings>

Common pitfalls:

• Default maxReceivedMessageSize (65536) causes failures on large payloads
• Default timeouts may be too short for slow operations
• Unnamed bindings create implicit defaults that are hard to trace

Service Behavior Configuration

<behaviors>
  <serviceBehaviors>
    <behavior name="StandardServiceBehavior">
      <serviceMetadata httpGetEnabled="true" httpsGetEnabled="true" />
      <serviceDebug includeExceptionDetailInFaults="false" />
      <serviceThrottling maxConcurrentCalls="100"
                         maxConcurrentInstances="100"
                         maxConcurrentSessions="100" />
    </behavior>
  </serviceBehaviors>
</behaviors>

Production rules:

• Always set includeExceptionDetailInFaults="false" in production
• Configure throttling based on measured capacity
• Disable metadata endpoints in production if not required

Endpoint Configuration

<services>
  <service name="MyNamespace.MyService" behaviorConfiguration="StandardServiceBehavior">
    <endpoint address=""
              binding="basicHttpBinding"
              bindingConfiguration="SecureBasicHttp"
              contract="MyNamespace.IMyService" />
    <endpoint address="mex"
              binding="mexHttpsBinding"
              contract="IMetadataExchange" />
  </service>
</services>

Contract Design Patterns

Versioning Contracts

Use explicit namespaces and version indicators:

[ServiceContract(Namespace = "http://example.com/services/v2")]
public interface IOrderServiceV2
{
    [OperationContract]
    OrderResponseV2 PlaceOrder(OrderRequestV2 request);
}

[DataContract(Namespace = "http://example.com/data/v2")]
public class OrderRequestV2
{
    [DataMember(Order = 1)]
    public string CustomerId { get; set; }

    [DataMember(Order = 2, IsRequired = false)]
    public string NewFieldInV2 { get; set; }
}

Versioning strategies:

• Add new fields as optional (IsRequired = false)
• Use Order attribute for deterministic serialization
• Maintain parallel endpoints for breaking changes
• Document version lifecycle and deprecation schedule

Fault Contract Patterns

Define explicit faults instead of relying on generic exceptions:

[ServiceContract]
public interface IOrderService
{
    [OperationContract]
    [FaultContract(typeof(ValidationFault))]
    [FaultContract(typeof(NotFoundFault))]
    OrderResponse GetOrder(string orderId);
}

[DataContract]
public class ValidationFault
{
    [DataMember]
    public string Field { get; set; }

    [DataMember]
    public string Message { get; set; }
}

Fault handling on client:

try
{
    var response = client.GetOrder(orderId);
}
catch (FaultException<ValidationFault> ex)
{
    // Handle validation error
}
catch (FaultException<NotFoundFault> ex)
{
    // Handle not found
}
catch (FaultException ex)
{
    // Handle unexpected service fault
}
catch (CommunicationException ex)
{
    // Handle communication failure
}

Hosting Patterns

IIS Hosting

Standard .svc file approach:

<%@ ServiceHost Language="C#" Service="MyNamespace.MyService" %>

With factory for advanced scenarios:

<%@ ServiceHost Language="C#"
    Service="MyNamespace.MyService"
    Factory="MyNamespace.CustomServiceHostFactory" %>

IIS configuration in web.config:

• Configure app pool recycling to minimize service disruption
• Set idle timeout based on service usage patterns
• Enable WCF tracing in staging but not production

Self-Hosting

using (var host = new ServiceHost(typeof(MyService)))
{
    host.Open();
    Console.WriteLine("Service running. Press Enter to stop.");
    Console.ReadLine();
    host.Close();
}

Production considerations:

• Implement graceful shutdown handling
• Configure Windows Service wrapper for reliability
• Handle Faulted state and restart logic

Windows Service Hosting

public class MyServiceHost : ServiceBase
{
    private ServiceHost _serviceHost;

    protected override void OnStart(string[] args)
    {
        _serviceHost = new ServiceHost(typeof(MyService));
        _serviceHost.Open();
    }

    protected override void OnStop()
    {
        _serviceHost?.Close();
    }
}

Security Patterns

Transport Security with Certificates

<bindings>
  <netTcpBinding>
    <binding name="SecureNetTcp">
      <security mode="Transport">
        <transport clientCredentialType="Certificate" />
      </security>
    </binding>
  </netTcpBinding>
</bindings>

Certificate management:

• Store certificates in Windows Certificate Store, not file system
• Use certificate thumbprints in configuration
• Implement certificate rotation procedures
• Monitor certificate expiration

Message Security

<bindings>
  <wsHttpBinding>
    <binding name="SecureWsHttp">
      <security mode="Message">
        <message clientCredentialType="Certificate"
                 negotiateServiceCredential="false"
                 establishSecurityContext="false" />
      </security>
    </binding>
  </wsHttpBinding>
</bindings>

Custom Authorization

public class CustomAuthorizationPolicy : IAuthorizationPolicy
{
    public bool Evaluate(EvaluationContext context, ref object state)
    {
        // Custom authorization logic
        var identity = GetIdentityFromContext(context);
        var claims = BuildClaimsForIdentity(identity);
        context.AddClaimSet(this, new DefaultClaimSet(claims));
        return true;
    }
}

Diagnostics and Monitoring

WCF Tracing

Enable tracing for troubleshooting:

<system.diagnostics>
  <sources>
    <source name="System.ServiceModel" switchValue="Warning,ActivityTracing">
      <listeners>
        <add name="traceListener"
             type="System.Diagnostics.XmlWriterTraceListener"
             initializeData="c:\logs\wcf-traces.svclog" />
      </listeners>
    </source>
  </sources>
</system.diagnostics>

Trace levels:

• Off: Production default
• Warning: Production troubleshooting
• Information: Staging
• Verbose: Development only (high overhead)

Message Logging

<system.serviceModel>
  <diagnostics>
    <messageLogging logEntireMessage="true"
                    logMalformedMessages="true"
                    logMessagesAtServiceLevel="true"
                    logMessagesAtTransportLevel="false" />
  </diagnostics>
</system.serviceModel>

Security warning: Message logs may contain sensitive data. Encrypt or mask before storing.

Performance Counters

Enable WCF performance counters:

<system.serviceModel>
  <diagnostics performanceCounters="All" />
</system.serviceModel>

Key counters to monitor:

• Calls per second
• Calls outstanding
• Calls failed
• Calls faulted
• Instances created per second

Reliability Patterns

Reliable Sessions

<bindings>
  <wsHttpBinding>
    <binding name="ReliableBinding">
      <reliableSession enabled="true" ordered="true" />
    </binding>
  </wsHttpBinding>
</bindings>

Use when:

• Message ordering is required
• Network reliability is questionable
• Exactly-once delivery semantics are needed

Instance Management

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerCall)]
public class StatelessService : IMyService
{
    // New instance per call - best for scalability
}

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]
public class SessionService : IMyService
{
    // Instance per session - state across calls
}

[ServiceBehavior(InstanceContextMode = InstanceContextMode.Single)]
public class SingletonService : IMyService
{
    // Single instance - use with caution
}

Concurrency Management

[ServiceBehavior(
    InstanceContextMode = InstanceContextMode.Single,
    ConcurrencyMode = ConcurrencyMode.Multiple)]
public class ThreadSafeService : IMyService
{
    private readonly object _lock = new object();

    public void Operation()
    {
        lock (_lock)
        {
            // Thread-safe operation
        }
    }
}

Error Handling Patterns

Global Error Handler

public class GlobalErrorHandler : IErrorHandler
{
    public bool HandleError(Exception error)
    {
        // Log error
        Logger.LogException(error);
        return false; // Do not suppress
    }

    public void ProvideFault(Exception error, MessageVersion version,
                             ref Message fault)
    {
        var faultException = new FaultException<ServiceFault>(
            new ServiceFault { Message = "An error occurred" },
            new FaultReason("Service Error"));

        var msgFault = faultException.CreateMessageFault();
        fault = Message.CreateMessage(version, msgFault, faultException.Action);
    }
}

Register via behavior:

public class ErrorHandlerBehavior : IServiceBehavior
{
    public void ApplyDispatchBehavior(ServiceDescription description,
                                      ServiceHostBase host)
    {
        foreach (ChannelDispatcher dispatcher in host.ChannelDispatchers)
        {
            dispatcher.ErrorHandlers.Add(new GlobalErrorHandler());
        }
    }
}

Client Proxy Patterns

Proper Client Lifecycle

public class ServiceClientWrapper : IDisposable
{
    private readonly MyServiceClient _client;

    public ServiceClientWrapper()
    {
        _client = new MyServiceClient();
    }

    public void CallService()
    {
        try
        {
            _client.Operation();
        }
        catch (FaultException)
        {
            _client.Abort();
            throw;
        }
        catch (CommunicationException)
        {
            _client.Abort();
            throw;
        }
        catch (TimeoutException)
        {
            _client.Abort();
            throw;
        }
    }

    public void Dispose()
    {
        try
        {
            if (_client.State == CommunicationState.Faulted)
            {
                _client.Abort();
            }
            else
            {
                _client.Close();
            }
        }
        catch
        {
            _client.Abort();
        }
    }
}

Channel Factory Pattern

public class ServiceChannelFactory<TChannel> : IDisposable
{
    private readonly ChannelFactory<TChannel> _factory;

    public ServiceChannelFactory(string endpointName)
    {
        _factory = new ChannelFactory<TChannel>(endpointName);
    }

    public TChannel CreateChannel()
    {
        return _factory.CreateChannel();
    }

    public void Dispose()
    {
        try
        {
            _factory.Close();
        }
        catch
        {
            _factory.Abort();
        }
    }
}

Interoperability Patterns

WCF to Java/.NET Interop

[ServiceContract(Namespace = "http://example.com/services")]
public interface IInteropService
{
    [OperationContract]
    [XmlSerializerFormat] // Better interop than DataContractSerializer
    InteropResponse Process(InteropRequest request);
}

Use XmlSerializerFormat when:

• Interoperating with non-.NET SOAP clients
• Schema compatibility is critical
• Complex XML structures required

MTOM for Large Binary Data

<bindings>
  <basicHttpBinding>
    <binding name="MtomBinding" messageEncoding="Mtom">
      <security mode="Transport" />
    </binding>
  </basicHttpBinding>
</bindings>

Use MTOM when transferring binary data larger than 1KB to reduce base64 encoding overhead.