How to create SOAP services in ASP.NET Core

The services that comprise distributed applications must communicate with one another to exchange data or information. You need a common data format for these communications, which narrows the options if your distributed applications span heterogeneous platforms. Earlier protocols such as DCOM, RPC, and IIOP were restricted to homogeneous environments.

For heterogeneous environments, we need a communications protocol that is supported across disparate platforms. This is where SOAP (Simple Object Access Protocol) comes in.

SOAP is a lightweight protocol that uses XML to facilitate data exchange between systems. With SOAP, objects developed on different platforms and in different programming languages can communicate seamlessly. Thus SOAP allows us to build complex information systems by integrating services from diverse systems as components.

This article introduces SOAP and shows how you can implement a simple SOAP service in an ASP.NET Core application. To do so, we’ll take advantage of SoapCore, a SOAP middleware package for ASP.NET Core.

To use the code examples provided in this article, you should have Visual Studio 2022 installed in your system. If you don’t already have a copy, you can download Visual Studio 2022 here.

Create an ASP.NET Core Web API project in Visual Studio 2022

To create an ASP.NET Core 7 Web API project in Visual Studio 2022, follow the steps outlined below.

1. Launch the Visual Studio 2022 IDE.
2. Click on “Create new project.”
3. In the “Create new project” window, select “ASP.NET Core Web API” from the list of templates displayed.
4. Click Next.
5. In the “Configure your new project” window, specify the name and location for the new project.
6. Optionally check the “Place solution and project in the same directory” check box, depending on your preferences.
7. Click Next.
8. In the “Additional Information” window shown next, leave the “Use controllers (uncheck to use minimal APIs)” box checked. We won’t be using minimal APIs in this project.
9. Elsewhere in the “Additional Information” window, leave the “Authentication Type” set to “None” (the default) and make sure the check boxes “Enable Open API Support,” “Configure for HTTPS,” and “Enable Docker” remain unchecked. We won’t be using any of those features here.
10. Click Create.

We’ll use this ASP.NET Core Web API project to work with SOAP services in the sections below.

Install the SoapCore NuGet package

Next add the SoapCore NuGet package to the Web API project you just created in Visual Studio. To do this, select the project in the Solution Explorer window and right-click and select “Manage NuGet Packages.” In the NuGet Package Manager window, search for the SoapCore package and install it.

Alternatively, you can install the SoapCore package via the NuGet Package Manager console by entering the line shown below.

PM> Install-Package SoapCore

A third option is to install the SoapCore package via the dotnet CLI using the following command.

dotnet add package SoapCore

Create a data contract in ASP.NET Core

First off, let’s define a data contract. In a distributed application, a data contract plays an important role in ensuring that data exchanged between different systems is consistent and compatible by defining the structure and format of the exchanged data. In addition to basic types such as strings, numbers, and Booleans, data contracts also support composite types such as classes and structures as well as collection types.

Within the data contract, the properties or fields of each data type are specified along with their respective data types, names, and constraints or validation rules. This helps enable interoperability between clients and services implemented in different programming languages or platforms.

In C#, you can take advantage of the [DataContract] attribute to define a data contract. Create a new file named Author.cs and enter the following code to define a data contract.

using System.Runtime.Serialization;
namespace SoapCore_Demo
{
    [DataContract]
    public class Author
    {
        [DataMember]
        public int Id { get; set; }
        [DataMember]
        public string FirstName { get; set; }
        [DataMember]
        public string LastName { get; set; }
        [DataMember]
        public string Address { get; set; }
    }
}

Create a service contract in ASP.NET Core

A service contract is a fundamental part of a service-oriented architecture (SOA) and defines the interface and behaviors exposed by a service. Service contracts play a crucial role in service-oriented architectures by facilitating clear and efficient communication between service providers and customers. These contracts ensure mutual agreement between both parties, promoting interoperability and effective interaction.

A service contract typically has two main parts: the service interface (the service description) and any associated metadata that describes the service, such as message formats, security requirements, and service behavior. Service contracts are defined using the ServiceContract attribute in C#. The [ServiceContract] attribute in C# is used to designate an interface or a class as a service contract.

Create another .cs file, named AuthorServiceContract.cs, and enter the following code in there.

using System.Diagnostics;
using System.ServiceModel;
using System.Xml.Linq;
namespace SoapCore_Demo
{
    [ServiceContract]
    public interface IAuthorService
    {
        [OperationContract]
        void MySoapMethod(XElement xml);
    }
    public class AuthorService : IAuthorService
    {
        public void MySoapMethod(XElement xml)
        {
            Trace.WriteLine(xml.ToString());
        }
    }
}

The IAuthorService interface is marked with the [ServiceContract] attribute, which defines a service contract in the above example. The MySoapMethod() method is annotated with the [OperationContract] attribute, which marks it as an operation that clients can invoke to interact with the service.

Register a SOAP service in ASP.NET Core

To register the SOAP service, you should first add the service to the container by including the following code snippet in the Program.cs file.

builder.Services.AddSingleton<IAuthorService, AuthorService>();

You should then configure the HTTP request pipeline for the SOAP endpoint using the following line of code.

app.UseSoapEndpoint<IAuthorService>("/Service.asmx", new SoapEncoderOptions());

Here is the complete source code of the Program.cs file for your reference.

using SoapCore;
using SoapCore_Demo;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddSingleton<IAuthorService, AuthorService>();
builder.Services.AddControllers();
var app = builder.Build();
// Configure the HTTP request pipeline.
app.UseSoapEndpoint<IAuthorService>("/Service.asmx", new SoapEncoderOptions());
app.UseAuthorization();
app.MapControllers();
app.Run();

Execute the SOAP service

Now, run the application and browse the following endpoint to see the generated WSDL (Web Service Description Language) of the SOAP service as shown in Figure 1.

http://localhost:5210/Service.asmx

IDG

And there we have it—a SOAP service in ASP.NET Core. Note that you can also create a SOAP service using the WCF Web Service Reference tool in your Visual Studio IDE. This tool is available as a Visual Studio service extension, and can be used to create a Windows Communication Foundation (WCF) service based on SOAP in a .NET Core application.