.NET Aspire and Semantic Kernel AI

 Let's learn how to use the .NET Aspire Azure OpenAI client. We will familiarize ourselves with the Aspire.Azure.AI.OpenAI library, which is used to register an OpenAIClient in the dependency injection (DI) container for consuming Azure OpenAI or OpenAI functionality. In addition, it enables corresponding logging and telemetry.

Companion Video: https://youtu.be/UuLnCRdYvEI
Final Solution Code: https://github.com/medhatelmasry/AspireAI_Final

Pre-requisites:

• .NET 9.0
• Visual Studio Code
• .NET Aspire Workload
• "C# Dev Kit" extension for VS Code

Getting Started

We will start by cloning a simple C# solution that contains two projects that use Semantic Kernel - namely a console project (ConsoleAI) and a razor-pages project (RazorPagesAI). Clone the project in a working directory on your computer by executing these commands in a terminal window:

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

cd AspireAI

The cloned solution contains a console application (ConsoleAI) and a razor-pages application (RazorPagesAI). They both do pretty much do the same thing. The objective of today’s exercise is to:

• use .NET Aspire so that both projects get started from one place 
• pass environment variables to the console and razor-pages web apps from the .AppHost project that belongs to .NET Aspire

Open the solution in VS Code and update the values in the following appsettings.json files with your access parameters for Azure OpenAI and/or OpenAI:

ConsoleAI/appsettings.json

RazorPagesAI/appsettings.json

The most important settings are the connection strings. They are identical in both projects:

"ConnectionStrings": {

  "azureOpenAi": "Endpoint=Azure-OpenAI-Endpoint-Here;Key=Azure-OpenAI-Key-Here;",

  "openAi": "Key=OpenAI-Key-Here"

}

After you update your access parameters, try each application separately to see what it does:

Here is my experience using the console application (ConsoleAI) with AzureOrOpenAI set to “OpenAI”:

cd ConsoleAI

dotnet run

I then changed the AzureOrOpenAI setting to “Azure” and ran the console application (ConsoleAI) again:

Next, try the razor pages web application (RazorPagesAI) with AzureOrOpenAI set to “OpenAI”:

cd ../RazorPagesAI

dotnet watch

In the RazorPagesAI web app’s appsettings.json file, I changed AzureOrOpenAI to “Azure”, resulting in a similar experience.

In the root folder, add .NET Aspire to the solution:

cd ..

dotnet new aspire --force

Add the previous projects to the newly created .sln file with:

dotnet sln add ./AiLibrary/AiLibrary.csproj

dotnet sln add ./RazorPagesAI/RazorPagesAI.csproj

dotnet sln add ./ConsoleAI/ConsoleAI.csproj

Add the following .NET Aspire agent packages to the client ConsoleAI and RazorPagesAI projects with:

dotnet add ./ConsoleAI/ConsoleAI.csproj package Aspire.Azure.AI.OpenAI --prerelease

dotnet add ./RazorPagesAI/RazorPagesAI.csproj package Aspire.Azure.AI.OpenAI --prerelease

To add Azure hosting support to your IDistributedApplicationBuilder, install the 📦 Aspire.Hosting.Azure.CognitiveServices NuGet package in the .AppHost project:

dotnet add ./AspireAI.AppHost/AspireAI.AppHost.csproj package Aspire.Hosting.Azure.CognitiveServices

In VS Code, add the following references:

1. Add a reference from the .AppHost project into ConsoleAI project.
2. Add a reference from the .AppHost project into RazorPagesAI project.
3. Add a reference from the ConsoleAI project into .ServiceDefaults project.
4. Add a reference from the RazorPagesAI project into .ServiceDefaults project.

Copy the AI and ConnectionStrings blocks from either the console (ConsoleAI) or web app (RazorPagesAI)  appsettings.json file into the appsettings.json file of the .AppHost project. The appsettings.json file in the .AppHost project will look similar to this:

"AI": {

  "AzureOrOpenAI": "OpenAI",

  "OpenAiChatModel": "gpt-3.5-turbo",

  "AzureChatDeploymentName": "gpt-35-turbo"

},

