DEV Community: Wojciech Buńka

ASP.NET---101

Wojciech Buńka — Tue, 17 Mar 2026 15:45:33 +0000

About

This is my mini ASP.NET series. The goal is to provide readers with enough knowledge to start developing with ASP.NET. I plan to cover topics including Setup, REST APIs, SignalR, and Entity Framework with LINQ.

Articles

List of articles in this series.

Fundamentals

In this article I will try to provide you with the fundamental knowledge needed to start using ASP.NET. I will explain what ASP.NET, REST, and HTTP are. This article should give you enough theoretical knowledge to start working with ASP.NET.

Wojciech Buńka

Mar 17

ASP.NET---101 (Fundamentals)

#dotnet #aspnet

Comments

2 min read

Setup

In this article, I will explain how to set up a new ASP.NET project and what configurations are necessary. This project will also serve as a go-to template for creating ASP.NET applications and for teaching ASP.NET to others.

Wojciech Buńka

Mar 17

ASP.NET---101 (Setup)

#dotnet #aspnet

Comments

6 min read

REST

The purpose of this article is to provide you with practical, hands-on knowledge for building a REST API.
We will walk through the essential components required for creating API endpoints, covering both data input and data output techniques.

Wojciech Buńka

Mar 17

ASP.NET---101 (REST)

#dotnet #aspnet

Comments

2 min read

EF + LINQ

Work in progress

SignalR

Work in progress

ASP.NET---101 (Setup)

Wojciech Buńka — Tue, 17 Mar 2026 15:44:33 +0000

About

In this article I will explain how and what to set up in a new project. I will explain how and what to set up in a new project. This project will also serve as a go-to template for creating ASP.NET applications or for my teachings ASP.NET to others.

Solution creation

Let's start from creating empty project. You can use following command.

dotnet new web

If you are using VisualStudio just pick this.

I usually name solution and name project but with ".Api".

After creating the project, you will see the following file structure.

MyBestApp
+-- MyBestApp.sln
+-- MyBestApp.Api
|   +-- Program.cs
|   +-- appsettings.json
|   +-- appsettings.Development.json
|   +-- MyBestApp.Api.csproj
|   +-- Properties
|       +-- launchSettings.json

MyBestApp.sln – Solution file containing the overall solution configuration.
MyBestApp.Api.csproj – Project configuration file. Lists installed packages, project references, and included folders.
Program.cs – Startup file for the MyBestApp.Api project.
appsettings.json – Project configuration file for storing application settings. Note: Do not store credentials here.
appsettings.Development.json – Same as appsettings.json but specific to the development environment.
launchSettings.json – File containing launch settings.

Below is the default Program.cs file. I usually do not use the minimal API approach, so I will remove this line from the codebase. In this article i will show you how to do Controller based api.

var builder = WebApplication.CreateBuilder(args);
// Place your configuration code here
var app = builder.Build();

app.MapGet("/", () => "Hello World!"); // This will be removed

app.Run();

Basic configuration

To use certain features of ASP.NET or external packages, we first need to configure them.

What Do We Need to Configure?

Since we started with an empty project, we need to configure everything from scratch.

The basic setup includes logging, API documentation (Swagger), and a CORS policy.

Additionally, we must configure a controller-based API. For logging, I typically use Serilog.

But why?

Swagger is a great tool for documenting your API, and it can also be used to test it.
Logging is useful for analyzing what is happening within your application.
CORS allows your frontend application to communicate with the backend. This topic is more complex, but when running your frontend and backend locally, configuring CORS is often necessary. ## How I Prefer to Configure We could place all our configuration in the section mentioned in [Configuration], but the more we configure, the messier the code becomes. That’s why I prefer creating extension methods to handle specific configuration tasks. ## Extension members You can read more about them here: https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/extension-methods.

However, what they are can be quickly explained by the following quote:

Extension members enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type.

Extension Methods – Implementation

I will create a new folder named Configuration and add a new class called BasicConfig inside it.

MyBestApp
+-- MyBestApp.sln 
+-- MyBestApp.Api
|   +-- Program.cs
|   +-- appsettings.json
|   +-- appsettings.Development.json
|   +-- MyBestApp.Api.csproj
|   +-- Properties
|       +-- launchSettings.json
|   +-- Configuration // + This was added
|       +-- BasicConfig.cs // + This was added

BasicConfig.cs – This class will handle all our configuration. I also created an extension method named BasicConfiguration(), where we can place all the basic configuration logic.

