Adding a UI to your WebAPI in ASP.NET 9.0

You may have noticed that when you create a WebAPI project in .NET 9.0, the default swagger UI is not there anymore by default. In this article, I will show you how to restore it back as the default UI. In addition, we will install an alternative UI to swagger named Scalar. The approach used applies to both minimal and controller-based WebAPI.

Companion Video: https://youtu.be/vsy-pIxKpYU
Source Code: https://github.com/medhatelmasry/WebApiDemo

Getting Started

Let us first create a minimal WebAPI project with the following terminal command:

dotnet new webapi -o WebApiDemo

cd WebApiDemo

Open the project in VS Code and note the following statements in Program.cs:

• Around line 5 is this statement, which adds the OpenApi service:

builder.Services.AddOpenApi();

• Also, around line 12 is this statement:

app.MapOpenApi();

The above statements produce the following JSON endpoint file describing your API when you run your app:

/openapi/v1.json

This displays a page like the following in your browser:

Restoring Swagger UI

Note that swagger UI is nowhere to be found. It is quite straight forward to add a Swagger UI to your .NET 9.0 WebAPI project. Start by adding the following package to your project:

dotnet add package Swashbuckle.AspNetCore

You can now add the following statement right under app.MapOpenApi():

app.UseSwaggerUI(options =>  {

    options.SwaggerEndpoint("/openapi/v1.json", "My WebAPI");

});

Now, run the project and go to endpoint /swagger in your browser. You should see this UI:

NOTE: If you want the Swagger UI to be accessed at the / (root) endpoint, then you can add this option:

options.RoutePrefix = "";

Scalar: alternative to Swagger

There is a much better alternative to swagger named Scalar. It offers you an enhanced UI and some additional features. Let us explore Scalar. 

To use Scalar in an ASP.NET 9.0 WebAPI application, you must add the following package:

dotnet add package Scalar.AspNetCore

Comment out the following code in Program.cs:

// app.UseSwaggerUI(options => 

// {

//     options.SwaggerEndpoint("/openapi/v1.json", "My WebAPI");

// });

Replace the above commented-out code with this:

app.MapScalarApiReference();

That's all you need to do. Let’s see how the Scalar UI looks like. Run the project and point your browser to this endpoint:

/scalar/v1

Explore this UI. One interesting feature is that you can view client code in a variety of languages. Here is what it looks like if you choose C#:

You can further customize the UI by enabling and disabling various options. For example, replace the statement app.MapScalarApiReference() with:

app.MapScalarApiReference(options => {

    options

        .WithTitle("My WebAPI")

        .WithTheme(ScalarTheme.Moon)

        .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);

});

This results in a less dark theme and a default client code of C#.

Making Scalar UI the default page

To make the Scalar UI the default page when launching your WebAPI page with “dotnet watch”, edit the /Properties/launchSettings.json file and make the following changes:

1. In both http and https blocks, add this item:

"launchUrl": "scalar/v1"

2. Also, in both http and https blocks, change the value of launchBrowser to true.

Now when you restart your webAPI web app with “dotnet watch”, the Scalar UI is automatically loaded in your default browser.

Happy Coding!

.NET Aspire with VS Code, SQLite & SQL Server

In this Tutorial, we will explore .NET Aspire. At first, we will use it with SQLite. Thereafter, we will modify the solution so that it uses a SQL Server Docker image instead of SQLite. All this is done in a terminal window with the help of VS Code. The objective is to serve those who do not use the higher end Visual Studio 2022 IDE.

Start source code: https://github.com/medhatelmasry/SoccerFIFA
End source code: https://github.com/medhatelmasry/SoccerAspire
Companion video: https://youtu.be/FDF04Lner5k

Prerequisites

In order to continue with this tutorial, you will need the following:

• .NET 9.0
• dotnet-ef tool - If you do not have this tool, you can install it with the terminal window command "dotnet tool install --global dotnet-ef"
• Visual Studio Code
• C# Dev Kit extension for Visual Studio Code
• Docker Desktop
• Azure Data Studio

.NET Aspire Setup

In any terminal window folder, run the following command before you install .NET Aspire:

dotnet workload update 

To install the .NET Aspire workload from the .NET CLI, execute this command:

dotnet workload install aspire

Check your version of .NET Aspire, with this command:

dotnet workload list

Startup Application