"ConnectionStrings": {

  "azureOpenAi": "Endpoint=Azure-OpenAI-Endpoint-Here;Key=Azure-OpenAI-Key-Here;",

  "openAi": "Key=OpenAI-Key-Here"

}

Add the following code to the Program.cs file in the .AppHost project just before builder.Build().Run(): 

IResourceBuilder<IResourceWithConnectionString> openai;

var AzureOrOpenAI = builder.Configuration["AI:AzureOrOpenAI"] ?? "Azure"; ;

var chatDeploymentName = builder.Configuration["AI:AzureChatDeploymentName"];

var openAiChatModel = builder.Configuration["AI:OpenAiChatModel"];

 

// Register an Azure OpenAI resource. 

// The AddAzureAIOpenAI method reads connection information

// from the app host's configuration

if (AzureOrOpenAI.ToLower() == "azure") {

    openai = builder.ExecutionContext.IsPublishMode

        ? builder.AddAzureOpenAI("azureOpenAi")

        : builder.AddConnectionString("azureOpenAi");

} else {

    openai = builder.ExecutionContext.IsPublishMode

        ? builder.AddAzureOpenAI("openAi")

        : builder.AddConnectionString("openAi");

}

 

// Register the RazorPagesAI project and pass to it environment variables.

//  WithReference method passes connection info to client project

builder.AddProject<Projects.RazorPagesAI>("razor")

    .WithReference(openai)

    .WithEnvironment("AI__AzureChatDeploymentName", chatDeploymentName)

    .WithEnvironment("AI__AzureOrOpenAI", AzureOrOpenAI)

    .WithEnvironment("AI_OpenAiChatModel", openAiChatModel);

 

 // register the ConsoleAI project and pass to it environment variables

builder.AddProject<Projects.ConsoleAI>("console")

    .WithReference(openai)

    .WithEnvironment("AI__AzureChatDeploymentName", chatDeploymentName)

    .WithEnvironment("AI__AzureOrOpenAI", AzureOrOpenAI)

    .WithEnvironment("AI_OpenAiChatModel", openAiChatModel);

We need to add .NET Aspire agents in both our console and web apps. Let us start with the web app. Add this code to the Program.cs file in the RazorPagesAI project right before “var app = builder.Build()”: 

builder.AddServiceDefaults();

In the same Program.cs of the web app (RazorPagesAI), comment out the if (azureOrOpenAi.ToLower() == "openai") { …. } else { ….. } block and replace it with this code:

if (azureOrOpenAi.ToLower() == "openai") {

    builder.AddOpenAIClient("openAi");

    builder.Services.AddKernel()

        .AddOpenAIChatCompletion(openAiChatModel);

} else {

    builder.AddAzureOpenAIClient("azureOpenAi");

    builder.Services.AddKernel()

        .AddAzureOpenAIChatCompletion(azureChatDeploymentName);

}

In the above code, we call the extension method to register an OpenAIClient for use via the dependency injection container. The method takes a connection name parameter. Also, register Semantic Kernel with the DI. 

Also, in the Program.cs file in the ConsoleAI project, add this code right below the using statements:

var hostBuilder = Host.CreateApplicationBuilder();

hostBuilder.AddServiceDefaults();

In the same Program.cs of the console app (ConsoleAI), comment out the if (azureOrOpenAi.ToLower() == "azure") { …. } else { ….. } block and replace it with this code:

if (azureOrOpenAI.ToLower() == "azure") {

    var azureChatDeploymentName = config["AI:AzureChatDeploymentName"] ?? "gpt-35-turbo";

    hostBuilder.AddAzureOpenAIClient("azureOpenAi");

    hostBuilder.Services.AddKernel()

        .AddAzureOpenAIChatCompletion(azureChatDeploymentName);

} else {

    var openAiChatModel = config["AI:OpenAiChatModel"] ?? "gpt-3.5-turbo";

    hostBuilder.AddOpenAIClient("openAi");

    hostBuilder.Services.AddKernel()

        .AddOpenAIChatCompletion(openAiChatModel);

}

var app = hostBuilder.Build();

