Monday, November 16, 2026

Develop a blazor app with GitHub Copilot SDK

 In the walkthrough, we will develop an AI agent that queries a SQLite database in a Blazor app using GitHub Copilot SDK.

Prerequisites

  • .NET 10 or later
  • GitHub Copilot in your personal GitHub account (includes the GitHub Copilot Free plan)
  • Visual Studio Code with C# DevKit extension
  • dotnet-ef tool

What is an AI agent?

An AI agent is a goal-driven AI entity that can reason, take actions, and adapt autonomously in pursuit of an objective. Unlike a simple chatbot that only responds to user queries with pre-scripted answers, an AI agent can make decisions, use tools or APIs, and maintain memory of context to achieve a goal without step-by-step human guidance.

Modern AI agents are powered by advanced AI models, often large language models (LLMs), and provide several core abilities that distinguish them from basic automation:
  • Reasoning and planning
  • Tool use
  • Memory and context
  • Interactive execution

What is the GitHub Copilot SDK?

The GitHub Copilot SDK is a multi-platform toolkit that allows you to embed an AI agent runtime into your own applications.

Why use an SDK for AI agents?

Building a full-featured AI agent from the ground up is complex. You need to handle conversation state management across turns, decide when to call which external API, ensure the AI's responses stay within boundaries, manage multiple AI models for different tasks, and implement safety measures. 

The GitHub Copilot SDK removes that complexity by providing a prebuilt, production-tested agent engine. The SDK handles authentication, model management, chat sessions, and streaming. You focus on what gets built on top of those building blocks - your domain-specific tools and business logic.

Core concepts

Client

The CopilotClient class manages the connection to the Copilot CLI server. 

Session

A CopilotSession represents a single conversation or task context. Each session has its own conversation history, model configuration, tool definitions, and system prompt. You create sessions from the client using CreateSessionAsync, send messages to them, and receive responses through an event-driven model.

Tools

Tools are functions that you register with a session so the AI agent can call them during reasoning. Each tool has a name, description, parameters, and a handler function. When the AI model decides to use a tool, the SDK intercepts the request, calls your handler, and feeds the result back to the model for further reasoning.

In .NET, you define tools using AIFunctionFactory.Create from Microsoft.Extensions.AI:

AIFunctionFactory.Create(
    async ([Description("The order ID number")] int orderId) =>
        await GetOrderDetailsAsync(orderId),
    "get_order_details",
    "Look up the status and details of a specific order.")

Events

The SDK uses an event-driven communication model.

Session hooks

The SDK provides hooks that let you intercept and modify agent behavior at key points.

Getting started

In a working directory create a Blazor app and add required packages with these terminal window commands:

dotnet new blazor -o AI4SchoolAgent
cd AI4SchoolAgent
mkdir Models
mkdir Data
mkdir Services
mkdir Tools dotnet add package GitHub.Copilot.SDK dotnet add package Microsoft.Extensions.AI dotnet add package Microsoft.EntityFrameworkCore.Design dotnet add package Microsoft.EntityFrameworkCore.Sqlite

In the Models folder, add this C# Student class:

public class Student {

    public int StudentId { get; set; }

    [Required]
    public String? FirstName { get; set; }

    [Required]
    public String? LastName { get; set; }

    [Required]
    public String? School { get; set; }

    [Required]
    public String? Gender { get; set; }

    public DateOnly? DateOfBirth { get; set; }
    public String? Status { get; set; }
}

We will populate a SQLite database with some sample student data. We will need an Entity Framework database context class. Add the following C# SchoolDbContext class inside the Data folder:

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.EntityStudent>().HasData(GetStudents());

  }

  private static IEnumerable<Student> GetStudents() {
    const string studentsUrl =
      "https://gist.githubusercontent.com/medhatelmasry/2ae7a36d5392f862b0d1039b2a52b9b4/raw/45533eda6c43ce439dbc65c37a7fbdef01546c2d/students.json";

    using var httpClient = new HttpClient();

    var json = httpClient.GetStringAsync(studentsUrl).GetAwaiter().GetResult();

    return System.Text.Json.JsonSerializer.Deserialize<List<Student>>(json)

      ?? throw new InvalidOperationException("The students JSON returned no data.");
  }
}

In the above code, note that sample data is being read from a URL.

Add the following connection string to appsettings.json:

"ConnectionStrings": {
  "DefaultConnection": "DataSource=school-db.sqlite;Cache=Shared;"
}

Let’s add some tools that will help us query the database using natural language. In the Tools folder, add a C# class named StudentsAgentTools with the following code:

public class StudentsAgentTools {
    private readonly DbContext _dbContext;

    public StudentsAgentTools(DbContext dbContext) {
        _dbContext = dbContext;
    }

    public async Task<string> GetStudentDetailsByIdAsync(int studentId) {
        // Query the database for student information

        var student = await _dbContext.Set<Student>().FindAsync(studentId);

        return student != null

            ? $"Student {studentId}: {student.FirstName} {student.LastName}, School: {student.School}, Gender: {student.Gender}, Status: {student.Status ?? "not recorded"}"

            : "Student not found.";
    }