namespace MyBestApp.Api.Configuration
{
    public static class BasicConfig
    {
        public static WebApplicationBuilder BasicConfiguration(this WebApplicationBuilder builder)
        {
            return builder;
        }
    }
}

To enable the BasicConfiguration method, we need to import its namespace in Program.cs and invoke it as shown below.

using MyBestApp.Api.Configuration; // Required to access the extension method

var builder = WebApplication.CreateBuilder(args);
var app = builder
    .BasicConfiguration() // Extension method invocation
    .Build();

app.Run();

Package instalation

Now that we know how to organize our configuration, it is time to install the required packages.

Swagger and Serilog are external packages we need to install. You can do this using the following commands:

nuget install Serilog.AspNetCore
nuget install Swashbuckle.AspNetCore

Alternatively, you can use the built-in NuGet UI tool in your IDE to install these packages.

From there, in the Browse tab, type the name of the package you are looking for and download it.

[Note]
Make sure you downlad package for your version of Dotnet

Config implementation

Configuration is really straing forward.

Controller based web api configuration

To achieve this, add the following method in BasicConfig.cs:

public static WebApplicationBuilder BasicConfiguration(this WebApplicationBuilder builder)
{
    builder.Services.AddControllers(); // Enables use of controllers

    return builder;
}

Then, in Program.cs, add:

var app = builder
    .BasicConfiguration()
    .Build();

app.MapControllers(); // Enables routing for controllers

app.Run();

Logging (Serilog) Configuration

To enable Serilog, use the following code. This configuration reads settings from appsettings.json and logs output to the console.

public static WebApplicationBuilder BasicConfiguration(this WebApplicationBuilder builder)
{
    builder.Services.AddControllers(); 

    builder.Host
        .UseSerilog((ctx, lc) => 
            lc.ReadFrom.Configuration(ctx.Configuration));

    return builder;
}

In Program.cs, add:

var app = builder
    .BasicConfiguration()
    .Build();

app.UseSerilogRequestLogging(); // Logs HTTP requests

app.MapControllers();

app.Run();

Add the following configuration to your appsettings.json:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
      }
    },
    "WriteTo": [
      {
      "Name": "Console"
      }
    ]
  },
}

Swagger configuration

For Swagger configuration, I prefer to create a separate method. This is mainly because the configuration can become quite extensive, and it’s a feature you typically configure once and forget. Add the following method to BasicConfig.cs:

public static WebApplicationBuilder AddSwaggerSupport(this WebApplicationBuilder builder)
{
    builder.Services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "MyBestApp API",
            Version = "v1",
            Description = "Application created with love",
        });
    });

    return builder;
}

In Program.cs, use this configuration as follows:

var app = builder
    .BasicConfiguration()
    .AddSwaggerSupport()
    .Build();

app.UseSerilogRequestLogging();

app.UseSwagger();    // Enables Swagger middleware

app.UseSwaggerUI();  // Enables Swagger UI

app.MapControllers();

app.Run();

CORS configuration

If you don’t have a frontend, you don’t need to configure this. Similar to the logging configuration, we retrieve CORS settings from appsettings.json and apply the following configuration. Start by updating BasicConfig.cs:

public static WebApplicationBuilder BasicConfiguration(this WebApplicationBuilder builder)
{
    builder.Services.AddControllers(); 

    builder.Host 
        .UseSerilog((ctx, lc) => 
            lc.ReadFrom.Configuration(ctx.Configuration));

    var paths = builder.Configuration.GetSection("CORS-Paths").Get<string[]>();
    if (paths != null)
        builder.Services.AddCors(options =>
        {
            options.AddPolicy("CorsPolicy",
                builder => builder.WithOrigins(paths)
                .AllowAnyHeader()
                .AllowAnyMethod()
                .AllowCredentials()
                .SetIsOriginAllowed((host) => true));
        }); // + 

    return builder;
}

Add the following section to your appsettings.json:

{
  "CORS-Paths": [ // Use your frontend URLs here
    "https://localhost:7291",
    "http://localhost:5055"  
  ],
}

Final configuration

Now that we have all the necessary configurations, here is how my files look:

BasicConfig.cs

using Microsoft.OpenApi.Models;
using Serilog;