Replace “var kernel = builder.Build();” with this code:

var kernel = app.Services.GetRequiredService<Kernel>();

app.Start();

You can now test that the .NET Aspire orchestration of both the Console and Web apps. Stop all applications, then, in a terminal window,  go to the .AppHost project and run the following command:

dotnet watch

You will see the .NET Aspire dashboard:

Click on Views under the Logs column. You will see this output indicating that the console application ran successfully:

Click on the link for the web app under the Endpoints column. It opens the razor pages web app in another tab in your browser. Test it out and verify that it works as expected.

Stop the .AppHost application, then comment out the AI and ConneectionStrings blocks in the appsettings.json files in both the console and web apps. If you run the .AppHost project again, you will discover that it works equally well because the environment variables are being passed from the .AppHost project into the console and web apps respectively.

One last refinement we can do to the console application is do away with the ConfigurationBuilder because we can get a configuration object from the ApplicationBuilder. Therefore, comment out the following code in the console application:

var config = new ConfigurationBuilder()

    .SetBasePath(Directory.GetCurrentDirectory())

    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)

    .Build();

Replace the above code with the following:

var config = hostBuilder.Configuration;

You can delete the following package from the ConsoleAI.csproj file:

<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.0" />

Everything works just as it did before.

Using Dependency Injection with Sematic Kernel in ASP.NET

Overview

In this video I will show you how you Dependency Inject can be used with Semantic Kernel in an ASP.NET Razor Pages application. The same principals can be used with MVC. We will use the Phi-3 model hosted on GitHub. Developers can use a multitude of AI models on GitHub for free.

Source Code: https://github.com/medhatelmasry/AspWithSkDI
Companion Video: https://youtu.be/fLIWCkxXaM8

Pre-requisites

This walkthrough was done using .NET 8.0.

Getting Started

There are many AI models at GitHub from a variety of vendors that you can choose from. The starting point is to visit https://github.com/marketplace/models. At the time of writing, these are a subset of the models available:

For this article, I will use the "Phi-3.5-mini instruct (128k)" model highlighted above. If you click on that model you will be taken to the model's landing page:

Click on the green "Get started" button.

The first thing we need to do is get a 'personal access token' by clicking on the indicated button above.

Choose 'Generate new token', which happens to be in beta at the time of writing.

Give your token a name, set the expiration, and optionally describe the purpose of the token. Thereafter, click on the green 'Generate token' button at the bottom of the page.

Copy the newly generated token and place it is a safe place because you cannot view this token again once you leave the above page. 

Let's use Semantic Kernel in ASP.NET Razor Pages

In a working directory, create a Razor Pages web app named AspWithSkDI inside a terminal window with the following command:

dotnet new razor -n AspWithSkDI

Change into the newly created directory GitHubAiModelSK with:

cd AspWithSkDI

Next, let's add the Sematic Kernel package to our application with:

dotnet add package Microsoft.SemanticKernel -v 1.25.0

Open the project in VS Code and add this directive to the .csproj file right below: <Nullable>enable</Nullable>:

<NoWarn>SKEXP0010</NoWarn>

Add the following to appsettings.json:

    "AI": {

      "Endpoint": "https://models.inference.ai.azure.com",

      "Model": "Phi-3.5-mini-instruct",

      "PAT": "fake-token"

    }

Replace "fake-token" with the personal access token that you got from GitHub. 

Adding Dependency Injection support

Next, open Program.cs in an editor. Add the following code right above the statement "var app = builder.Build();" :

var modelId = builder.Configuration["AI:Model"]!;

var uri = builder.Configuration["AI:Endpoint"]!;

var githubPAT = builder.Configuration["AI:PAT"]!;

var client = new OpenAIClient(new ApiKeyCredential(githubPAT), new OpenAIClientOptions { Endpoint = new Uri(uri) });

var kernel = builder.Services.AddKernel()

    .AddOpenAIChatCompletion(modelId, client);

It is the last statement above that is key to making Semantic Kernel available to all other classes through Dependency Injection.

ASP.NET Razor Pages

Pages/Index.cshtml.cs