We will start with a .NET 9.0 application that involves a Minimal API backend and a Blazor frontend. Clone the code from this GitHub site with:

git clone https://github.com/medhatelmasry/SoccerFIFA

To get a good sense of what the application does, follow these steps:

1) Inside the WebApiFIFA folder, run the following command in a terminal window:

dotnet watch

Try out the GET /api/games endpoint, you should see the following output:

2) Next, let us try the frontend. Inside a terminal window in the BlazorFIFA folder, run this command:

dotnet watch

We know that the application works. However, it is a pain to have to start both projects to get the solution to work. This is where .NET Aspire will come to the rescue.

Converting solution to .NET Aspire

Close both terminal windows by hitting CTRL C in each.

To add the basic .NET Aspire projects to our solution, run the following command inside the root SoccerFIFA folder:

dotnet new aspire --force

This adds these artifacts:

• SoccerFIFA.sln file (this replaces the previous .sln file because of the --force switch)
• SoccerFIFA.AppHost folder
• SoccerFIFA.ServiceDefaults folder

We will add our previous API & Blazor projects to the newly created .sln file by executing the following commands inside the root SoccerFIFA folder:

dotnet sln add ./BlazorFIFA/BlazorFIFA.csproj

dotnet sln add ./WebApiFIFA/WebApiFIFA.csproj

dotnet sln add ./LibraryFIFA/LibraryFIFA.csproj

Our cloned projects use .NET 9.0. Unfortunately, at the time of writing this article, the new ASPIRE projects are created for .NET 8.0. We must unify all the projects so that they all use .NET 9.0. Therefore, update the .csproj files for SoccerFIFA.AppHost and SoccerFIFA.ServiceDefaults with package versions as follows:

SoccerFIFA.AppHost.csproj

change .net8.0 to .net 9.0

Package	Version
Aspire.Hosting.AppHost	9.1.0

SoccerFIFA.ServiceDefaults

change .net8.0 to .net 9.0

Package	Version
Microsoft.Extensions.Http.Resilience	9.2.0
Microsoft.Extensions.ServiceDiscovery	9.1.0
OpenTelemetry.Exporter.OpenTelemetryProtocol	1.11.1
OpenTelemetry.Extensions.Hosting	1.11.1
OpenTelemetry.Instrumentation.AspNetCore/td>	1.11.0
OpenTelemetry.Instrumentation.Http	1.11.0
OpenTelemetry.Instrumentation.Runtime	1.11.0

Next, we need to add references in the SoccerFIFA.AppHost project to the BlazorFIFA and WebApiFIFA projects with these commands:

dotnet add ./SoccerFIFA.AppHost/SoccerFIFA.AppHost.csproj reference ./BlazorFIFA/BlazorFIFA.csproj
dotnet add ./SoccerFIFA.AppHost/SoccerFIFA.AppHost.csproj reference ./WebApiFIFA/WebApiFIFA.csproj

Also, both BlazorFIFA and WebApiFIFA projects need to have references into SoccerFIFA.ServiceDefaults with:

dotnet add ./BlazorFIFA/BlazorFIFA.csproj reference ./SoccerFIFA.ServiceDefaults/SoccerFIFA.ServiceDefaults.csproj

dotnet add ./WebApiFIFA/WebApiFIFA.csproj reference ./SoccerFIFA.ServiceDefaults/SoccerFIFA.ServiceDefaults.csproj

Inside the SoccerFIFA root folder, start VS Code with:

code .

In the root folder, let us build to make sure everything works properly. Therefore, run this command:

dotnet build

You will receive an error message that suggests that you add the following markup to thje the .csproj file that belongs to 

<Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

Add the following code to SoccerFIFA.AppHost.csproj just under the opening <Project ... > tag. Thereafter, the solution should build without any errors.

Then, in the Program.cs files of both BlazorFIFA and WebApiFIFA, add this code before "var app = builder.Build();":

// Add service defaults & Aspire components.
builder.AddServiceDefaults();

In the Program.cs file in SoccerFIFA.AppHost, add this code right before “builder.Build().Run();”:

var api = builder.AddProject<Projects.WebApiFIFA>("backend");
builder.AddProject<Projects.BlazorFIFA>("frontend")
    .WithReference(api)
    .WaitFor(api);

Now, the relative name for the API app is “backend”. Therefore, we can change the base address to http://backend. Change Program.cs file in BlazorFIFA to:

client.BaseAddress = new Uri("http://backend/");

Test .NET Aspire Solution

To test the solution, in the SoccerFIFA.AppHost folder, start the application with:

dotnet watch

NOTE: If you are asked to enter a token, copy and paste it from the value in your terminal window:

This is what you should see in your browser:

Click on the app represented by the frontend link on the second row. You should experience the Blazor app:

At this stage we get a sense of what .NET Aspire can do for us. It essentially orchestrates the connection between multiple projects and produces a single starting point in the Host project. Let us take this journey one step further by converting our backend API so it uses a SQL Server container instead of SQLite.

Using SQL Server instead of SQLite

Stop the running application by hitting CTRL C.

IMPORTANT: You will need to ensure that Docker Desktop is running on your computer because Aspire will start SQL Server in a container. Also, update your Docker Desktop to the  latest version.

Add this package to the WebApiFIFA project:

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

Also in WebApiFIFA project Program.cs file, comment out (or delete) this code:

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlite(connectionString));

Place the below code just before builder.AddServiceDefaults():

builder.AddSqlServerDbContext<ApplicationDbContext>("sqldata");

Cleanup the backend API project (WebApiFIFA) from all traces of SQLite by doing the following:

1. Delete SQLite files college.db, college.db-shm, and college.db-wal.
2. In WebApiFIFA.csproj, delete: <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.2" />
3. Delete the Data/Migrations folder.
4. Delete the ConnectionStrings section in appsettings.json

We will create new migrations that work with SQL Server, instead of SQLite. Therefore, run the following command from within a terminal window inside folder WebApiFIFA.

dotnet ef migrations add M1 -o Data/Migrations

Configure AppHost to use SQL Server

The WebApiFIFA.AppHost project is the orchestrator for your app. It's responsible for connecting and configuring the different projects and services of your app. Add the .NET Aspire Entity Framework Core Sql Server library package to your SoccerFIFA.AppHost project with:

dotnet add package Aspire.Hosting.SqlServer

In the Program.cs file in SoccerFIFA.AppHost project comment out (or delete) the following code:

var api = builder.AddProject<Projects.WebApiFIFA>("backend");

Replace the above code with: 

var sql = builder.AddSqlServer("sql").AddDatabase("sqldata"); 

var api = builder.AddProject<Projects.WebApiFIFA>("backend")

    .WithReference(sql)

    .WaitFor(sql); 

The preceding code adds a SQL Server Container resource to your app and configures a connection to a database called sqldata. The Entity Framework classes you configured earlier will automatically use this connection when migrating and connecting to the database.

Run the solution

After ensuring that your Docker Desktop is running, execute this terminal window command inside the SoccerFIFA.AppHost folder:

dotnet watch

Your browser will look like this:

Click on the highlighted link above. Our application works just as it did before. The only difference is that this time we are using SQL Server running in a container:

I hope you found this useful and are able to see the possibilities of this new addition to .NET.

ASP.NET 7 Minimal Web API with SQLite

This tutorial is about using ASP.NET 6.0 Minimal WebAPI. We will build a simple application that uses SQLite to save students data. We will then consume the API from an HTML page. 

Source Code: https://github.com/medhatelmasry/StudentsApi Companion Video: https://youtu.be/JG2TeGBs8MU

VS Code extensions needed:

• C#
• C# Extensions

In a suitable working directory, create a Web API web application with:

dotnet new webapi -f net7.0 --no-https --use-minimal-apis -o StudentsMinimalApi 
 
cd StudentsMinimalApi  

 code .

dotnet watch

The app will display in your browser, and you will see this:

Look at API code in Program.cs:

app.MapGet("/weatherforecast", () =>

{

    var forecast =  Enumerable.Range(1, 5).Select(index =>

        new WeatherForecast

        (

            DateTime.Now.AddDays(index),

            Random.Shared.Next(-20, 55),

            summaries[Random.Shared.Next(summaries.Length)]

        ))

        .ToArray();

    return forecast;

})

.WithName("GetWeatherForecast"); 

.WithOpenApi();

Add this tool if you do not already have it: 

dotnet tool install --global dotnet-ef 

 Let us add these packages that provide support for SQLite and reading a CSV file: 

dotnet add package Microsoft.EntityFrameworkCore.Design

dotnet add package Microsoft.EntityFrameworkCore.Tools