namespace MyBestApp.Api.Configuration
{
    public static class BasicConfig
    {
        public static WebApplicationBuilder BasicConfiguration(this WebApplicationBuilder builder)
        {
            builder.Services.AddControllers();

            builder.Host
                .UseSerilog((ctx, lc) => lc
                .WriteTo.Console()
                .ReadFrom.Configuration(ctx.Configuration));

            var paths = builder.Configuration.GetSection("CORS-Paths").Get<string[]>();
            if (paths != null)
                builder.Services.AddCors(options =>
                {
                    options.AddPolicy("CorsPolicy",
                        builder => builder.WithOrigins(paths)
                        .AllowAnyHeader()
                        .AllowAnyMethod()
                        .AllowCredentials()
                        .SetIsOriginAllowed((host) => true));
                });

            return builder;
        }

        public static WebApplicationBuilder AddSwaggerSupport(this WebApplicationBuilder builder)
        {
            builder.Services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "MyBestApp API",
                    Version = "v1",
                    Description = "Application created with love",
                });
            });

            return builder;
        }
    }
}

Program.cs

using MyBestApp.Api.Configuration;
using Serilog;

var builder = WebApplication.CreateBuilder(args);
var app = builder
    .BasicConfiguration()
    .AddSwaggerSupport()
    .Build();

app.UseSerilogRequestLogging();

app.UseSwagger();

app.UseSwaggerUI();

app.MapControllers();

app.Run();

appsettings.json

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information"
      }
    },
    "WriteTo": [
      {
        "Name": "Console"
      }
    ]
  },
  "CORS-Paths": [
    "https://localhost:7291", 
    "http://localhost:5055"
  ],
  "AllowedHosts": "*"
}

With this configuration, we are nearly ready to run our application. The final missing piece is creating the Controller.

Controllers

To test the configuration, we need to create our first Controller. I will add the following to our project:

MyBestApp
+-- MyBestApp.sln 
+-- MyBestApp.Api
|   +-- Program.cs
|   +-- appsettings.json
|   +-- appsettings.Development.json
|   +-- MyBestApp.Api.csproj
|   +-- Properties
|       +-- launchSettings.json
|   +-- Configuration
|       +-- BasicConfig.cs
|   +-- Controllers // + This was added
|       +-- MyBestAppController.cs // + This was added

In MyBestAppController.cs, I will create an example controller containing a GET method named Ping that returns the string "Pong".

using Microsoft.AspNetCore.Mvc;

namespace MyBestApp.Api.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class MyBestAppController : ControllerBase
    {
        [HttpGet("Ping")]
        public string PingPong()
        {
            return "Pong";
        }
    }
}

Now our app is ready for testing. You can access Swagger to see the new GET endpoint, and verify that logging is functioning correctly.

To access Swagger, navigate to your launch URL and append /swagger/index.html. This will open a page similar to the one shown below.

Exactly! This page will display your API’s documentation, including the custom description and the available endpoints like your Ping GET method. From here, you can easily test your API directly in the browser.

And in the console, you should see logs generated by your application, including HTTP request details and any other configured log events.

Summary

In this article, we completed the basic setup of an ASP.NET application. We configured essential features such as Swagger, logging, and CORS, and created a simple endpoint. In the next article, I will cover more advanced topics related to building Web APIs.

ASP.NET---101 (REST)

Wojciech Buńka — Tue, 17 Mar 2026 15:44:30 +0000

About

The purpose of this article is to provide you with practical, hands-on knowledge for building a REST API.

We will walk through the essential components required for creating API endpoints, covering both data input and data output techniques.

Attributes

In ASP.NET Core, attributes define and control API behavior. They are placed above controller methods and provide metadata about how each endpoint should handle requests.

Commonly used attributes include:

[HttpGet], [HttpPost], [HttpPut], [HttpDelete] – Specify the HTTP method for an endpoint
[Route("path")] – Define a custom URL route
[FromBody], [FromQuery], [FromForm] – Control how parameters are bound
[Produces("application/json")] – Specify the response format ## Input Methods In this section, we explore how to receive data in a REST API. Different HTTP methods and scenarios require different binding techniques. Some inputs can be combined; others are specific to certain request types. ### Form Query Query parameters are appended to the URL and are useful for simple key-value data, especially for GET requests.

[HttpGet("FormQuery")]
public string FormQuery([FromQuery] string text)
{
    return $"Your text form Query -> {text}";
}

Example request (cURL)

curl -X 'GET' \
  'https://localhost:7291/api/MyBestApp/QueryExample?text=You_Are_Great' \
  -H 'accept: text/plain'