Add the following instance variable and property to the code-behind file named Pages/Index.cshtml.cs:

private readonly Kernel _kernel;

[BindProperty]

public string? Reply { get; set; }

Replace the class constructor with the following:

public IndexModel(ILogger<IndexModel> logger, Kernel kernel) {

    _logger = logger;

    _kernel = kernel;

}

We can now get access to Semantic Kernel through the _kernel object.

Add the following OnPostAsync() method to the IndexModel class:

// action method that receives user prompt from the form

public async Task<IActionResult> OnPostAsync(string userPrompt) {

    // get a chat completion service

    var chatCompletionService = _kernel.GetRequiredService<IChatCompletionService>(); 

 

    // Create a new chat by specifying the assistant

    ChatHistory chat = new(@"

        You are an AI assistant that helps people find information about baking. 

        The baked item must be easy, tasty, and cheap. 

        I don't want to spend more than $10 on ingredients.

        I don't want to spend more than 30 minutes preparing.

        I don't want to spend more than 30 minutes baking."

    ); 

 

    chat.AddUserMessage(userPrompt); 

 

    var response = await chatCompletionService.GetChatMessageContentAsync(chat, kernel: _kernel); 

 

    Reply = response.Content!.Replace("\n", "<br>"); 

 

    return Page();

}

In the above OnPostAsync() method, the user prompt is received and passed on to the Phi-3 GPT SLM model. In this case our assistant specializes suggests easy, fast and cheap baking ideas.

Pages/Index.cshtml

The Index.cshtml file represents the view that the user sees when interacting with our web app. Replace the content of Index.cshtml with the following:

@page

@model IndexModel

@{

    ViewData["Title"] = "SK Dependency Injection in ASP.NET Razor Pages";

}

<div class="text-center">

    <h3 class="display-6">@ViewData["Title"]</h3>

    <form method="post" onsubmit="showPleaseWaitMessage()">

        <input type="text" name="userPrompt" size="80" 

            required placeholder="What do you want to bake today?"/>

        <input type="submit" value="Submit" />

    </form>

</div>

<p>&nbsp;</p>

<div id="please-wait-message" style="display:none;">

    <p class="alert alert-info">Please wait...</p>

</div>

<div id="response-message">

    @if (Model.Reply != null) {

        <p class="alert alert-success">@Html.Raw(Model.Reply)</p>

    }

</div>

@section Scripts {

    <script>

        function showPleaseWaitMessage() {

    document.getElementById('response-message').innerHTML = '';      
    document.getElementById('please-wait-message').style.display = 'block';        }

    </script>

}

There is some JavaScript that was added to the view to display a "Please wait ...." message while the user waits for the AI model to respond.

Run the application

In a terminal window in the root of the application, run the following command:

dotnet watch

The home page of the web app displays in your default browser and it looks like this:

I entered "Apple Pie" then clicked on Submit. A "Please wait ..." message appeared while the AI model processed my request.

After about 40 seconds the response came back.

Conclusion

It is easy and straight forward to use dependency injection to create a kernel.

Using Mongo DB in an ASP.NET 8.0 Minimal Web API web app

 In this tutorial I will show you how to develop an ASP.NET 8.0 Minimal API application that interacts with MongoDB. In order to proceed you will need the following pre-requisites:

• Docker - used to host MongoDB. This is my preferred approach because it is quick and does not take too many resources on the host computer.
• .NET 8.0
• Visual Studio Code

The Database

Run the following command in a terminal window to start a MongoDB container named mdb:

docker run -p 27777:27017 --name mgo -d mongo:4.1.6

You can verify that the container is running by typing the following command in a terminal window:

docker ps -a

Let us start a bash session inside the container so that we can create a database and add some sample data to it. Enter the following command to start an interactive bash session inside the container:

docker exec -it mgo bash

We can then use the mongo command line interface (CLI) to create a database named school-db and then add some sample data to a collection of students. Type the following command:

mongo

This takes you into a mongo session command prompt. Enter the following command to create a database named school-db:

use school-db

Next, let's create a collection named students and add to it six sample students:

db.Students.insertMany(

[

  {'FirstName':'Sue','LastName':'Fox','School':'Business'},

  {'FirstName':'Tom','LastName':'Max','School':'Mining'},

  {'FirstName':'Ann','LastName':'Lee','School':'Nursing'},

  {'FirstName':'Joe','LastName':'Roy','School':'Tourism'},

  {'FirstName':'Jan','LastName':'Ash','School':'Communications'},

  {'FirstName':'Eva','LastName':'Day','School':'Medicine'},

]);

You can retrieve the list of students with the following command:

db.Students.find().pretty();

To exit the mongo command prompt by typing:

exit

You can also exit the bash session and return to the host operating system by typing:

exit

Creating an ASP.NET 8.0 Minimal Web API application

Create an ASP.NET 8.0 Minimal Web API application. This is accomplished by entering this command:

dotnet new webapi -f net8.0 -o AspMongoApi

Let's see what our application looks like. Run the application by executing:

cd AspMongoApi

dotnet run

The above command builds and runs the application in a web server. Point your browser to https://localhost:????/weatherforecast (Where ???? is your port number). This is what you should see:

Stop the web server by hitting CTRL+C on the keyboard.

Building the Students API

Add the MongoDB driver Nuget package with the following command:

dotnet add package MongoDB.Driver

Now that we have the driver, we can proceed with coding our Minimal API. I will use Visual Studio Code because it is operating system agnostic. To load your application workspace into VS Code, simply type in the following command from the root folder of your application:

code .

We need a Student class to represent the schema for student documents in a Students collection in the MongoDB school-db database. Create a Models folder. Inside the Models folder, add a file named Student.cs with the following code:

using MongoDB.Bson;

using MongoDB.Bson.Serialization.Attributes;

namespace AspMongoApi.Models;

public class Student {

    [BsonId]

    [BsonRepresentation(BsonType.ObjectId)]

    public string? Id { get; set; }

    public string? FirstName { get; set; }

    public string? LastName { get; set; }

    

    [BsonElement("School")]

    public string? Department { get; set; }

}

In the preceding class, the Id property:

• Is required for mapping the Common Language Runtime (CLR) object to the MongoDB collection.
• Is annotated with [BsonId] to designate this property as the document's primary key.
• Is annotated with [BsonRepresentation(BsonType.ObjectId)] to allow passing the parameter as type string instead of an ObjectId structure. Mongo handles the conversion from string to ObjectId.

The Department property is annotated with the [BsonElement] attribute. The attribute's value of School represents the property name in the MongoDB collection.

Add the following to appsettings.json:

"StudentDbSettings": {

"CollectionName": "Students",

"ConnectionString": "mongodb://localhost:27777",

"DatabaseName": "school-db"

},

The entire contents of appsettings.json will look like this:

{

  "StudentDbSettings": {

    "CollectionName": "Students",

    "ConnectionString": "mongodb://localhost:27777",

    "DatabaseName": "school-db"

  },

  "Logging": {

    "LogLevel": {

      "Default": "Information",

      "Microsoft.AspNetCore": "Warning"

    }

  },

  "AllowedHosts": "*"

}

Add StudentDbSettings.cs to the Models folder with this code:

namespace AspMongoApi.Models;

public class StudentsDbSettings {

    public string ConnectionString { get; set; } = null!;

    public string DatabaseName { get; set; } = null!;

    public string CollectionName { get; set; } = null!;

}

The above StudentDbSettings class is used to store the appsettings.json file's StudentDbSettings property values. The JSON and C# property names are named identically to simplify the mapping process.

Add the following code to Program.cs before "var app = builder.Build();" :

builder.Services.Configure<StudentsDbSettings>(

    builder.Configuration.GetSection("StudentDbSettings"));

In the above code, the configuration instance to which the appsettings.json file's StudentDatabaseSettings section binds is registered in the Dependency Injection (DI) container.

Create a folder named Services and add to it a file named StudentService.cs with the following code:

namespace AspMongoApi.Services;

public class StudentsService {

    private readonly IMongoCollection<Student> _studentsCollection;