    public async Task<string> GetStudentsByGenderAsync(string gender) {
        // Query the database for student information by gender

        var students = await _dbContext.Set<Student>().Where(s => s.Gender == gender).ToListAsync();

        if (students.Count == 0)
            return "No students found.";

        var result = new StringBuilder();

        foreach (var student in students) {
            result.AppendLine($"Student {student.StudentId}: {student.FirstName} {student.LastName}, School: {student.School}, Gender: {student.Gender}, Status: {student.Status ?? "not recorded"}");
        }
        return result.ToString();
    }

    public async Task<string> GetStudentsBySchoolAsync(string school) {
        // Query the database for student information by school
        var students = await _dbContext.Set<Student>().Where(s => s.School == school).ToListAsync();

        if (students.Count == 0)
            return "No students found.";

        var result = new StringBuilder();

        foreach (var student in students) {
            result.AppendLine($"Student {student.StudentId}: {student.FirstName} {student.LastName}, School: {student.School}, Gender: {student.Gender}, Status: {student.Status ?? "not recorded"}");
        }
        return result.ToString();
    }

    public async Task<string> GetStudentsByAgeAsync() {
        // Query the database for student information by school

        var students = await _dbContext.Set<Student>().ToListAsync();

        if (students.Count == 0)
            return "No students found.";

        var result = new StringBuilder();

        foreach (var student in students) {
            var today = DateOnly.FromDateTime(DateTime.Today);

            var age = student.DateOfBirth is { } dateOfBirth
                ? today.Year - dateOfBirth.Year - (today < dateOfBirth.AddYears(today.Year - dateOfBirth.Year) ? 1 : 0)
                : (int?)null;

            result.AppendLine($"Student {student.StudentId}: {student.FirstName} {student.LastName}, School: {student.School}, Gender: {student.Gender}, Born: {student.DateOfBirth?.ToString("yyyy-MM-dd") ?? "not recorded"}, Age: {age?.ToString() ?? "not recorded"}");
        }
        return result.ToString();
    }

    public async Task<string> GetAllStudentsAsync() {
        // Query the database for all students
        var students = await _dbContext.Set<Student>().ToListAsync();

        if (students.Count == 0)
            return "No students found.";

        var result = new StringBuilder();

        foreach (var student in students) {
            result.AppendLine($"Student {student.StudentId}: {student.FirstName} {student.LastName}, School: {student.School}, Gender: {student.Gender}, Status: {student.Status ?? "not recorded"}");
        }
        return result.ToString();
    }

    public async Task<string> ProcessWithdrawalAsync(int studentId, string reason) {
        // Business logic to process the withdrawal
        var student = await _dbContext.Set<Student>().FindAsync(studentId);

        if (student == null)
            return "Student not found.";

        // Assuming we have a property to track return status for the student
        student.Status = "Withdrawal Initiated";

        await _dbContext.SaveChangesAsync();

        return $"Withdrawal initiated for student {studentId}.";
    }
}

Create an agent service named AgentService inside the Services folder with this code:

public class AgentService {
    private readonly SchoolDbContext _db;

    public AgentService(SchoolDbContext db) {
        _db = db;
    }

    public async Task<string> AskAsync(string prompt) {
        var client = new CopilotClient(
            new CopilotClientOptions {
                LogLevel = CopilotLogLevel.Info
            });

        await client.StartAsync();

        var toolService = new StudentsAgentTools(_db);

        var tools = new List<AIFunctionDeclaration> {
            AIFunctionFactory.Create(
                async (int studentId) =>
                    await toolService.GetStudentDetailsByIdAsync(studentId),
                "get_student_details",
                "Look up student details."),

            AIFunctionFactory.Create(
                async (int studentId, string reason) =>
                    await toolService.ProcessWithdrawalAsync(studentId, reason),
                "process_withdrawal",
                "Process a withdrawal request."),

            AIFunctionFactory.Create(
                async (string gender) =>
                    await toolService.GetStudentsByGenderAsync(gender),
                "get_students_by_gender",
                "Find students by gender"),

            AIFunctionFactory.Create(
                async (string school) =>
                    await toolService.GetStudentsBySchoolAsync(school),
                "get_students_by_school",
                "Find students by school"),

            AIFunctionFactory.Create(
                async () =>
                    await toolService.GetStudentsByAgeAsync(),
                "get_students_by_age",
                "Find students by age"),

            AIFunctionFactory.Create(
                async () =>
                    await toolService.GetAllStudentsAsync(),
                "get_all_students",
                "Get all students")
        };

        var config = new SessionConfig {
            Model = "kimi-k3",
            OnPermissionRequest = PermissionHandler.ApproveAll,
            Tools = tools
        };

        var session = await client.CreateSessionAsync(config);

        var responseBuilder = new StringBuilder();

        var tcs = new TaskCompletionSource<string>();

        session.On<SessionEvent>(evt => {
            switch (evt) {
                case AssistantMessageEvent msg:
                    responseBuilder.Append(msg.Data.Content);
                    break;

                case SessionIdleEvent:
                    tcs.SetResult(responseBuilder.ToString());
                    break;
            }
        });

        await session.SendAsync(new MessageOptions {
            Prompt = prompt
        });

        return await tcs.Task.WaitAsync(
            TimeSpan.FromSeconds(30));
    }
}

Add these services to Program.cs:

builder.Services.AddDbContext<SchoolDbContext>(options =>
    options.UseSqlite(
        builder.Configuration.GetConnectionString("DefaultConnection")));
        
builder.Services.AddScoped<AgentService>();

Now we can add a migration using the dotnet-ef tool. To add this tool, run the following terminal window command:

dotnet tool install -g dotnet-ef

Thereafter, run this command from a terminal window inside the root folder of your C# project:

dotnet ef migrations add M1 -o Data/Migrations

We will create the database with sample student data with the following command:

dotnet ef database update

At this stage you will notice that a database file named school-db.sqlite has been created in the project.

Building the Blazor UI

Add Components/Pages/Agent.razor with this code:

@page "/agent"
@rendermode InteractiveServer
@using AI4SchoolAgent.Services
@inject AgentService AgentService

<PageTitle>School AI Agent</PageTitle>

<h3>School Administration AI Agent</h3>

@if (IsBusy) {
    <p class="alert alert-info mt-3" role="status">Thinking...</p>
}

<div class="chat-window">
    @foreach (var message in Messages) {
        <div class="message">
            <b>@message.Role:</b>
            <div>@message.Content</div>
        </div>
    }
</div>

<div class="mt-3">
    <InputTextArea class="form-control" rows="4" @bind-Value="Prompt" />

    <button class="btn btn-primary mt-2" @onclick="SendPrompt" disabled="@IsBusy">
        Ask Agent
    </button>
</div>

@if (!string.IsNullOrEmpty(ErrorMessage)) {
    <div class="alert alert-danger mt-3" role="alert">@ErrorMessage</div>
}

@code {
    string Prompt = "";
    bool IsBusy;
    string? ErrorMessage;
    List<ChatMessage> Messages = new();

    async Task SendPrompt() {
        if (string.IsNullOrWhiteSpace(Prompt))
            return;

        Messages.Add(new ChatMessage {
            Role = "User",
            Content = Prompt
        });

        IsBusy = true;
        ErrorMessage = null;

        try {
            var result = await AgentService.AskAsync(Prompt);

            Messages.Add(new ChatMessage {
                Role = "Agent",
                Content = result
            });

            Prompt = "";
        } catch (Exception ex) {
            ErrorMessage = $"Unable to get a response: {ex.Message}";
        } finally {
            IsBusy = false;
        }
    }

    class ChatMessage {
        public string Role { get; set; } = "";
        public string Content { get; set; } = "";
    }
}

Add styling to Components/Pages/Agent.razor.css:

.chat-window {
    border: 1px solid #ddd;
    height: 500px;
    overflow-y: auto;
    padding: 10px;
    background-color: #fafafa;
}

.message {
    margin-bottom: 15px;
    padding: 10px;
    border-radius: 6px;
    background-color: white;
}

Add a menu item to the app’s navigation. Open Components/Layout/NavMenu.razor in the editor. Add the following before the </nav> closing tag:

<div class="nav-item px-3">
  <NavLink class="nav-link" href="agent">
    <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Agent
  </NavLink>
</div>

I got the following response for prompt: “Who is the oldest student in the school of medicine?”:

I'll help you find the oldest student in the School of Medicine. Let me first look 
up the available student tools.Let me get the list of students in the School of
Medicine.No exact match — let me list all students to check the school names.
I found five students in Medicine. Let me check each one's details to find the oldest.
The oldest student in the School of Medicine is **Dan Ash** (Student ID: 8),
who is **32 years old**, born on March 19, 1994. For reference, here are all the Medicine students by age: 1. **Dan Ash** — 32 (born 1994-03-19) 2. Cat Yao — 32 (born 1994-06-28, slightly younger) 3. Deb Roy — 30 4. Mat Tan — 28 5. Mia Chu — 25 While both Dan Ash and Cat Yao are 32 years old, Dan Ash is the older of the two
by birth date. Is there anything else I can help you with?

Conclusion

We now have an agent that can work independently to extract information for a database and use it to accomplish a mission.

Monday, November 9, 2026

Scaffold Interactive-Server Blazor CRUD pages with SQLite

In this walkthrough, we will use the scaffolding tool to create the CRUD pages for a data driven Interactive-Server Blazor app. The app connects directly with SQLite database using Entity Framework Core.

Overview

Blazor is a framework for developing interactive client-side web applications using C# instead of JavaScript.

Architecture

The architecture of the application that we will be building will look like this: 

ASP.NET Core hosts the server-side app and sets up SignalR endpoints where clients connect. SignalR is responsible for updating the DOM on the client with any changes. The Blazor application on the server connects directly to the database using Entity Framework Core.

Blazor Render Modes

NameDescriptionRender LocationInteractive
Static ServerStatic server-side rendering (static SSR)Server❌
Interactive ServerInteractive server-side rendering (interactive SSR) using Blazor Server.Server✔️
Interactive WASMClient-side rendering (CSR) using Blazor WebAssembly.Client✔️
Interactive AutoInteractive SSR using Blazor Server initially and then CSR on subsequent visits after the Blazor bundle is downloaded.Server, then client✔️

To apply a render mode to a component, use the @rendermode directive on the component instance or on the component definition. Example:

<Dialog @rendermode="InteractiveServer" />