You can also paste {Your_URL}/api/MyBestApp/QueryExample?text=You_Are_Great

directly into your browser’s address bar.

From Body

For sending complex or large amounts of data (e.g., objects, arrays), we use the request body—primarily with POST or PUT methods.

[HttpPost("FormBody")]
public string FormBody([FromBody] ExampleRequest request)
{
    return String.Concat(Enumerable.Repeat(request.Text, request.Amount));
}

Example request (cURL)

curl -X 'POST' \
  'https://localhost:7291/api/MyBestApp/BodyExample' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "ASP.NET",
  "amount": 5
}'

From Route

Route parameters are embedded directly in the URL path.

[HttpGet("FormRoute/{text}")]
public string FormRoute(string text)
{
    return $"Your text form Query -> {text}";
}

Example request (cURL)

curl -X 'GET' \
  'https://localhost:7291/api/MyBestApp/RouteExample/What%27s_up%3F' \
  -H 'accept: text/plain'

As with query parameters, you can also call this endpoint directly in your browser.

Return types

So far, our examples have returned simple strings. However, return type choice affects control over HTTP status codes and response formatting.

Common return patterns:

Direct type (e.g., string) – Simple, but limited HTTP status control.
ActionResult<T> – Strongly typed response with full HTTP status control.
IActionResult – Flexible return type for varied responses.

[HttpPost("FormBodyActionResult")]
public ActionResult<string> FormBodyActionResult([FromBody] ExampleRequest request)
{
    if (request.Amount < 0)
        return new BadRequestObjectResult("Amount must be bigger that 0");

    return Ok(String.Concat(Enumerable.Repeat(request.Text, request.Amount)));
}

[HttpPost("FormBodyIActionResult")]
public IActionResult FormBodyIActionResult([FromBody] ExampleRequest request)
{
    if (request.Amount < 0)
        return new BadRequestObjectResult("Amount must be bigger that 0");

    return Ok(String.Concat(Enumerable.Repeat(request.Text, request.Amount)));
}

!Bonus!: How to upload file

ASP.NET Core supports file uploads using the [FromForm] attribute with IFormFile.

[HttpPost("FileUploadExample")]
public string FromForm(IFormFile file)
{
    return $"Received: {file.FileName}, {file.ContentType}";
}

Summary

We explored the key elements of building a REST API in ASP.NET Core, including defining endpoints with attributes, receiving input from different sources, and returning structured responses. You also learned how to handle files through API endpoints. With these fundamentals, you can start creating functional, flexible, and well-structured APIs.

ASP.NET---101 (Fundamentals)

Wojciech Buńka — Tue, 17 Mar 2026 15:44:25 +0000

About

The goal of this article is to provide you with the fundamental knowledge needed to start using ASP.NET. I will explain what ASP.NET, REST, and HTTP are. This article should give you enough theoretical knowledge to start working with ASP.NET.

What is ASP.NET?

So, what is ASP.NET? As stated on the official ASP.NET homepage: https://dotnet.microsoft.com/en-us/learn/aspnet/what-is-aspnet.

ASP.NET is an open source web framework, created by Microsoft, for building modern web apps and services with .NET.

ASP.NET is cross platform and runs on Windows, Linux, macOS, and Docker.

ASP.NET WEB API

The ASP.NET Web API is a framework for building HTTP services that can be accessed from a wide range of clients. It integrates seamlessly with the ASP.NET Core pipeline, making it lightweight, fast, and easy to test.

Its key benefits include:

Automatic routing based on URL patterns
Built-in support for JSON and XML serialization
Model binding and validation
Flexible return type handling ## REST REST (Representational State Transfer) is an architectural style for designing networked applications. It uses HTTP as the communication protocol and emphasizes a stateless, client-server model. REST APIs typically use standard HTTP verbs such as:
GET – Retrieve data
POST – Create new data
PUT/PATCH – Update existing data
DELETE – Remove data

A well-designed REST API is easy to understand, scalable, and can be consumed by any client capable of making HTTP requests.

HTTP

HTTP (Hypertext Transfer Protocol) is the foundation of data communication on the web. In the context of ASP.NET Web API, HTTP provides:

Methods (verbs) to define the action on resources
Headers to send metadata
Status codes to indicate the result of the request (e.g., 200 OK, 404 Not Found, 500 Internal Server Error)
Body to carry data in various formats such as JSON, XML, or plain text ### HTTP Methods and Request Body Usage

