A Comprehensive Guide to Calling SOAP Services in .NET Core: Solutions from Migration to Authentication

Introduction

With the rise of .NET Core, many developers are migrating legacy .NET Framework applications to this cross-platform framework. During migration, calling SOAP services often becomes a technical hurdle, especially when involving WCF (Windows Communication Foundation) and complex security configurations. Based on a real-world case, this article analyzes HTTP response errors and authentication issues encountered when migrating from .NET 4.6.2 to .NET Core for SOAP service calls, offering validated solutions.

Problem Background and Error Analysis

In the original scenario, a developer attempted to migrate code from .NET 4.6.2 to a .NET Core project that calls a SOAP service. The initial code used BasicHttpsBinding with BasicHttpsSecurityMode.Transport, but it threw an exception: "An error occurred while receiving the HTTP response... This could be due to the service endpoint binding not using the HTTP protocol." Server-side error revelation indicated the root cause was authentication failure: "The HTTP request is unauthorized with client authentication scheme 'Basic'."

Comparing with the old configuration, key differences were found in binding settings. The old config used basicHttpsBinding with explicit security mode="Transport" and transport clientCredentialType="Basic", whereas the initial migration code only set BasicHttpsSecurityMode.Transport without properly handling client credential types, leading to mismatched authentication headers.

Core Concepts: Binding and Security Configuration

In WCF, bindings define communication protocols, encoding, and transport details between services and clients. For HTTPS transport, BasicHttpBinding or BasicHttpsBinding are commonly used. In .NET Core's WCF implementation, BasicHttpBinding supports BasicHttpSecurityMode.Transport to enable SSL/TLS, and client credential types must be set via the Security.Transport.ClientCredentialType property, e.g., HttpClientCredentialType.Basic for basic authentication.

An example of incorrect configuration is:

var binding = new BasicHttpsBinding(BasicHttpsSecurityMode.Transport);
// Missing client credential type setting causes authentication failure
binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic; // Must be explicitly set

Correct configuration should align the binding with the server's expected authentication scheme. The server's authentication header 'Basic realm="Integration Server"' indicates a need for basic authentication, so the client must provide valid username and password credentials.

Solution: Using the New WCF Syntax in .NET Core

Based on the best answer, we recommend using ChannelFactory and OperationContextScope to call SOAP services. Here is a complete code example:

BasicHttpBinding basicHttpBinding = null;
EndpointAddress endpointAddress = null;
ChannelFactory<IAService> factory = null;
IAService serviceProxy = null;

try
{
    basicHttpBinding = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
    basicHttpBinding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
    endpointAddress = new EndpointAddress(new Uri("https://someurl.com/ws/TheEndpoint.pub.ws:AService"));
    factory = new ChannelFactory<IAService>(basicHttpBinding, endpointAddress);

    factory.Credentials.UserName.UserName = "usrn";
    factory.Credentials.UserName.Password = "passw";
    serviceProxy = factory.CreateChannel();

    using (var scope = new OperationContextScope((IContextChannel)serviceProxy))
    {
        var result = await serviceProxy.getSomethingAsync("id").ConfigureAwait(false);
    }

    factory.Close();
    ((ICommunicationObject)serviceProxy).Close();
}
catch (MessageSecurityException ex)
{
    throw;
}
catch (Exception ex)
{
    throw;
}
finally
{
    CloseCommunicationObjects((ICommunicationObject)serviceProxy, factory);
}

This code ensures proper binding configuration for transport security and basic authentication, and manages operation context via OperationContextScope to prevent resource leaks.

Handling OperationContextScope Exceptions

In practice, using OperationContextScope might cause an exception: "This OperationContextScope is being disposed out of order." This is due to a known issue in .NET Core's WCF implementation. As a workaround, manually manage OperationContext:

basicHttpBinding = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
basicHttpBinding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;

factory = new ChannelFactory<IAService_PortType>(basicHttpBinding, new EndpointAddress(new Uri("https://someurl.com/ws/TheEndpoint.pub.ws:AService")));
factory.Credentials.UserName.UserName = "usern";
factory.Credentials.UserName.Password = "passw";
serviceProxy = factory.CreateChannel();
((ICommunicationObject)serviceProxy).Open();
var opContext = new OperationContext((IClientChannel)serviceProxy);
var prevOpContext = OperationContext.Current;
OperationContext.Current = opContext;

try
{
    var result = await serviceProxy.getSomethingAsync("id").ConfigureAwait(false);
    factory.Close();
    ((ICommunicationObject)serviceProxy).Close();
}
finally
{
    CloseCommunicationObjects((ICommunicationObject)serviceProxy, factory);
    OperationContext.Current = prevOpContext;
}

This method explicitly sets and restores the operation context, avoiding disposal order issues, but requires attention to thread safety and context management.

Debugging and Server-Side Authentication

When encountering authentication errors such as 'Anonymous' instead of 'Basic', check client credential settings and server configurations. Ensure:

1. Binding configuration matches the server's expected authentication scheme (e.g., HttpClientCredentialType.Basic).
2. Credentials (username and password) are correct and accepted by the server for basic authentication.
3. Use tools like Fiddler or Wireshark to capture HTTP requests and verify that authentication headers include correct Authorization: Basic <credentials>.

If issues persist, contact server administrators to confirm authentication settings or refer to server logs for detailed error information.

Resources and Further Learning

To deepen understanding of WCF implementation in .NET Core, consider these resources:

• WCF .NET Core GitHub Repository: Access the latest code and documentation.
• BasicHttpBinding Test Cases: Learn best practices for binding configuration.
• ClientCredentialType Test Cases: Explore implementation details for different authentication types.

These resources offer abundant examples to help developers resolve similar migration challenges.

Conclusion

Calling SOAP services when migrating to .NET Core requires careful handling of binding and authentication configurations. By using BasicHttpBinding with correct security settings, combined with ChannelFactory and proper context management, HTTP response and authentication errors can be effectively resolved. The solutions provided in this article, based on real-world cases, emphasize the importance of debugging and resource utilization, aiding developers in successful migration tasks. As WCF .NET Core continues to evolve, monitor official updates for more stable API support.