dotnet add package Microsoft.EntityFrameworkCore

dotnet add package Microsoft.EntityFrameworkCore.SQLite

dotnet add package Microsoft.EntityFrameworkCore.SQLite.Design

dotnet add package CsvHelper

Create three folders: wwwroot, Data & Models.

Inside the Models folder, add the following Student class: 

public class Student {

        public int StudentId { get; set; }

        public string? LastName { get; set; }

        public string? FirstName { get; set; }

        public string? School { get; set; }

}

Developers prefer having sample data when building data driven applications. Therefore, we will create some sample data to ensure that our application behaves as expected. Copy the following data from https://gist.github.com/medhatelmasry/bd83812406665cd7584bb994f6e7704e and save it in a text file wwwroot/students.csv.

Add the following connection string to appsettings.json:

"ConnectionStrings": {

  "DefaultConnection": "DataSource=school.db;cache=shared"

},

Next, we need to add an Entity Framework context class. Inside the Data folder, add a class file named SchoolContext with the following content: 

public class SchoolDbContext : DbContext {

    public DbSet<Student> Students => Set<Student>();

    public SchoolDbContext(DbContextOptions<SchoolDbContext> options)

            : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder) {

        base.OnModelCreating(modelBuilder);

        modelBuilder.Entity<Student>().HasData(GetStudents());

    }

    private static IEnumerable<Student> GetStudents() {

        string[] p = { Directory.GetCurrentDirectory(), "wwwroot", "students.csv" };

        var csvFilePath = Path.Combine(p);

        var config = new CsvConfiguration(CultureInfo.InvariantCulture) {

            PrepareHeaderForMatch = args => args.Header.ToLower(),

        };

        var data = new List<Student>().AsEnumerable();

        using (var reader = new StreamReader(csvFilePath)) {

            using (var csvReader = new CsvReader(reader, config)) {

                data = csvReader.GetRecords<Student>().ToList();

            }

        }

        return data;

    }

}

In the above code, student data is being seeded in the OnModelCreating() method by reading contents of students.csv file.

We need to register the context class (SchoolDbContext) with dependency injection in Program.cs. Add the following code right before “var app = builder.Build();” in Program.cs: 

var connStr = builder.Configuration.GetConnectionString("DefaultConnection") 

    ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");

builder.Services.AddDbContext<SchoolDbContext>(option => option.UseSqlite(connStr));

Let us add a migration and subsequently update the database. Execute the following CLI commands in a terminal window.

dotnet ef migrations add M1 -o Data/Migrations

dotnet ef database update

At this point the database and tables are created.

Students API

Let us add API endpoints that:

• Read all the students
• Read students that belong to a particular school
• Read student data by id
• Add student data
• Update student data
• Delete student data

Therefore, add the following code to Program.cs just before the final statement “app.Run();”:

app.MapGet("/api/students", async (SchoolDbContext db) =>

    await db.Students.ToListAsync());

app.MapGet("/api/students/school/{school}", async (string school, SchoolDbContext db) =>

    await db.Students.Where(t => t.School!.ToLower() == school.ToLower()).ToListAsync());

app.MapGet("/api/students/{id}", async (int id, SchoolDbContext db) =>

    await db.Students.FindAsync(id)

        is Student student ? Results.Ok(student) : Results.NotFound());

app.MapPost("/api/students", async (Student student, SchoolDbContext db) =>

{

    db.Students.Add(student);

    await db.SaveChangesAsync();

    return Results.Created($"/students/{student.StudentId}", student);

});

app.MapPut("/api/students/{id}", async (int id, Student inputStudent, SchoolDbContext db) =>

{

    var student = await db.Students.FindAsync(id);

    if (student is null) return Results.NotFound();

    student.FirstName = inputStudent.FirstName;

    student.LastName = inputStudent.LastName;

    student.School = inputStudent.School;

    await db.SaveChangesAsync();

    return Results.NoContent();

});

app.MapDelete("/api/students/{id}", async (int id, SchoolDbContext db) =>

{

    if (await db.Students.FindAsync(id) is Student student)

    {

        db.Students.Remove(student);

        await db.SaveChangesAsync();

        return Results.Ok(student);

    }

    return Results.NotFound();

});

Run the app and point your browser to /api/students. You should see the following results:

Try endpoint /api/students/22: 

Try endpoint /api/students/school/medicine:

OPTIONAL: If you want migrations to be applied automatically, add the following code to Program.cs right before the last “app.Run()” statement

using (var scope = app.Services.CreateScope()) {

    var services = scope.ServiceProvider;

    var context = services.GetRequiredService<SchoolDbContext>();    

    context.Database.Migrate();

}

CORS (Cross-Origin Resource Sharing)

In wwwroot folder, create a file named show.html and add to it this HTML/JavaScript code:

<!DOCTYPE html>

<html>

  <html>

    <head>

      <meta charset="utf-8" />

      <title>Test API</title>

    </head>

    <body>

      <h3>Test API</h3>

      <button id="btnGetData">Get Data</button>

      <pre id="preOutput"></pre>

      <script>

        const url = "PUT-API-URL-HERE";

        var showResponse = function (object) {

          document.querySelector("#preOutput").innerHTML = JSON.stringify(

            object,

            null,

            4

          );

        };

        const button = document.querySelector("#btnGetData");

        button.addEventListener("click", (e) => {

          getData();

        });

        var getData = async function () {

          await fetch(url)

            .then((response) => {

              return response.json();

            })

            .then((data) => {

              showResponse(data);

            });

          return false;

        };

      </script>

    </body>

  </html>

</html>

Replace PUT-API-URL-HERE with the URL that gets all the students (Example: http://localhost:5143/api/students). 

From the file system, double-click on the wwwroot/show.html file. You will see the following page:

When you click on the “Get Data” button, nothing will appear because there is a JavaScript error. To understand where this error is coming from, hit F12 in your browser and check the console. This error will appear:

We need to enable CORS on the API project. This is done by adding the following code in Program.cs just before “var app = builder.Build();”:

 

// Add Cors

builder.Services.AddCors(o => o.AddPolicy("Policy", builder => {

  builder.AllowAnyOrigin()

    .AllowAnyMethod()

    .AllowAnyHeader();

}));

Also, in the same Program.cs file, add this code just after “var app = builder.Build();”: 

app.UseCors("Policy");

Save your code then make a new request for data from show.html. This time you should be successful:

Declutter Program.cs (optional)

Program.cs can get too cluttered. How about we move all the business logic into a separate class?

Create a Services/StudentService.cs class with the following content:

public class StudentService {

    public static async Task<IResult> GetAllStudents(SchoolDbContext db) {

        return TypedResults.Ok(await db.Students.ToListAsync());

    }

    public static async Task<IResult> GetStudentsBySchool(string school, SchoolDbContext db) {

        var students = await db.Students.Where(t => t.School!.ToLower() == school.ToLower()).ToListAsync();

        return TypedResults.Ok(students);

    }

    public static async Task<IResult> GetStudent(int id, SchoolDbContext db) {

        return await db.Students.FindAsync(id)

        is Student student

            ? Results.Ok(student)

            : Results.NotFound();

    }

    public static async Task<IResult> CreateSttudent(Student student, SchoolDbContext db) {

        db.Students.Add(student);

        await db.SaveChangesAsync();

        return Results.Created($"/students/{student.StudentId}", student);

    }

    public static async Task<IResult> UpdateStudent(int id, Student inputStudent, SchoolDbContext db) {

        var student = await db.Students.FindAsync(id);

        if (student is null) return Results.NotFound();

        student.FirstName = inputStudent.FirstName;

        student.LastName = inputStudent.LastName;

        student.School = inputStudent.School;

        await db.SaveChangesAsync();

        return Results.NoContent();

    }

    public static async Task<IResult> DeleteStudent(int id, SchoolDbContext db) {

        if (await db.Students.FindAsync(id) is Student student)

        {

            db.Students.Remove(student);

            await db.SaveChangesAsync();

            return TypedResults.Ok(student);

        }

        return TypedResults.NotFound();

    }

}

Also, change all the Map??? in Program.cs to:

    var route = app.MapGroup("/api/students");

route.MapGet("/", StudentService.GetAllStudents);

route.MapGet("/school/{school}", StudentService.GetStudentsBySchool);

route.MapGet("/{id}", StudentService.GetStudent);

route.MapPost("/", StudentService.CreateSttudent);

route.MapPut("/{id}", StudentService.UpdateStudent);

route.MapDelete("/{id}", StudentService.DeleteStudent);

The application should work as expected.

Congrats for coming this far.