Different HTTP methods have different conventions regarding the use of the request body:

Method	Typical Use	Request Body Allowed?	Notes
GET	Retrieve data	Not recommended (technically possible, but discouraged and often ignored by servers/browsers)	All data should be sent via query parameters.
POST	Create new resource	Yes	Commonly used for sending JSON, XML, or form data in the body.
PUT	Replace a resource entirely	Yes	The body usually contains the full updated resource representation.
DELETE	Remove a resource	Rarely used	Spec says a body is allowed, but most implementations ignore it.

Summary

In this article, we discussed what ASP.NET is, covered REST, and reviewed the basics of HTTP. I hope this will help you in working with ASP.NET. In the next article, I will show you how to perform a basic project setup.

ASP.NET - SOAP API (SOAPCORE)

Wojciech Buńka — Fri, 25 Apr 2025 18:54:08 +0000

About

This article is practical guide for anyone looking to set up and work with a SOAP API. It is based on my own experience, and aims to provide clear steps, useful tips, and highlight some of the common challenges I encountered along the way.

Tools

For this tutorial we will be needing:

.Net 8
Postman

About
Contents
What is SOAP API?
- Key Features
Project preconditions
Model
- DataContract example
- XMLSerialization example
Soap service
- Implementation
- Configuration
- What is WSDL?
- How to Read a WSDL?
How to Call a SOAP API?
- Postman example
Final words

What is SOAP API?

SOAP API (Simple Object Access Protocol) is a protocol used to exchange information between systems over a network using HTTP. It's one of the ways web services can communicate with each other, often used in enterprise applications.

Key Features

Protocol-based - SOAP is a standard protocol, It follows strict rules defined by the W3C.
XML Format
WSDL (Web Services Description Language) - SOAP use WSDL files to describe the service – what operations it provides, input/output types, and how to access it.

Project preconditions

Install SoapCore nuget package

dotnet add package SoapCore

With this packed installed we are ready to create example model for our project.

Model

For the sake of this article we will use basic model of Invoice.

In .NET, there are two primary approaches for serializing objects to XML: DataContractSerializer and XmlSerializer. For new development, DataContractSerializer is generally recommended due to its superior performance, support for complex object graphs, and ability to serialize private members. However, in legacy systems or scenarios requiring strict adherence to specific XML schemas, XmlSerializer may be necessary, as it offers greater control over the XML output and is compatible with a broader range of existing XML standards. In this article, we will explore both serializers to understand their respective use cases and implementation details

DataContract example

This example demonstrates how to implement DataContract and DataMember attributes for serializing objects in SOAP services using DataContractSerializer.

DataContract: Applied to classes to indicate they are serializable. This tells the serializer which types should be included in the SOAP message.
DataMember: Applied to class properties to mark them for serialization. Only properties marked with this attribute are included in the serialized XML.

[DataContract]
public class Invoice
{
    [DataMember]
    public required int InvoiceNumber { get; set; }
    [DataMember]
    public required string CustomerName { get; set; }
    [DataMember]
    public required DateTime InvoiceDate { get; set; }
    [DataMember]
    public ICollection<InvoiceItem> Items { get; set; } = new List<InvoiceItem>();
}

[DataContract]
public class InvoiceItem
{
    [DataMember]
    public string? Description { get; set; }
    [DataMember]
    public required int Quantity { get; set; }
    [DataMember]
    public required decimal UnitPrice { get; set; }
}

[DataContract]
public class GetInvoice
{
    [DataMember]
    public required int InvoiceNumber { get; set; }
}

XMLSerialization example

For XmlSerializer situation is the same but we use XmlType and XmlElement:

XmlType: Applied to classes to define the XML schema for the object. It marks the class as serializable to XML.
XmlElement: Applied to class properties to specify which properties should be included in the serialized XML and how they should appear in the XML structure.

[XmlType]
public class XmlInvoice
{
    [XmlElement]
    public required int InvoiceNumber { get; set; }
    [XmlElement]
    public required string CustomerName { get; set; }
    [XmlElement]
    public required DateTime InvoiceDate { get; set; }
    [XmlElement]
    public ICollection<XmlInvoiceItem> Items { get; set; }
}

[XmlType]
public class XmlInvoiceItem
{
    [XmlElement]
    public string? Description { get; set; }
    [XmlElement]
    public required int Quantity { get; set; }
    [XmlElement]
    public required decimal UnitPrice { get; set; }
}