In this post, we will build a Server-side Blazor app talks directly to a SQLite database. This is a very realistic option since both blazor and the database server run on the server.

Let's get coding

In a terminal window, go to a work directory. Enter the following command to create a Server-Side Blazor application inside a directory named BlazorEF: 

dotnet new blazor -o BlazorEF
cd BlazorEF
mkdir Models
mkdir Data

Open the BlazorEF folder in Visual Studio Code.

When you run the app, your default browser will load a page that looks like this: 

We will extend the above application so that it talks to SQLite using Entity Framework Core. To this end, we will be dealing with a very simple Student model. Therefore, add a Student.cs class file to the Models folder with the following C# content: 

public class Student {
    public int StudentId { get; set; }

    [Required]
    public String? FirstName { get; set; }

    [Required]
    public String? LastName { get; set; }

    [Required]
    public String? School { get; set; }

    [Required]
    public String? Gender { get; set; }

    public DateOnly? DateOfBirth { get; set; }
}

Since we will be using SQLite, we will need to add the appropriate Entity Framework Core packages to our project. From within a terminal window at the root of your BlazorEF project, run the following commands to add the appropriate database related packages: 

dotnet add package Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore
dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package Microsoft.EntityFrameworkCore.Design

We need to add a connection string for the SQLite database. Add the following to the appsettings.json file: 

"ConnectionStrings": {
  "DefaultConnection": "DataSource=college.db;Cache=Shared;"
}

We will be using the Entity Framework Code First approach. 

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. Student data from this link will be used.

The starting point is to create a database context class. Add a C# class file named SchoolDbContext.cs in the Data folder with the following C# code: 

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() {
        const string studentsUrl =
            "https://gist.githubusercontent.com/medhatelmasry/2ae7a36d5392f862b0d1039b2a52b9b4/raw/45533eda6c43ce439dbc65c37a7fbdef01546c2d/students.json";

        using var httpClient = new HttpClient();

        var json = httpClient.GetStringAsync(studentsUrl).GetAwaiter().GetResult();

        return System.Text.Json.JsonSerializer.Deserialize<List<Student>>(json)
            ?? throw new InvalidOperationException("The students JSON returned no data.");
    }
}

Notice the above code will seed Student data into the database.

In the Program.cs file, just before ‘var app = builder.Build();’, add the following code so that our application can use SQLite:

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");

builder.Services.AddDbContext<SchoolDbContext>(
    options => options.UseSqlite(connectionString)
);

We are now ready to apply Entity Framework migrations, create the database and seed data. If you have not done so already, you will need to globally install the Entity Framework CLI tool. This tooling is installed globally on your computer by running the following command in a terminal window:

dotnet tool install --global dotnet-ef

To make sure nothing is broken, build your project with "dotnet build" before proceeding. Then, from within a terminal window inside the BlazorEF root directory, run the following command to create migrations: 

dotnet ef migrations add M1 -o Data/Migrations

 This results in the creation of a migration file ending with the name ....M1.cs in the Data/Migrations folder. In my case, this file looked like this: 

Note that the above code also includes commands for inserting sample data.

The next step is to create the SQLite college.db database file. To automatically apply migrations, add the following code to Program.cs, right before the final app.Run() statement:

using (var scope = app.Services.CreateScope()) {
  var services = scope.ServiceProvider;

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

  context.Database.Migrate();
}

We will scaffold the CRUD pages for students using the scaffold tool. To install the scaffold tool globally, enter this command in any terminal window:

dotnet tool install --global Microsoft.dotnet-scaffold

Thereafter, run the scaffold tool in the root folder of your Blazor project with:

dotnet scaffold 

Follow these steps:

Delete this unnecessary addition in the appsettings.json file:

"SchoolDbContext": "Data Source=SchoolDbContext.db"

You will notice these razor components have been added to your Blazor project:

Add this menu item to your Components/Layout/NavMenu.razor file.

<div class="nav-item px-3">
    <NavLink class="nav-link" href="students">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Students
    </NavLink>
</div>

Run your application:

You will discover that Student CRUD operations work seamlessly.

I hope you learned something new in this tutorial and trust that you will build much more sophisticated Blazor apps than this.

Monday, October 12, 2026

Seed & Extend Identity Users & Roles in ASP.NET with Scaffold tool

In this tutorial, we will learn how to add more data fields to the standard ASP.NET users & roles schema using the scaffold tool. We will also learn how to seed users and roles.

Prerequisites

To proceed with this tutorial, you need the following:

  • VS Code
  • .NET: The current version of .NET is 10.0
  • the dotnet-ef tool
  • Tthe Microsoft.dotnet-scaffold tool

Getting Started

Create a new razor pages application with the following terminal window command:

dotnet new razor --auth individual -o XtendUsersRoles
cd XtendUsersRoles
mkdir Models

This creates an ASP.NET app that uses SQLite database for authentication.

Open the application folder in VS Code.

Suppose we want to capture more data about the user, in addition to email and password. Keeping it simple, lwe will extend user data with FirstName & LastName.

An easy way to do this is to create a new class that extends IdentityUser and adds FirstName and LastName properties. In the Models folder, add a new class named XUser to it with the following class code: 

public class XUser : IdentityUser {
  public XUser() : base() { }

