# 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:

```xml
<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

```xml
<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

```xml
<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:

```csharp
[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:

```csharp
[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:

```csharp
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

```csharp
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

```csharp
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

```xml
<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

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

### Custom Authorization

```csharp
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:

```xml
<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

```xml
<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:

```xml
<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

```xml
<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

```csharp
[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

```csharp
[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

```csharp
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:

```csharp
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

```csharp
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

```csharp
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

```csharp
[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

```xml
<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.