[XmlType]
public class GetXmlInvoice
{
    [XmlElement]
    public required int InvoiceNumber { get; set; }
}

Soap service

With our model in place, we can proceed to implement the service. A service defines the methods that clients can invoke via SOAP. Each service consists of one or more OperationContracts, which represent operations exposed to remote clients.

Implementation

Implementing a SOAP service in .NET is straightforward. First, we import the System.ServiceModel namespace. Then, we define an interface decorated with the ServiceContract attribute, and annotate each method intended for remote access with the OperationContract attribute.

Example

using System.ServiceModel;

[ServiceContract]
public interface IInvoiceService
{
    [OperationContract]
    public IEnumerable<Invoice> GetInvoices(GetInvoice invoice);
}

When we have interface ready all we need to do is implement this interface.

public class InvoiceService : IInvoiceService
{
    public IEnumerable<Invoice> GetInvoices(GetInvoice invoice)
    {
        return [ 
            new Invoice() 
            {
                CustomerName = "Jhon",
                InvoiceDate = DateTime.Now,
                InvoiceNumber = 1,
                Items = [ 
                    new InvoiceItem() 
                    {
                        Description = "Pen",
                        Quantity = 1,
                        UnitPrice = 21.37M
                    }
                ]
            },
            new Invoice()
            {
                CustomerName = "Tom",
                InvoiceDate = DateTime.Now,
                InvoiceNumber = 1,
                Items = [
                    new InvoiceItem()
                    {
                        Description = "Cars",
                        Quantity = 1,
                        UnitPrice = 22.12M
                    }
                ]
            }
        ];
    }
}

Configuration

Now that our SOAP service is ready, the next step is to register it in the ASP.NET application. First we need to register our service to dependency injection (DI) container. Then we need to add endpoint to our service.

During endpoint registration, we need to configure two key properties: SoapSerializer and Path.

SoapSerializer: This should be set according to the serialization method used—either DataContractSerializer or XmlSerializer.
Path: This specifies the URL path where the service will be accessible. For example, if we set the Path to "/XmlServicePath.asmx", the service can be accessed at https://localhost/XmlServicePath.asmx.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSoapCore();
builder.Services.AddSingleton<IInvoiceService, InvoiceService>();
builder.Services.AddSingleton<IXmlInvoiceService, XmlInvoiceService>();

var app = builder.Build();

app.UseRouting();

app.UseEndpoints(endpoints => {
    _ = endpoints.UseSoapEndpoint<IXmlInvoiceService>(opt =>
    {
        opt.Path = "/XmlServicePath.asmx";
        // Set SoapSerializer to XmlSerializer when using XmlSerializer
        opt.SoapSerializer = SoapSerializer.XmlSerializer;
    });
    _ = endpoints.UseSoapEndpoint<IInvoiceService>(opt =>
    {
        opt.Path = "/ServicePath.asmx";
        // Set SoapSerializer to DataContractSerializer when using DataContractSerializer
        opt.SoapSerializer = SoapSerializer.DataContractSerializer;
    });
});

With the service set up, we can now launch the application. Open a web browser and navigate to your application's base URL, appending /XmlServicePath.asmx or /ServicePath.asmx to access the SOAP endpoint. If everything is configured correctly, you should see a page displaying the service description.

This is WSDL

What is WSDL?

WSDL (Web Services Description Language) is an XML-based document that describes a SOAP web service—including its operations, location (endpoint), and the communication protocols it uses.

How to Read a WSDL?

WSDL files can be read manually, but using tools can make the process easier and more intuitive. Personally, I recommend the Wizdler Chrome extension. It's lightweight and provides a clear overview of the service structure and required inputs. However, many other tools are available to help you inspect and interact with WSDL files, depending on your preferences and development environment.

How to Call a SOAP API?

Calling a SOAP API is straightforward. First, add the required HTTP headers:

SOAPAction: Set this to the specific action you want to call, e.g., http://tempuri.org/IMyService/GetUser
Content-Type: Set this to text/xml; charset=utf-8

Next, construct the request body. A SOAP message must be wrapped in a SOAP Envelope, which includes a Header (optional) and a Body (required). Here's a basic example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
   <soapenv:Header/>
   <soapenv:Body>
    {{Your conntent here}}
   </soapenv:Body>
</soapenv:Envelope>