    public StudentsService(IOptions<StudentsDbSettings> studentsDatabaseSettings) {

        var mongoClient = new MongoClient(

            studentsDatabaseSettings.Value.ConnectionString);

        var mongoDatabase = mongoClient.GetDatabase(

            studentsDatabaseSettings.Value.DatabaseName);

        _studentsCollection = mongoDatabase.GetCollection<Student>(

            studentsDatabaseSettings.Value.CollectionName);

    }

    public async Task<List<Student>> GetAsync() =>

        await _studentsCollection.Find(_ => true).ToListAsync();

    public async Task<Student?> GetAsync(string id) =>

        await _studentsCollection.Find(x => x.Id == id).FirstOrDefaultAsync();

    public async Task CreateAsync(Student newStudent) =>

        await _studentsCollection.InsertOneAsync(newStudent);

    public async Task UpdateAsync(string id, Student updatedStudent) =>

        await _studentsCollection.ReplaceOneAsync(x => x.Id == id, updatedStudent);

    public async Task RemoveAsync(string id) =>

        await _studentsCollection.DeleteOneAsync(x => x.Id == id);

}

In the above code, an StudentsDbSettings instance is retrieved from Dependency Injection via constructor injection. Also, the above class knows how to connect to the MongoDB server and use the available driver methods to retrieve, insert, update and delete data.

Register the StudentService class with DI to support constructor injection. Add the following to Program.cs before "var app = builder.Build();" :

builder.Services.AddSingleton<StudentsService>();

Add the following code to Program.cs right before the "app.Run()l" statement:

app.MapGet("/students", async (StudentsService studentsService) => {

    var students = await studentsService.GetAsync();

    return students;

});

app.MapGet("/students/{id}", async (StudentsService studentsService, string id) => {

    var student = await studentsService.GetAsync(id);

    return student is null ? Results.NotFound() : Results.Ok(student);

});

app.MapPost("/students", async (StudentsService studentsService, Student student) => {

    await studentsService.CreateAsync(student);

    return student;

});

app.MapPut("/students/{id}", async (StudentsService studentsService, string id, Student student) => {

    await studentsService.UpdateAsync(id, student);

    return student;

});

app.MapDelete("/students/{id}", async (StudentsService studentsService, string id) => {

    await studentsService.RemoveAsync(id);

    return Results.Ok();

});

The above endpoints:

• Use the StudentService class to perform CRUD operations.
• Contains action methods to support GET, POST, PUT, and DELETE HTTP requests.

Running the application

Start the application by executing the this command from a terminal windows at the root of the application:

dotnet watch

Test the API with the Swagger interface that is available in your browser:

You can also view the data by pointing your browser to https://localhost:????/api/Students. This is the expected output:

Note that even though the last field is named School in the database, it appears as Department in our app because that is how we mapped it in the Student class.

Go ahead and test the other API endpoints for POST, PUT and DELETE using your favourite tool like Postman or curl. It should all work.

Cleanup

To stop & remove the MongoDB docker container, enter the following from any terminal window on your computer:

docker rm -f mgo

I hope you learned something new in this tutorial. Until next time, happy coding.

ASP.NET 6.0 Web API and Mongo DB

In this tutorial I will show you how to develop an ASP.NET 6.0 API application that interacts with MongoDB. In order to proceed you will need the following pre-requisites:

• Docker - used to host MongoDB. This is my preferred approach because it is quick and does not take too many resources on the host computer.
• .NET 6.0
• Visual Studio Code

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

Companion Video: https://youtu.be/pDIqBRvy3g8

The Database

Run the following command in a terminal window to start a MongoDB container named mdb:

docker run -p 27777:27017 --name mgo -d mongo:4.1.6

You can verify that the container is running by typing the following command in a terminal window:

docker ps -a

Let us start a bash session inside the container so that we can create a database and add some sample data to it. Enter the following command to start an interactive bash session inside the container:

docker exec -it mgo bash

We can then use the mongo command line interface (CLI) to create a database and then add some sample data to a collection of students. Type the following command:

mongo

This takes you into a mongo session command prompt. Enter the following command to create a database named school-db:

use school-db

Next, let's create a collection named students and add to it six sample students:

db.Students.insertMany(

[

  {'FirstName':'Sue','LastName':'Fox','School':'Business'},

  {'FirstName':'Tom','LastName':'Max','School':'Mining'},

  {'FirstName':'Ann','LastName':'Lee','School':'Nursing'},

  {'FirstName':'Joe','LastName':'Roy','School':'Tourism'},

  {'FirstName':'Jan','LastName':'Ash','School':'Communications'},

  {'FirstName':'Eva','LastName':'Day','School':'Medicine'},

]);

You can retrieve the list of students with the following command:

db.Students.find({}).pretty();

To exit the mongo command prompt by typing:

exit

You can also exit the bash session and return to the host operating system by typing:

exit

Creating an ASP.NET 6.0 Web API application

Create an ASP.NET 6.0 Web API application. This is accomplished by entering this command:

dotnet new webapi -f net6.0 -o AspMongoApi

Let us see what our application looks like. Run the application by executing:

cd AspMongoApi

dotnet run

The above command builds and runs the application in a web server. Point your browser to https://localhost:????/weatherforecast (Where ???? is your port number). This is what you should see:

Stop the web server by hitting CTRL+C on the keyboard.

Building the Students API

Find the latest version of MongoDB driver from https://www.nuget.org/packages/MongoDB.Driver/. At the time of writing, the latest version was 2.14.1. Add the MongoDB driver Nuget package with the following command:

dotnet add package MongoDB.Driver --version 2.14.1

Now that we have the driver, we can proceed with coding our API. I will use Visual Studio Code because it is operating system agnostic. To load your application workspace into VS Code, simply type in the following command from the root folder of your application:

code .

We need a Student class to represent the schema for student documents in the Students collection in the MongoDB school-db database. Create a Models folder. Inside the Models folder, add a file named Student.cs with the following code:

using MongoDB.Bson;

using MongoDB.Bson.Serialization.Attributes;

namespace AspMongoApi.Models;

public class Student {

    [BsonId]

    [BsonRepresentation(BsonType.ObjectId)]

    public string? Id { get; set; }

    public string? FirstName { get; set; }

    public string? LastName { get; set; }

    

    [BsonElement("School")]

    public string? Department { get; set; }

}

In the preceding class, the Id property:

• Is required for mapping the Common Language Runtime (CLR) object to the MongoDB collection.
• Is annotated with [BsonId] to designate this property as the document's primary key.
• Is annotated with [BsonRepresentation(BsonType.ObjectId)] to allow passing the parameter as type string instead of an ObjectId structure. Mongo handles the conversion from string to ObjectId.

The Department property is annotated with the [BsonElement] attribute. The attribute's value of School represents the property name in the MongoDB collection.

Add the following to appsettings.json:

"StudentDbSettings": {

"CollectionName": "Students",

"ConnectionString": "mongodb://localhost:27777",

"DatabaseName": "school-db"

},

The entire contents of appsettings.json will look like this:

{

  "StudentDbSettings": {

    "CollectionName": "Students",

    "ConnectionString": "mongodb://localhost:27777",

    "DatabaseName": "school-db"

  },

  "Logging": {

    "LogLevel": {

      "Default": "Information",

      "Microsoft.AspNetCore": "Warning"

    }

  },

  "AllowedHosts": "*"

}

Add StudentDbSettings.cs to the Models folder with this code:

namespace AspMongoApi.Models;

public class StudentsDbSettings {

    public string ConnectionString { get; set; } = null!;

    public string DatabaseName { get; set; } = null!;

    public string CollectionName { get; set; } = null!;

}

The above StudentDbSettings class is used to store the appsettings.json file's StudentDbSettings property values. The JSON and C# property names are named identically to simplify the mapping process.

Add the following code to Program.cs before "var app = builder.Build();" :

builder.Services.Configure<StudentsDbSettings>(

    builder.Configuration.GetSection("StudentDbSettings"));

In the above code, the configuration instance to which the appsettings.json file's StudentDatabaseSettings section binds is registered in the Dependency Injection (DI) container.