  public string? FirstName { get; set; }
  public string? LastName { get; set; }
}

We may also wish to extend the standard roles table with a CreatedDate property.

Just as we did with users, we will create another class for roles that inherits from IdentityRole. In the Models folder, add another class named XRole and add to it the following code:

public class XRole: IdentityRole {

  public XRole() : base() { }

  public XRole(string roleName) : base(roleName) { }

  public DateTime CreatedDate { get; set; }
}

Add the following to Pages/_ViewImports.cshtml:

@using XtendUsersRoles.Models

Edit Data/ApplicationDbContext.cs file and make ApplicationDbContext  inherit from IdentityDbContext<XUser, XRole, string>(options). The ApplicationDbContext class code will look like this:

public class ApplicationDbContext(
    DbContextOptions<ApplicationDbContext> options)
    : IdentityDbContext<XUser, XRole, string>(options)
{

}

Add these passwords to the appsettings.Development.json file:

"Passwords": {
  "Admin": "P@$$w0rd",
  "Member": "P@$$w0rd"
}

We will seed the database with two roles and two users. Add Data/IdentitySeeder.cs with the following code:

public static class IdentitySeeder {
  public static async Task SeedAsync(
      UserManager<XUser> userManager,
      RoleManager<XRole> roleManager,
      IConfiguration configuration) {

      ArgumentNullException.ThrowIfNull(userManager);
      ArgumentNullException.ThrowIfNull(roleManager);
      ArgumentNullException.ThrowIfNull(configuration);

      await EnsureRoleAsync(roleManager, "Admin");
      await EnsureRoleAsync(roleManager, "Member");

      await EnsureUserAsync(
          userManager, configuration["Passwords:Admin"]!, "aa@aa.aa", "Adam", "Atkins", "Admin");

      await EnsureUserAsync(

          userManager, configuration["Passwords:Member"]!, "mm@mm.mm", "Mike", "Moore", "Member");
  }

  private static async Task EnsureRoleAsync(RoleManager<XRole> roleManager, string roleName) {
      if (!await roleManager.RoleExistsAsync(roleName)) {
          var result = await roleManager.CreateAsync(new XRole(roleName) {
              CreatedDate = DateTime.UtcNow
          });

          EnsureSucceeded(result, $"creating role '{roleName}'");
      }
  }

  private static async Task EnsureUserAsync(
      UserManager<XUser> userManager,
      string password,
      string email,
      string firstName,
      string lastName,
      string roleName) {

      var user = await userManager.FindByEmailAsync(email);

      if (user is null) {
          user = new XUser {
              UserName = email,
              Email = email,
              EmailConfirmed = true,
              FirstName = firstName,
              LastName = lastName
          };

          var result = await userManager.CreateAsync(user, password);
          EnsureSucceeded(result, $"creating user '{email}'");
      }

      if (!await userManager.IsInRoleAsync(user, roleName)) {
          var result = await userManager.AddToRoleAsync(user, roleName);
          EnsureSucceeded(result, $"adding user '{email}' to role '{roleName}'");
      }

  }

  private static void EnsureSucceeded(IdentityResult result, string operation) {
      if (!result.Succeeded) {
          var errors = string.Join("; ", result.Errors.Select(error => $"{error.Code}: {error.Description}"));

          throw new InvalidOperationException($"Identity seeding failed while {operation}: {errors}");
      }
  }
}

In the Program.cs, replace the builder.Services.AddDefaultIdentity. . .  statement with this:

builder.Services.AddIdentity<XUser, XRole>(
options => {
    options.Stores.MaxLengthForKeys = 128;
})
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultUI()
.AddDefaultTokenProviders()
.AddRoles<XRole>();

We need to call the identity seed logic from somewhere. In Program.cs, Add the following code to the “if (app.Environment.IsDevelopment())” block, right before “app.UseMigrationsEndPoint()”:

await using var scope = app.Services.CreateAsyncScope();
var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
await dbContext.Database.MigrateAsync();

await IdentitySeeder.SeedAsync(
    scope.ServiceProvider.GetRequiredService<UserManager<XUser>>(),
    scope.ServiceProvider.GetRequiredService<RoleManager<XRole>>(),
    app.Configuration);

Edit Pages/Shared/_LoginPartial.cshtml and change:

@inject SignInManager<IdentityUser> SignInManager
@inject UserManager<IdentityUser> UserManager

TO

@inject SignInManager<XUser> SignInManager
@inject UserManager<XUser> UserManager

Let us start with a clean database and migration. Therefore, delete app.db and the Data/Migrations folder. 

If you do not already have the .NET entity framework tool, execute the following command from within a terminal window:

dotnet tool install -g dotnet-ef

Then, execute the following entity framework migration commands from within a terminal window in the root folder of the application:

dotnet ef migrations add M1 -o Data/Migrations
dotnet ef database update

To seed the database with sample roles and users, start the application with:

dotnet watch

To prove that user and role data are successfully seeded, login with one of the below credentials that were previously seeded:

EmailPassword
aa@aa.aa P@$$w0rd
mm@mm.mm P@$$w0rd

The next task we need to accomplish is to modify the registration page so that the application can capture extended data such as FirstName & LastName. ASP.NET provides ASP.NET Core Identity as a Razor Class Library. This means that the registration UI is baked into the assemblies and is surfaced with the .AddDefaultUI() option with the services.AddIdentity() command in Program.cs.

