Forem: Alex Khanuckaev

Generating TypeScript client from .NET 9 API with OpenAPI and Orval

Alex Khanuckaev — Tue, 13 May 2025 10:00:11 +0000

A step-by-step guide on how to automatically create strongly typed TypeScript client for your .NET API service.

Creating Demo API

First, let's demonstrate how to create an API. All examples are provided using console utilities, but they can be reproduced using IDE of choice.

Let's create a solution for our application:

dotnet new sln - name OpenApiDemo

Creating a full-scale WebAPI project with controllers:

dotnet new webapi -use-controllers -n DemoApi

And let's add it to our solution:

dotnet sln add DemoApi

As a result, you will have file structure like this:

Adding OpenAPI and Scalar

Recently, Microsoft introduced their own API description generator, reducing the reliance on Swashbuckle Swagger. Although this decision generated some controversy, considering the recent commercialization of many free libraries such as MassTransit and AutoMapper, it may not be entirely unfavorable. It's 2025 after all, so no need to depend on swagger.

So, let's add an OpenApi package to our dotnet project:

dotnet add DemoApi package Microsoft.AspNetCore.OpenApi

And also let's add Scalar to test our API (it's not actually needed to create typescript client, but it's always nice to have).
dotnet add DemoApi package Scalar.AspNetCore

And, also, we need to setup scalar to communicate with openapi generated references:

builder.Services.AddControllers();
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

Let's run our API and see if everything is OK:

dotnet run --project DemoApi

Generating OpenAPI reference file on build

Fine! Now we need to get api description file on build. To do this we need to install Microsoft.Extensions.ApiDescription.Server package by following command:

dotnet add DemoApi package Microsoft.Extensions.ApiDescription.Server

Ok, let's build project

dotnet build DemoApi

After building there should be a file DemoApi.json inside obj folder of your project

Regrettably, the DemoApi.json file is generated exclusively within the obj folder. For those utilizing a CI/CD pipeline where the backend and frontend are built in separate steps, and the output from the backend build is limited to the bin folder or, in some cases, only the docker image.

There are two potential solutions: either copy this file during the CI/CD step or modify your .csproj file accordingly. Given that MSBuild can be complex, here is the code that needs to be added:

<Target Name="PostBuild" AfterTargets="Build">
      <Copy SourceFiles="$(ProjectDir)obj\DemoAPI.json" DestinationFolder="$(OutDir)" />
      <Message Text="open api file copiied to $(OutDir)" Importance="high"/>
  </Target>

  <Target Name="CopyFilesToPublish" AfterTargets="Publish">
      <Copy SourceFiles="$(OutDir)\DemoAPI.json" DestinationFolder="$(PublishDir)"/>
  </Target>

Command to test those adjustments:

dotnet publish DemoApi -o out

Front-end

Front-end Preparations:

We will be using orval to generate our client, primarily because it comes highly recommended by my front-end coworkers.

Some preparational steps:

mkdir Front
cd Front
npm init
npm i orval -D
npm i axios

TypeScript client generation:

Create orval.config.js (this one generates client that uses axios library to make calls. If you want to use fetch api see documentation):

module.exports = {
  weather: {
    input: {
      target: "../out/DemoAPI.json",
    },
    output: {
      mode: "split",
      target: "endpoint.ts",
      schemas: "model",
    },
  },
};

To generate your typescript client, use command:

node .\node_modules\orval\dist\bin\orval.js --config .\orval.config.js

That's it. Your typescript client file is in endpoint.ts, and types for API contract calls are in models folder.

If you need a source code for this tutorial, I had created a github repository.

Btw, you can subscribe to my medium blog, to get my posts faster.

Using NSubstitute to implement multiple interfaces

Alex Khanuckaev — Tue, 25 Mar 2025 09:52:45 +0000

NSubstitute is an invaluable tool for .NET developers, offering a streamlined approach to creating test doubles for complex systems. It can easily create mocks not only for interfaces, but also for object. It has quite intelligible documentation, but some of their use cases are not fully covered. Inheritance of multiple interfaces, for example.

Creating Substitutes for Multi-Interface Objects with NSubstitute

NSubstitute provides a seamless way to create substitutes for objects that implement multiple interfaces. Let's explore the steps involved in this process.

Step 1: Define the Interfaces

First, define the interfaces that the object implements. For example, consider an object that implements IFoo and IBar interfaces.

    public interface IFoo
    {
        string FooMethod();
    }

    public interface IBar
    {
        string BarMethod();
    }

Step 2: Create a substitute

NSubstitute allows you to specify multiple interfaces when creating a substitute:

var multiInterfaceSubstitute = Substitute.For<IFoo, IBar>();
var substitute = Substitute.For<IFoo, IBar>();
Assert.True(substitute is IFoo);
Assert.True(substitute is IBar);

Step 3: Configure the Behavior

To configure substitute behaviour you can try use it as you always do:

substitute.FooMethod().Returns("Foo response");
substitute.BarMethod().Returns("Bar response");

No. This wouldn’t compile:

C# compiler is absolutely sure, that your object substitute is only type of IFoo. But not an IBar. I spent some time pondering around this error and was ready to just implement interface that inherits them both. But maybe I wasn’t the first person in the world who encounter this? Unfortunately, Google, StackOverflow and even bing didn’t give me the answer, but with some testing and trying I got this elegant (no) solution:

substitute.FooMethod().Returns("Foo!");
((IBar)substitute).BarMethod().Returns("Bar!");

Assert.Equal("Bar!", ((IBar)substitute).BarMethod());

Other things to play around:

You can implement one known class and set of interfaces there:

[Fact]
public void Test2()
{
    var substitute = Substitute.For<MyClass, IFoo, IBar>()!;
    Assert.True(substitute is IBar);
    ((IBar)substitute).BarMethod().Returns("Bar!");

    Assert.Equal("Bar!", ((IBar)substitute).BarMethod());
}

Let’s try it with classes.

var substitute = Substitute.For<MyClass, NotMyClass>()!;

This doesn’t work and raises the exceptions:

Tests.UnitTest1.Test4 (< 1ms): Error Message: NSubstitute.Exceptions.SubstituteException : Can not substitute for multiple classes. To substitute for multiple types only one type can be a concrete class; other types can only be interfaces.

So, unfortunately for some c++ folks, there is no multiple inheritance here.

Follow me on Medium

Dependency injection validation error in ASP.NET Core projects

Alex Khanuckaev — Sat, 11 Jan 2025 08:35:42 +0000

Recently I was digging into some dotnet project and while (days of) debugging realised, that some of singleton projects actually depends on the scoped ones.

Problem

Code example for better understanding:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddScoped<Scoped>();
builder.Services.AddSingleton<Singleton>();

var app = builder.Build();


class Scoped
{
    public string Test { get; set; } = "It works! But shouldn't";
}

class Singleton(Scoped sc)
{
    public void Print()
    {
        Console.WriteLine(sc.Test);
    }
}

This code started and didn't produce any errors. But of course, some services are scoped for a reason (EF Context for example), so when they don't you have a lot of really hard figure out bugs.

So what's happening?

Let's dive deeper inside builder.Build() here. It's actually using Build method from HostApplicationBuilder class. There is a code inside it:

ServiceProviderOptions? serviceProviderOptions = null;
if (!settings.DisableDefaults)
{
    HostingHostBuilderExtensions.ApplyDefaultAppConfiguration(_hostBuilderContext, Configuration, settings.Args);
    HostingHostBuilderExtensions.AddDefaultServices(_hostBuilderContext, Services);
    serviceProviderOptions = HostingHostBuilderExtensions.CreateDefaultServiceProviderOptions(_hostBuilderContext);
}

_createServiceProvider = () =>
{
    // Call _configureContainer in case anyone adds callbacks via HostBuilderAdapter.ConfigureContainer<IServiceCollection>() during build.
    // Otherwise, this no-ops.
    _configureContainer(Services);
    return serviceProviderOptions is null ? Services.BuildServiceProvider() : Services.BuildServiceProvider(serviceProviderOptions);
};

So yep, Services.BuildServiceProvider() without parameters doesn't validate services by default. But there are some options that comes from HostingHostBuilderExtensions. Ok, sometimes I like Microsoft naming. When you see something named as HostingHostBuilderExtensions, you can be absolutely sure, that things are completely screwed, and you are in a really deep water.

But this surprisingly is the end of the long journey. Here it is:

internal static ServiceProviderOptions CreateDefaultServiceProviderOptions(HostBuilderContext context)
{
    bool isDevelopment = context.HostingEnvironment.IsDevelopment();
    return new ServiceProviderOptions
    {
        ValidateScopes = isDevelopment,
        ValidateOnBuild = isDevelopment,
    };
}

So, the actual difference is Environment. Some folks in asp.net core development team decided to reduce building time of dependency injector containers by making validation dependant on, in fact, an environment variable. And haven’t provided any documentation.

TL;DR

Service validation in ASP.NET Core apps depends on environment. Guys in Microsoft made some optimizations, so validations works only if you are running your app in development environment. So be sure to set ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT to Develompent when you are debugging your code.