This Envelope structure is mandatory for every SOAP request.

To test our service we need to make following call.

POST /ServicePath.asmx HTTP/1.1
Host: https://localhost:32769
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://tempuri.org/IMyService/GetUser"

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <tem:GetUser>
         <tem:userId>123</tem:userId>
      </tem:GetUser>
   </soapenv:Body>
</soapenv:Envelope>

Postman example

Additional Resources

This section includes tools and resources that, while not essential for every project, may prove useful depending on your needs. During the development of my project, I found these items difficult to locate, so I’ve included them here to help others who might encounter similar challenges.

Double encoding of XML

Double encoding in XML refers to the practice of encoding specific characters or entities multiple times, often resulting in a redundant encoding process. This typically manifests in a manner similar to the following.

Normal XML.

<?xml version="1.0" encoding="UTF-8"?>
<book>
    <title>The Great Gatsby</title>
    <author>F. Scott Fitzgerald</author>
    <genre>Fiction</genre>
    <published>1925</published>
    <price currency="USD">10.99</price>
</book>

Now we want to encode our xml. For this we will use table below.

Character	Encoded As
`<`	`<`
`>`	`>`
`&`	`&`
`"`	`"`
`'`	`'`

Encoded XML.

&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;book&gt;
    &lt;title&gt;The Great Gatsby&lt;/title&gt;
    &lt;author&gt;F. Scott Fitzgerald&lt;/author&gt;
    &lt;genre&gt;Fiction&lt;/genre&gt;
    &lt;published&gt;1925&lt;/published&gt;
    &lt;price currency=&quot;USD&quot;&gt;10.99&lt;/price&gt;
&lt;/book&gt;

But now we want to encode once more. This time is easy. We need to add & before every special sign (Table above).

Double encoded XML.

&amp;lt;?xml version=&amp;quot;1.0&amp;quot; encoding=&amp;quot;UTF-8&amp;quot;?&amp;gt;
&amp;lt;book&amp;gt;
    &amp;lt;title&amp;gt;The Great Gatsby&amp;lt;/title&amp;gt;
    &amp;lt;author&amp;gt;F. Scott Fitzgerald&amp;lt;/author&amp;gt;
    &amp;lt;genre&amp;gt;Fiction&amp;lt;/genre&amp;gt;
    &amp;lt;published&amp;gt;1925&amp;lt;/published&amp;gt;
    &amp;lt;price currency=&amp;quot;USD&amp;quot;&amp;gt;10.99&amp;lt;/price&amp;gt;
&amp;lt;/book&amp;gt;

This proces can be repeted as many times you want.

XSD

XSD, or XML Schema Definition, is utilized to define the structure, data types, and constraints of XML messages exchanged between web services.

In some cases, you may encounter .xsd files. When this occurs, you can leverage the xsd.exe tool to work with these files. Further details about this tool can be found in the XSD.exe Documentation.

Final words

That concludes this article. You should now be equipped to set up your own SOAP API. If you have any questions or notice any mistakes, please feel free to leave a comment. Best of luck, and enjoy working on your implementation!

Link to my implementation -> https://github.com/TheWerou/SoapCoreExample

DEV Community: Wojciech Buńka

ASP.NET---101

About

Articles

Fundamentals

ASP.NET---101 (Fundamentals)

Setup

ASP.NET---101 (Setup)

REST

ASP.NET---101 (REST)

EF + LINQ

SignalR

ASP.NET---101 (Setup)

About

Solution creation

Basic configuration

What Do We Need to Configure?

But why?

Extension Methods – Implementation

Package instalation

Config implementation

Controller based web api configuration

Logging (Serilog) Configuration

Swagger configuration

CORS configuration

Final configuration

Controllers

Summary

ASP.NET---101 (REST)

About

Attributes

Example request (cURL)

From Body

Example request (cURL)

From Route

Example request (cURL)

Return types

!Bonus!: How to upload file

Summary

ASP.NET---101 (Fundamentals)

About

What is ASP.NET?

ASP.NET WEB API

HTTP

Summary

ASP.NET - SOAP API (SOAPCORE)

About

Tools

Contents

What is SOAP API?

Key Features

Project preconditions

Model

DataContract example

XMLSerialization example

Soap service

Implementation

Configuration

What is WSDL?

How to Read a WSDL?

How to Call a SOAP API?

Postman example

Additional Resources

Double encoding of XML

XSD

Final words

Links