If you do not already have the .NET scaffolding tool, execute the following command from within a terminal window:

dotnet tool install -g Microsoft.dotnet-scaffold

To expose the identity pages (like LOgin, Register, Logout, etc) and change them, we will use the Scaffold tool. Run the following command from within a terminal window at the root of your project:

dotnet scaffold

Follow these steps to generate the Identity razor pages:


The result of the scaffolding process is that we now have a new folder /Areas/Identity/Pages/Account with many pages that pertains to Identity:

There are, however, some things that the scaffold tool did incorrectly:

  1. It added an ApplicationDbContext connection string in appsettings.json file. Go ahead and delete it.
  2. The scaffold tool also added this line of code into Program.cs, that also needs to be deleted:

builder.Services.AddDefaultIdentity<ApplicationUser>(options => options.SignIn.RequireConfirmedAccount = true).AddEntityFrameworkStores<ApplicationDbContext>();

Edit the code-behind file Areas/Identity/Pages/Account/Register.cshtml.cs. Add the following properties to the InputModel class: 

[Required]
[DataType(DataType.Text)]
[StringLength(50, ErrorMessage = "The {0} must be at least {2} and at max {1} characters long.", MinimumLength = 2)]
[Display(Name = "First Name")]
public string? FirstName { get; set; }

[Required]
[DataType(DataType.Text)]
[StringLength(50, ErrorMessage = "The {0} must be at least {2} and at max {1} characters long.", MinimumLength = 2)]
[Display(Name = "Last Name")]
public string? LastName { get; set; }

In the same file, delete the CreateUser() method.

In the OnPostAsync() method at around line 128, replace:

var user = CreateUser();

with: 

var user = new XUser {
  UserName = Input.Email,
  Email = Input.Email,
  FirstName = Input.FirstName,
  LastName = Input.LastName
};

In the same Register.cshtml.cs file, replace all instances of ApplicationUser with XUser. Do this also in files Login.cshtml.cs and Logout.cshtml.cs.

Next, let us update the UI. Edit razor page Areas\Identity\Pages\Account\Register.cshtml. Add the following markup to the form right before the email/username block: 

<div class="form-floating mb-3">
    <input asp-for="Input.FirstName" class="form-control" aria-required="true" placeholder="first name" />
    <label asp-for="Input.FirstName">First Name</label>
    <span asp-validation-for="Input.FirstName" class="text-danger"></span>
</div>

<div class="form-floating mb-3">
    <input asp-for="Input.LastName" class="form-control" aria-required="true" placeholder="last name" />
    <label asp-for="Input.LastName">Last Name</label>
    <span asp-validation-for="Input.LastName" class="text-danger"></span>
</div>

Run the web application and click on the Register button on the top-right side.


After you click on Register, all user data will be saved in the database. We can capture first name and last name as expected. 

We have succeeded in updating the registration page so that additional user data can be captured. Mission accomplished.

Monday, October 5, 2026

ASP.NET 10.0 Minimal WebAPI with SQLite & Swagger

This tutorial is about using ASP.NET 10.0 Minimal WebAPI. We will build a simple application with SQLite to save students data. We will then consume the API from an HTML page and add a Swagger interface to test the API endpoints.

Requirements:

  • .NET 10.0
  • C# Dev Kit VS Code Extenstion

In a suitable working directory, create a Web API web application in the terminal window with:

dotnet new webapi -o StudentsMinApi 
cd StudentsMinApi
mkdir Data
mkdir Models
mkdir wwwroot code . dotnet watch

This will appear in your terminal window:

Point your browser to the URL displayed in the terminal window, followed by /weatherforecast.

In the above case the address would be http://localhost:5130/weatherforecast. This would display the following in your browser:

Look at the API code in Program.cs:

app.MapGet("/weatherforecast", () => {
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

Add this Entity Framework 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 Swagger: 

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 Swashbuckle.AspNetCore

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; }
    public string? Gender { get; set; }
    public DateTime? DateOfBirth { 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/2ae7a36d5392f862b0d1039b2a52b9b4 and save it into a text file wwwroot/students.csv.

Add the following connection string to your  appsettings.json file:

"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 ApplicationDbContext with the following content: 

public class ApplicationDbContext : DbContext {

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

    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> 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.json" };
        var filePath = Path.Combine(p);

        var json = File.ReadAllText(filePath);
        var data = System.Text.Json.JsonSerializer.Deserialize<List<Student>>(json) ?? new List<Student>();

        return data;
    }

}

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

We need to register the context class (ApplicationDbContext) 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<ApplicationDbContext>(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 student data by id
  • Add student data
  • Update student data
  • Delete student data

This can easily be done using the scaffold tool. Make sure you install the tool globally with this terminal window command:

dotnet tool install --global Microsoft.dotnet-scaffold

Once you have installed the scaffold tool, enter the following command to start the tool at the root of your project:

dotnet scaffold

Make the choices as shown in the various steps below:

 

A file named StudentsApi.cs gets created in the root folder of your project with this code:

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.EntityFrameworkCore;
using StudentsMinApi.Data;
using StudentsMinApi.Models;

public static class StudentsApi {
    public static void MapStudentEndpoints(this IEndpointRouteBuilder routes) {
        var group = routes.MapGroup("/api/Student").WithTags(nameof(Student));

        group.MapGet("/", async (ApplicationDbContext db) => {
            return await db.Students.ToListAsync();
        })
        .WithName("GetAllStudents");

        group.MapGet("/{id}", async Task<Results<Ok<Student>, NotFound>> (int studentid, ApplicationDbContext db) => {
            return await db.Students.AsNoTracking()
                .FirstOrDefaultAsync(model => model.StudentId == studentid)
                is Student model
                    ? TypedResults.Ok(model)
                    : TypedResults.NotFound();
        })
        .WithName("GetStudentById");

        group.MapPut("/{id}", async Task<Results<Ok, NotFound>> (int studentid, Student student, ApplicationDbContext db) => {
            var affected = await db.Students
                .Where(model => model.StudentId == studentid)
                .ExecuteUpdateAsync(setters => setters
                .SetProperty(m => m.StudentId, student.StudentId)
                .SetProperty(m => m.LastName, student.LastName)
                .SetProperty(m => m.FirstName, student.FirstName)
                .SetProperty(m => m.School, student.School)
                .SetProperty(m => m.Gender, student.Gender)
                .SetProperty(m => m.DateOfBirth, student.DateOfBirth)
        );

            return affected == 1 ? TypedResults.Ok() : TypedResults.NotFound();
        })
        .WithName("UpdateStudent");

        group.MapPost("/", async (Student student, ApplicationDbContext db) => {
            db.Students.Add(student);
            await db.SaveChangesAsync();
            return TypedResults.Created($"/api/Student/{student.StudentId}",student);
        })
        .WithName("CreateStudent");

        group.MapDelete("/{id}", async Task<Results<Ok, NotFound>> (int studentid, ApplicationDbContext db) => {
            var affected = await db.Students
                .Where(model => model.StudentId == studentid)
                .ExecuteDeleteAsync();

            return affected == 1 ? TypedResults.Ok() : TypedResults.NotFound();
        })
        .WithName("DeleteStudent");
    }
}

Note the following mapping code in your Program.cs file:

app.MapStudentEndpoints();

You can start the WebAPI app and view all students at endpoint: /api/student.

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<ApplicationDbContext>();    
    context.Database.Migrate();
}

Adding Swagger Support

It is very easy to add Swagger support to our application so that we can test the various endpoints that our WebAPI application has to offer. 

Add the following code right under app.MapOpenApi():

app.UseSwaggerUI(options =>
{
        options.SwaggerEndpoint("/openapi/v1.json", "My WebAPI");
});

In file Properties/launchSettings.json, set the value of launchBrowser to true in two places:

"launchBrowser": true

Also, add the following property to both the http and https JSON blocks:

"launchUrl": "swagger"

Restart the app by typing dotnet watch in the terminal window. The app will automatically load into your default browser in a Swagger interfact that looks like this:

Go ahead and test all the available student endpoints.

You may encounter the following error when you try any of the endpoints that require an ID parameter - example: /api/Student/{id} endpoint:

This error can easily be resolved by targeting OpenAPI version 3. In Program.cs, replace "builder.Services.AddOpenApi();" with:

builder.Services.AddOpenApi(options => {
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});

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:5130/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 in the WebAPI 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:


The application should work as expected.

Congrats for coming this far.

Tuesday, September 29, 2026

docker-compose with MySQL and ASP.NET

This article discussed one approach to having your ASP.NET development environment work with MySQL running in a docker container.

Source code: https://github.com/medhatelmasry/AspMySQL

It is assumed that the following installed on your computer:

  1. .NET 10.0 
  2. Docker Desktop 
  3. ‘dotnet-ef’ tool 

Setting up MySQL docker container

To download a suitable MySQL image from Docker Hub and run it on your local computer, type the following command from within a terminal window:

docker run -d --name mysqldb -p 3333:3306 -e MYSQL_ROOT_PASSWORD=secret mysql:8.4

This starts a container named mysqldb that listens on port 3333 on your local computer. The root password is secret.

To ensure that the MySQL container is running, type the following from within a terminal window:

docker ps

You will see a message like the following:

CONTAINER ID   IMAGE       COMMAND                  CREATED       STATUS          PORTS                                         NAMES
4baa0ba99088   mysql:8.4   "docker-entrypoint.s…"   2 hours ago   Up 48 minutes   0.0.0.0:3333->3306/tcp, [::]:3333->3306/tcp   mysqldb

Creating our ASP.NET MVC App

Create an ASP.NET MVC app named AspMySQL with SQLite support by running the following terminal window commands:

dotnet new mvc --auth individual -o AspMySQL
cd AspMySQL

To run the web application and see what it looks like, enter the following command:

dotnet watch

The app starts in your default browser and looks like this:

We need a suitable MySQL Entity Framework driver. One such driver is the official MySQL driver from Oracle. Run this pair of commands to replace the SQLite driver with the Oracle MySQL driver:

dotnet remove package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package MySql.EntityFrameworkCore

Let us configure our web application so that the connection string can be constructed from environment variables. Open the Program.cs file in your favourite editor and comment out (or delete) the following statements around lines 8-10:

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlite(connectionString));