Create a folder named Services and add to it a file named StudentService.cs with the following code:

namespace AspMongoApi.Services;

public class StudentsService {

    private readonly IMongoCollection<Student> _studentsCollection;

    public StudentsService(IOptions<StudentsDbSettings> studentsDatabaseSettings) {

        var mongoClient = new MongoClient(

            studentsDatabaseSettings.Value.ConnectionString);

        var mongoDatabase = mongoClient.GetDatabase(

            studentsDatabaseSettings.Value.DatabaseName);

        _studentsCollection = mongoDatabase.GetCollection<Student>(

            studentsDatabaseSettings.Value.CollectionName);

    }

    public async Task<List<Student>> GetAsync() =>

        await _studentsCollection.Find(_ => true).ToListAsync();

    public async Task<Student?> GetAsync(string id) =>

        await _studentsCollection.Find(x => x.Id == id).FirstOrDefaultAsync();

    public async Task CreateAsync(Student newStudent) =>

        await _studentsCollection.InsertOneAsync(newStudent);

    public async Task UpdateAsync(string id, Student updatedStudent) =>

        await _studentsCollection.ReplaceOneAsync(x => x.Id == id, updatedStudent);

    public async Task RemoveAsync(string id) =>

        await _studentsCollection.DeleteOneAsync(x => x.Id == id);

}

In the above code, an StudentsDbSettings instance is retrieved from DI via constructor injection. Also, the above class knows how to connect to the MongoDB server and use the available driver methods to retrieve, insert, update and delete data.

To register the StudentService class with DI to support constructor injection, add the following to Program.cs before "var app = builder.Build();" :

builder.Services.AddSingleton<StudentsService>();

Add a StudentsController.cs class to the Controllers folder with the following code:

namespace AspMongoApi.Controllers;

[ApiController]

[Route("api/[controller]")]

public class StudentsController : ControllerBase {

    private readonly StudentsService _studentsService;

    public StudentsController(StudentsService studentsService) =>

        _studentsService = studentsService;

    [HttpGet]

    public async Task<List<Student>> Get() =>

        await _studentsService.GetAsync();

    [HttpGet("{id:length(24)}")]

    public async Task<ActionResult<Student>> Get(string id) {

        var student = await _studentsService.GetAsync(id);

        if (student is null) {

            return NotFound();

        }

        return student;

    }

    [HttpPost]

    public async Task<IActionResult> Post(Student newStudent) {

        await _studentsService.CreateAsync(newStudent);

        return CreatedAtAction(nameof(Get), new { id = newStudent.Id }, newStudent);

    }

    [HttpPut("{id:length(24)}")]

    public async Task<IActionResult> Update(string id, Student updatedStudent) {

        var student = await _studentsService.GetAsync(id);

        if (student is null) {

            return NotFound();

        }

        updatedStudent.Id = student.Id;

        await _studentsService.UpdateAsync(id, updatedStudent);

        return NoContent();

    }

    [HttpDelete("{id:length(24)}")]

    public async Task<IActionResult> Delete(string id) {

        var student = await _studentsService.GetAsync(id);

        if (student is null) {

            return NotFound();

        }

        await _studentsService.RemoveAsync(student.Id!);

        return NoContent();

    }

}

The StudentsController class:

• Uses the StudentService class to perform CRUD operations.
• Contains action methods to support GET, POST, PUT, and DELETE HTTP requests.

Running the application

Start the application by executing the this command from a terminal windows at the root of the application:

dotnet run

You can view the data by pointing your browser to https://localhost:????/api/Students. This is the expected output:

Note that even though the last field is named School in the database, it appears as Department in our app because that is how we mapped it in the Student class.

Go ahead and test the other API endpoints for POST, PUT and DELETE using your favourite tool like Postman or curl. It should all work.

Cleanup

To stop & remove the MongoDB docker container, enter the following from any terminal window on your computer:

docker rm -f mgo

I hope you learned something new in this tutorial. Until next time, happy coding.

Reference:https://referbruv.com/blog/posts/integrating-mongodb-with-aspnet-core-(net-6)