Replace the above code with the following:

var host = builder.Configuration["DBHOST"] ?? "localhost";
var port = builder.Configuration["DBPORT"] ?? "3333";
var password = builder.Configuration["DBPASSWORD"] ?? "secret";
var db = builder.Configuration["DBNAME"] ?? "aspnetDB";
var user = builder.Configuration["DBUSER"] ?? "root";

string connectionString = $"Server={host};Port={port};Database={db};User={user};Password={password};";

builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseMySQL(connectionString));

Five environment variables are used in the database connection string. These are: DBHOST, DBPORT , DBPASSWORD, DBNAME and DBUSER. If these environment variables are not found then they will take on default values: localhost, 3333, secret, aspnetDB and root respectively.

Go ahead and delete the connection string from appsettings.json as it is not needed anymore:

"ConnectionStrings": {
  "DefaultConnection": "DataSource=app.db;Cache=Shared"
},

Entity Framework Migrations

We can instruct our application to automatically process any outstanding Entity Framework migrations. This is done by adding the following statement to Program.cs right before the last app.Run() statement:

using (var scope = app.Services.CreateScope()) {
    var services = scope.ServiceProvider;

    var context = services.GetRequiredService<ApplicationDbContext>();    
    context.Database.Migrate();
}

Since SQLite is different from MySQL, we must delete all migrations and re-create them. Therefore, follow these steps:

  1. delete the Data/Migrations folder.
  2. delete file: app.db
  3. create new migrations with this terminal window command: 

dotnet ef migrations add M1 -o Data/Migrations

Test app

Now, let's test our web app and see whether it can talk to the containerized MySQL database server. Run the web application with the following terminal command:

dotnet watch

Click on the Register link on the top right side.

The ASP.NET MVC user register page.

I entered an Email, Password and Confirm password, then clicked on the Register button. The website then displays the following page that requires that you confirm the email address:

Click on the “Click here to confirm your account” link. This leads you to a confirmation page:

Login with the email address and password that you registered with.

The message on the top right side confirms that the user was saved and that communication between the ASP.NET app and MySQL is working as expected.

Dockeri-zing app

We will generate the release version of the application by executing the following command from a terminal window in the root directory of the web app:

dotnet publish -o distrib

The above command instructs dotnet to produce the release version of the application in the distrib directory. When you inspect the distrib directory, you will see files like the following:

The highlighted file in the above image is the main DLL file that is the entry point into the web application. Let us run the DLL. To do this, change to the distrib directory, then run your main DLL file with:

cd distrib
dotnet AspMySQL.dll

This displays the familiar messages from the web server that the app is ready to be accessed from a browser. 

Hit CTRL C to stop the web server.

We now have a good idea about the ASP.NET artifacts that need to be copied into a container. 

In a terminal window, stop and remove the MySQL container with:

docker rm -f mysqldb

Return to the root directory of your project by typing the following in a terminal window:

cd ..

Docker image for web app

We need to create a docker image that will contain the .NET runtime. At the time of writing this article, the current version of .NET is 10.0.

We can exclude files from being copied into the container image. Add a file named .dockerignore in the root of the web application with this content:

**/.git
**/.gitignore
**/node_modules
**/npm-debug.log
**/.DS_Store
**/bin
**/obj
**/distrib **/.vs **/.vscode **/.env **/*.user **/*.suo **/.idea **/coverage **/.nyc_output **/docker-compose*.yml **/Dockerfile* **/.github **/README.md **/LICENSE

Create a text file named Dockerfile and add to it the following content:

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build

WORKDIR /src

# Copy project file and restore dependencies
COPY *.csproj .
RUN dotnet restore

# Copy source code
COPY . .

# Publish application
RUN dotnet publish -c Release -o /app/publish

# Runtime stage
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime

WORKDIR /app

COPY --from=build /app/publish .

ENV ASPNETCORE_URLS=http://+:80

EXPOSE 80
EXPOSE 443

# Run the application
ENTRYPOINT ["dotnet", "AspMySQL.dll"]

docker-compose.yml

We will next create a docker .yml file that orchestrates the entire system involving two containers: a MySQL database server and our web app. In the root folder of your application, create a text file named docker-compose.yml and add to it the following content:

volumes:
  mysqldata:

services:
  db:
    image: mysql:8.4
    volumes:
      - mysqldata:/var/lib/mysql
    #restart: always
    ports:
      - "3333:3306"
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_TCP_PORT: 3306
    healthcheck:
      test: [ "CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-uroot", "-psecret" ]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 30s

  webapp:
    build:
      context: .
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "7777:80"
    #restart: always
    environment:
      - DBHOST=db
      - DBPORT=3306
      - DBPASSWORD=secret
      - DBNAME=snoopyDB
      - DBUSER=root

Running the yml file

To find out if this all works, go to a terminal window at the root directory of the application and run the following command:

docker-compose up -d --build

Point your browser to http://localhost:7777/ and you should see the main web page. Register a user, confirm the email, and login. It should all work as expected.

Cleanup

Run the following command to shutdown docker-compose and cleanup:

docker-compose down -v

Conclusion

We have seen how straight forward and easy it is to containerize an application and its database with docker-compose.