gRPC is a modern, open-source RPC framework that leverages HTTP/2, Protocol Buffers, and advanced streaming capabilities to deliver exceptional performance. Unlike traditional REST APIs, gRPC offers strongly-typed contracts, automatic code generation, and built-in support for multiple programming languages. This makes it an ideal choice for microservices architectures and cross-platform development.

In this handbook, I’ll take you on a journey from absolute beginner to building production-ready gRPC services with ASP.NET Core. Whether you're migrating from REST APIs or starting fresh with gRPC, this guide will provide you with practical, hands-on experience and real-world examples.

What you'll learn:

• How to set up your first gRPC service in .NET

• How to define service contracts with Protocol Buffers

• How to implement unary, server streaming, and client streaming operations

• How to build CRUD (Create, Read, Update, Delete) operations

Let's dive in and discover how gRPC can revolutionize your API development experience!

You can find all the code in this GitHub Repository.

Table of Contents

1. gRPC Overview and How It Works with .NET

2. How to Set Up gRPC with .NET

3. How to Create the Product Model

4. How to Set Up the SQLite Database

5. How to Create Product Protocol Buffers

6. How to Implement CRUD Operations Services with gRPC

7. How to Implement gRPC CRUD Database Operations With SQLite

8. How to Test gRPC Services with Postman

9. How to Test Product Creation

10. How to Test All Product Operations

11. Conclusion

Perquisites

Before we start, make sure you have the following installed:

• .NET SDK

• Visual Studio Code

• Postman

gRPC Overview and How It Works with .NET

gRPC is a high-performance, cross-platform framework that works seamlessly with many technologies, including .NET Core.

Why choose gRPC with .NET?

There are many reasons why this is a good combination. First, of all, this combo is up to 8x faster than using REST APIs with JSON. Its strongly-typed contracts also help prevent runtime errors.

It also has built-in support for client, server, and bidirectional streaming, as well as seamless integration across different languages and platforms. Finally, it leverages HTTP/2 for multiplexing and header compression – so as you can see, these two tools are a super effective pair.

To understand in more detail why gRPC is so valuable, let's explore a common real-world scenario.

The Challenge: Microservices Communication

Imagine you're building a large e-commerce application. For better maintainability and scalability, you decide to split your monolithic application into smaller, focused services:

• Product Service – Handles product catalog, inventory, and product management

• Authentication Service – Manages user authentication, authorization, and user profiles

These services need to communicate with each other frequently. For example, before a user can add a product to their cart, the Product Service must verify with the Authentication Service that the user is logged in and has the proper permissions.

Traditional Approach: HTTP REST APIs

Traditionally, in .NET applications, we solve this inter-service communication using HttpClient to make REST API calls between services. While this works, it comes with several challenges:

• Network failures: API calls can fail unexpectedly, even when everything appears correct

• Performance bottlenecks: JSON serialization/deserialization adds overhead

• Slow response times: HTTP/1.1 limitations affect performance under high load

• Type safety: No compile-time contract validation between services

• Verbose payloads: JSON can be bulky compared to binary formats

The gRPC Solution

This is where gRPC shines. It addresses these challenges by providing some really helpful features in addition to the ones we’ve already discussed above like protocol buffers, code generation for client and server, and more.

When to Use gRPC in .NET

gRPC is particularly beneficial in certain scenarios, but it’s not a great choice in others. Here are some example use cases, as well as some to avoid:

✅ Perfect for:

• Microservices architecture: High-frequency service-to-service communication

• Real-time applications: Chat applications, live updates, gaming

• High-performance APIs: When speed and efficiency are critical

• Polyglot environments: Services written in different programming languages

• Internal APIs: Backend services that don't need browser compatibility

❌ Consider Alternatives When:

• Browser-based applications: Limited browser support (use gRPC-Web instead)

• Public APIs: REST might be more familiar to external developers

• Simple CRUD operations: Where REST's simplicity is sufficient

• Legacy system integration: When existing systems only support HTTP/1.1

gRPC vs REST: A Quick Comparison

Here’s a quick side-by-side comparison of their main features:

In this handbook, we'll build a complete Product Management system using gRPC with .NET, demonstrating how to implement efficient service-to-service communication with full CRUD operations.

How to Set Up gRPC with .NET

In this tutorial, we'll use Visual Studio Code to build our complete gRPC application. Let's start by creating a new gRPC project using the .NET CLI.

Creating Your First gRPC Project

Start by opening your terminal (you can use VS Code's integrated terminal or your system terminal) and navigate to your desired directory where you want to create the project.

Run the following command to create a new gRPC project:

dotnet new grpc -o ProductGrpc

What this command does:

• dotnet new grpc creates a new project using the gRPC template

• -o ProductGrpc specifies the output directory name for our project

Next, navigate into the project directory:

cd ProductGrpc

Then open the project in Visual Studio Code:

code .

Understanding the Project Structure

After running the command, you should see output similar to the following in your terminal, confirming that the project was created successfully:

Let's explore what the .NET gRPC template has generated for us:

ProductGrpc/
├── Protos/
│   └── greet.proto          # Protocol Buffer definition file
├── Services/
│   └── GreeterService.cs    # Sample gRPC service implementation
├── Program.cs               # Application entry point
├── ProductGrpc.csproj       # Project file
└── appsettings.json         # Configuration file

Key files:

• Protos/greet.proto: Defines the service contract using Protocol Buffers

• Services/GreeterService.cs: Contains the actual service implementation

• Program.cs: Configures and starts the gRPC server

• ProductGrpc.csproj: Contains project dependencies and build settings

Verifying the Setup

Let's make sure everything is working correctly by running the default application:

dotnet run

You should see output indicating that the gRPC server is running:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7042
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

🎉 Congratulations! You've successfully created your first gRPC application using the .NET CLI. The server is now running and ready to accept gRPC requests.

Let's move on to the next section, where we'll start building our Product Management system.

How to Create the Product Model

Now that we have our gRPC project set up, let's create our Product model. In .NET applications, models represent the data structure and business entities that our application will work with. Think of models as blueprints that define what properties our data objects should have.

Understanding Models in gRPC Applications

Models serve several important purposes:

• Data structure: They define the shape and properties of our business entities.

• Type safety: They ensure compile-time validation of our data.

• Business logic: They represent real-world objects in our application.

• Database mapping: They serve as entities for database operations.

Creating the Models Folder

Let’s organize our code by creating a dedicated folder for our models called Models in your project root directory.

Inside the Models folder, create a new file called Product.cs.

Your project structure should now look like this:

ProductGrpc/
├── Models/
│   └── Product.cs           # Our new Product model
├── Protos/
├── Services/
└── ...

Implementing the Product Model

Add the following code to your Product.cs file:

// Models/Product.cs
using System.ComponentModel.DataAnnotations;

namespace ProductGrpc.Models
{
    public class Product
    {

        public Guid Id { get; set; }
        public required string Name { get; set; }
        public required string Description { get; set; }
        public decimal Price { get; set; }

        public DateTime Created { get; set; } = DateTime.UtcNow;

        public DateTime Updated { get; set; } = DateTime.UtcNow;
        public string? Tags { get; set; }
    }
}

Modern C# features:

• required keyword: Ensures properties must be initialized when creating an object

• string?: Nullable reference type for optional properties

• Default values: Created and Updated automatically set to the current UTC

Why Use Guid for ID?

We're using Guid instead of int for our primary key for a few reasons:

• Uniqueness: Guaranteed to be unique across different systems

• Security: Harder to guess than sequential integers

• Distributed systems: No need for centralized ID generation

• Scalability: Perfect for microservices architecture

Namespace Considerations

Important Note: If you changed your project name when creating it, make sure your namespace matches your project name. For example:

• If your project is named MyProductService, use namespace MyProductService.Models

• If your project is named ProductGrpc, use namespace ProductGrpc.Models

🎉 Excellent work! You've successfully created your first business model that will serve as the foundation for our entire gRPC application.

Next Steps

Now that we have our Product model ready, let's move on to setting up SQLite as our database and configuring Entity Framework Core to handle our data persistence. This will allow us to store and retrieve our Product data efficiently.

How to Set Up the SQLite Database

To persist our product data, we need a database that can handle our CRUD (Create, Read, Update, Delete) operations efficiently. We'll use SQLite for this tutorial because it's lightweight, requires no separate server installation, and works perfectly for developing small-to-medium applications.

Installing the Required Packages

Before we create our database context, we need to install the necessary Entity Framework Core packages. Open your terminal and make sure you're in the root directory of your project, then run these commands:

dotnet add package Microsoft.EntityFrameworkCore.Design

dotnet add package Microsoft.EntityFrameworkCore.Sqlite

What these packages do:

• Microsoft.EntityFrameworkCore.Design provides design-time tools for EF Core (migrations, scaffolding)

• Microsoft.EntityFrameworkCore.SQLite is a SQLite database provider for Entity Framework Core

You should see output confirming the packages were added successfully:

info : PackageReference for 'Microsoft.EntityFrameworkCore.Design' version 'x.x.x' added to file 'ProductGrpc.csproj'.
info : PackageReference for 'Microsoft.EntityFrameworkCore.Sqlite' version 'x.x.x' added to file 'ProductGrpc.csproj'.

Creating the Database Context

Now let's create our database context, which acts as a bridge between our .NET objects and the database.

First, create a new folder called Data In your project root. Inside the Data folder, create a file called AppDbContext.cs.

Your project structure should now look like this:

ProductGrpc/
├── Data/
│   └── AppDbContext.cs      # Our new database context
├── Models/
│   └── Product.cs
├── Protos/
├── Services/
└── ...

Add the following code to your AppDbContext.cs file:

// Data/AppDbContext.cs
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Models;

namespace ProductGrpc.Data
{
    public class AppDbContext : DbContext
    {
        public AppDbContext(DbContextOptions<AppDbContext> options) : base(options)
        {
        }

        public DbSet<Product> Products { get; set; }
    }
}

Let’s understand the key components of DbContext:

• Constructor: Accepts DbContextOptions for configuration (connection string, provider, and so on)

• DbSet Products: Represents the Products table in our database

Registering the Database Context

Now we need to register our AppDbContext With the dependency injection container so our application can use it.

Open your Program.cs file and add the database configuration:

// Program.cs

using ProductGrpc.Data;
using ProductGrpc.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(opt=> 
    opt.UseSqlite("Data Source=ProductGrpc.db "));
// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();


app.Run();

Data Source=ProductGrpc.db creates a SQLite database file named ProductGrpc.db in your project directory.

Creating and Running Migrations

Now we need to create a migration to generate the database schema based on our Product model.

Start by creating the initial migration:

dotnet ef migrations add InitialCreate

This command will:

• Analyze your models and DbContext

• Generate migration files in a Migrations folder

• Create SQL commands needed to build your database schema

You should see output like this:

Build succeeded.
Done. To undo this action, use 'dotnet ef migrations remove'

Apply the migration to create the database:

dotnet ef database update

This command will:

• Execute the migration SQL commands

• Create the ProductGrpc.db file in your project directory

• Set up the Products table with all the correct columns

You should see output confirming the database was created:

Build succeeded.
Applying migration '20240101000000_InitialCreate'.
Done.

Verifying the Setup

After running the migration, you should see:

1. A new Migrations folder in your project with migration files

2. A ProductGrpc.db file in your project root (this is your SQLite database)

3. No errors in the terminal output

Your project structure should now look like this:

ProductGrpc/
├── Data/
│   └── AppDbContext.cs
├── Migrations/
│   ├── 20240101000000_InitialCreate.cs
│   └── AppDbContextModelSnapshot.cs
├── Models/
│   └── Product.cs
├── ProductGrpc.db            # Your SQLite database file
└── ...

Congratulations! You've successfully installed Entity Framework Core packages, created a database context, registered the context with dependency injection, generated and applied your first migration, and created a working SQLite database. Whew!

What's Next?

Now that our database is set up and ready, we can move on to creating our Protocol Buffer definitions (.proto files) and implementing our gRPC services for CRUD operations.

How to Create Product Protocol Buffers

Protocol Buffers (protobuf) are the heart of gRPC communication. They define the structure of your data and services in a language-neutral way, which then gets compiled into native C# code. Protocol Buffers use the efficient HTTP/2 protocol, making service-to-service communication fast and reliable.

Understanding Protocol Buffers vs REST APIs

To better understand Protocol Buffers, let's compare them to what you might already know from REST API development.

In REST API development, you typically define your API endpoints using controllers and action methods. The contract between client and server is often documented separately (like with OpenAPI/Swagger), and there's no compile-time guarantee that your documentation matches your actual implementation.

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}")]
    public async Task<ActionResult<ProductDto>> GetProduct(int id) { ... }

With gRPC, the service contract is defined first in the .proto file using the service keyword. This contract becomes the single source of truth, and both client and server code are generated from it, ensuring they're always in sync.

service ProductService {
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
}

Data Transfer and Serialization

REST APIs typically use JSON for data transfer, which is human-readable and widely supported. But JSON is text-based, which has a few negatives. First, it has larger payload sizes due to text encoding. It also comes with some runtime parsing overhead. It doesn’t have any built-in schema validation, and there’s a high potential for typos in field names

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Wireless Headphones",
  "price": 99.99
}

gRPC instead uses Protocol Buffers, which serialize data into a compact binary format. This provides significantly smaller payloads (up to 6x smaller than JSON), faster serialization/deserialization, strong typing with compile-time validation, and schema evolution without breaking changes.

Transport Protocol Differences

REST APIs run over HTTP/1.1, which has some limitations:

• One request-response cycle per connection

• Text-based headers (larger overhead)

• No built-in multiplexing

• Limited streaming capabilities

gRPC leverages HTTP/2, which offers some advantages:

• Multiplexing: Multiple requests over a single connection

• Header compression: Reduced overhead with HPACK

• Server push: The Server can initiate streams to clients

• Flow control: Better handling of slow consumers

Data Structure Definitions

In REST APIs, you define DTOs (Data Transfer Objects) as regular classes:

public class ProductDto
{
    public string Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

These DTOs exist only in your specific language and need manual synchronization across different services or languages.

In gRPC, you define Messages in the proto file:

message ProductModel {
  string id = 1;
  string name = 2;
  double price = 3;
}

These message definitions are language-agnostic and automatically generate equivalent classes in any supported programming language.

Here's a quick comparison table to summarize these differences:

Creating the Product Proto File

Navigate to the Protos folder in your project and create a new file called product.proto. Make sure the file extension is .proto.

Your project structure should look like this:

ProductGrpc/
├── Protos/
│   ├── greet.proto          # Default template file
│   └── product.proto        # Our new proto file
└── ...

Setting Up the Proto File Header

Add the following header to your product.proto file:

//  Protos/product.proto
syntax = "proto3";

option csharp_namespace = "ProductGrpc";

package product;

Here’s what’s going on:

• syntax = "proto3": Specifies that we're using Protocol Buffers version 3

• option csharp_namespace = "ProductGrpc": Sets the C# namespace for generated code

• package product: Defines the protobuf package name

Note: If you named your project differently, make sure the csharp_namespace matches your project name.

Defining the Product Service

In gRPC, services define the available operations (similar to interfaces in REST APIs). Add the following service definition:

// :Protos/product.proto
service  ProductsServiceProto {
  rpc CreateProduct(CreateProductRequest) returns (CreateProductResponse);
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
  rpc UpdateProduct(UpdateProductRequest) returns (UpdateProductResponse);
  rpc DeleteProduct(DeleteProductRequest) returns (DeleteProductResponse);
}

Service methods explained:

• rpc: Defines a remote procedure call

• CreateProduct: Method name

• (CreateProductRequest): Input message type

• returns (CreateProductResponse): Output message type

Defining Protocol Buffer Messages

Messages in gRPC are equivalent to DTOs in REST APIs. They define the structure of data being exchanged. Let's create all the messages we need:

Product Model Message:

// product.proto
message ProductModel {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string created_at = 5;
  string updated_at = 6;
  string tags = 7;
}

Create Operation Messages:

// Protos/product.proto
message CreateProductRequest {
  string name = 1;
  string description = 2;
  double price = 3;
  string tags = 4;
}

message CreateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

Read Operation Messages:

// Protos/product.proto
message GetProductRequest {
  string id = 1;
}

message GetProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

message ListProductsRequest {
  int32 page = 1;
  int32 page_size = 2;
}

message ListProductsResponse {
  bool success = 1;
  string message = 2;
  repeated ProductModel products = 3;
  int32 total_count = 4;
}

Update Operation Messages:

 // Protos/product.proto
message UpdateProductRequest {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string tags = 5;
}

message UpdateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

Delete Operation Messages:

// Protos/product.proto
message DeleteProductRequest {
  string id = 1;
}

message DeleteProductResponse {
  bool success = 1;
  string message = 2;
}

Understanding Protocol Buffer Syntax

There are a few key concepts you should understand about how protocol buffers work:

• Field Numbers: Each field has a unique number (for example, = 1, = 2) used for binary encoding

• Field Types: string, int32, double, bool are common scalar types

• repeated: Indicates an array/list (for example, repeated ProductModel products)

• Message Nesting: Messages can contain other messages (for example, ProductModel product)

Keep in mind that field numbers must be unique within a message, field numbers 1-15 use 1 byte encoding (more efficient), and you should never reuse field numbers (for backward compatibility).

Complete Product Proto File

Here's your complete product.proto file:

// Protos/product.proto
syntax = "proto3";

option csharp_namespace = "ProductGrpc";

package product;

// Product service definition
service  ProductsServiceProto {
  rpc CreateProduct(CreateProductRequest) returns (CreateProductResponse);
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
  rpc UpdateProduct(UpdateProductRequest) returns (UpdateProductResponse);
  rpc DeleteProduct(DeleteProductRequest) returns (DeleteProductResponse);
}

// Product model message
message ProductModel {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string created_at = 5;
  string updated_at = 6;
  string tags = 7;
}

// Create operation messages
message CreateProductRequest {
  string name = 1;
  string description = 2;
  double price = 3;
  string tags = 4;
}

message CreateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

// Read operation messages
message GetProductRequest {
  string id = 1;
}

message GetProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

message ListProductsRequest {
  int32 page = 1;
  int32 page_size = 2;
}

message ListProductsResponse {
  bool success = 1;
  string message = 2;
  repeated ProductModel products = 3;
  int32 total_count = 4;
}

// Update operation messages
message UpdateProductRequest {
  string id = 1;
  string name = 2;
  string description = 3;
  double price = 4;
  string tags = 5;
}

message UpdateProductResponse {
  bool success = 1;
  string message = 2;
  ProductModel product = 3;
}

// Delete operation messages
message DeleteProductRequest {
  string id = 1;
}

message DeleteProductResponse {
  bool success = 1;
  string message = 2;
}

Building the Project to Generate C# Code

Now that we've defined our Protocol Buffer contract, we need to build the project to generate the corresponding C# code:

dotnet build

This command will compile your .proto files into C# classes, generate client and server code, and create strongly-typed request/response classes.

You should see output confirming the build was successful:

Restore complete (0.6s)
  ProductGrpc succeeded (9.5s) → bin\Debug\net9.0\ProductGrpc.dll

Build succeeded in 11.1s

What Gets Generated?

After building, the Protocol Buffer compiler generates several C# files (you won't see them directly, but they're available in your code):

• ProductModel: C# class representing your product data

• CreateProductRequest/Response: Request and response classes for create operations

• ProductService.ProductServiceBase: Base class for implementing your service

• ProductService.ProductServiceClient: Client class for calling the service

Congratulations! You've successfully created a comprehensive Protocol Buffer definition, defined a complete CRUD service contract, set up a strongly-typed message structure, and generated C# code from your proto file.

What's Next?

Now that we have our Protocol Buffer contract defined, we can start implementing the actual gRPC service methods. In the next section, we'll create the ProductService Class and implement each CRUD operation.

Remember: Protocol Buffers are language-agnostic, so this same .proto file could be used to generate client code in Python, Java, Go, or any other supported language.

How to Implement CRUD Operations Services with gRPC

Now that we have our database set up and Protocol Buffer contracts defined, it's time to implement the actual CRUD (Create, Read, Update, Delete) functionality. We'll create a gRPC service that brings together our database models and Protocol Buffer definitions.

Understanding the Implementation Architecture

Before we start coding, let's understand how the pieces fit together:

Protocol Buffer (.proto) → Generated C# Code → Our Service Implementation → Database

Key concepts in this code:

• Proto Service: Interface (defines what methods are available)

• Proto Messages: DTOs (define data structure)

• Service Implementation: Business logic (what happens)

• Database Context: Data persistence layer

Configuring Proto File Build

First, we need to ensure our product.proto file gets compiled into C# code during the build process.

Open your ProductGrpc.csproj file and locate the <ItemGroup> section that references proto files:

  <!-- ProductGrpc.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    <!-- Add this line to include our product.proto file -->
    <Protobuf Include="Protos\product.proto" GrpcServices="Server" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.64.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.6">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.6" />
  </ItemGroup>
</Project>

What this configuration does:

• Include="Protos\product.proto" tells .NET to process our proto file

• GrpcServices="Server" generates server-side code (service base classes)

Building the Project

Now let's build the project to generate the C# code from our proto file:

dotnet build

This command will compile your .proto files into C# classes, generate the ProductsServiceProto. ProductsServiceProtoBase class we'll inherit from, create all the request/response message classes, and validate that everything compiles correctly.

You should see output like:

Build succeeded.
    0 Warning(s)
    0 Error(s)

Creating the ProductService Class

Navigate to the Services folder and create a new file called ProductService.cs. This will contain our gRPC service implementation.

Your project structure should now look like this:

ProductGrpc/
├── Services/
│   ├── GreeterService.cs    # Default template service
│   └── ProductService.cs    # Our new product service
└── ...

Setting Up the Service Foundation

Start by creating the basic service class structure:

 // Services/ProductService.cs
using Grpc.Core;
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Models;

namespace ProductGrpc.Services
{
    public class ProductService :  ProductsServiceProto .ProductsServiceProtoBase
    {
        private readonly AppDbContext _dbContext;
        private readonly ILogger<ProductService> _logger;

        public ProductService(AppDbContext dbContext, ILogger<ProductService> logger)
        {
            _dbContext = dbContext;
            _logger = logger;
        }

        // CRUD methods will be implemented here
    }
}

Key components of this code:

• Inheritance: ProductsServiceProto .ProductsServiceProtoBase is generated from our proto file

• Dependency injection: We inject AppDbContext for database operations and ILogger for logging

• Constructor: Initializes our dependencies

Implementing Method Signatures

Now let's add all the method signatures that we defined in our proto file. These methods override the virtual methods from the base class:

 //Services/ProductService.cs
using Grpc.Core;
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Models;

namespace ProductGrpc.Services
{
    public class ProductService :  ProductsServiceProto .ProductsServiceProtoBase
    {
        private readonly AppDbContext _dbContext;
        private readonly ILogger<ProductService> _logger;

        public ProductService(AppDbContext dbContext, ILogger<ProductService> logger)
        {
            _dbContext = dbContext;
            _logger = logger;
        }

        public override async Task<CreateProductResponse> CreateProduct(
            CreateProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<GetProductResponse> GetProduct(
            GetProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<ListProductsResponse> ListProducts(
            ListProductsRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<UpdateProductResponse> UpdateProduct(
            UpdateProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }

        public override async Task<DeleteProductResponse> DeleteProduct(
            DeleteProductRequest request, 
            ServerCallContext context)
        {
            // Implementation will go here
            throw new NotImplementedException();
        }
    }
}

Understanding Method Parameters

Each gRPC method receives two parameters:

1. Request parameter: Contains the data sent by the client (for example, CreateProductRequest)

2. ServerCallContext: Provides access to request metadata, cancellation tokens, and response headers

Method Signature Pattern:

public override async Task<ResponseType> MethodName(
    RequestType request, 
    ServerCallContext context)

Registering the Service

Before we implement the methods, we need to register our service with the application. Open Program.cs and add the service:

 // Program.cs
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Services; // Add this using statement

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddGrpc();

// Register our database context
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite("Data Source=ProductGrpc.db"));

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGrpcService<ProductService>(); // Add this line

app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

Handling Compiler Warnings

You might see warnings like:

This async method lacks 'await' operators and will run synchronously.

This is expected since we haven't implemented the actual logic yet. These warnings will disappear once we add the implementation in the following sections.

Creating Helper Methods

Before implementing CRUD operations, let's add some helper methods for converting between our database models and Protocol Buffer messages:

:Services/ProductService.cs
// Add these helper methods to your ProductService class


 private static ProductModel MapToProductModel(Product product)
{
    return new ProductModel
    {
        Id = product.Id.ToString(),
        Name = product.Name,
        Description = product.Description,
        Price = (double)product.Price,
        CreatedAt = product.Created.ToString("yyyy-MM-ddTHH:mm:ssZ"),
        UpdatedAt = product.Updated.ToString("yyyy-MM-ddTHH:mm:ssZ"),
        Tag = product.Tags ?? string.Empty
    };
}

Excellent work! You've successfully:

• Configured proto file compilation

• Created the ProductService class structure

• Set up dependency injection

• Defined all CRUD method signatures

• Registered the service with the application

• Created helper methods for data mapping

What's Next?

Now that we have our service foundation ready, we'll implement each CRUD operation one by one:

1. CreateProduct: Add new products to the database

2. GetProduct: Retrieve a single product by ID

3. ListProducts: Get a paginated list of products

4. UpdateProduct: Modify existing products

5. DeleteProduct: Remove products from the database

In the next sections, we'll dive deep into each implementation, handling error cases, validation, and best practices.

💡 Pro Tip: The ServerCallContext parameter provides useful information like request cancellation tokens, client metadata, and response headers. We'll use these in our implementations for better error handling and logging.

Note: The override keyword is crucial – it tells C# that we're implementing the virtual methods defined in the generated base class from our proto file.

How to Implement gRPC CRUD Database Operations With SQLite

Now that we have our service foundation ready, let's implement each CRUD operation. Each method will handle database operations, error handling, and return appropriate responses using our Protocol Buffer messages.

Understanding the Implementation Pattern

Each CRUD operation follows a consistent pattern:

1. Input Validation: Validate request parameters

2. Database Operation: Perform the actual database work

3. Response Mapping: Convert database models to Protocol Buffer messages

4. Error Handling: Catch and handle exceptions gracefully

Creating the CreateProduct Service

The CreateProduct method handles adding new products to our database. This is the "C" in CRUD (Create).

//Services/ProductService.cs
public override async Task<CreateProductResponse> CreateProduct(
    CreateProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Input validation
        if (string.IsNullOrWhiteSpace(request.Name))
        {
            return new CreateProductResponse
            {
                Success = false,
                Message = "Product name is required"
            };
        }

        if (request.Price <= 0)
        {
            return new CreateProductResponse
            {
                Success = false,
                Message = "Product price must be greater than zero"
            };
        }

        // Create new product entity
        var productItem = new Product
        {
            Id = Guid.NewGuid(),
            Name = request.Name,
            Description = request.Description,
            Price = Convert.ToDecimal(request.Price),
            Created = DateTime.UtcNow,
            Updated = DateTime.UtcNow,
            Tags = request.Tags
        };

        // Add to database
        _dbContext.Products.Add(productItem);
        await _dbContext.SaveChangesAsync();

        _logger.LogInformation("Product created successfully with ID: {ProductId}", productItem.Id);

        // Return success response
        return new CreateProductResponse
        {
            Success = true,
            Message = "Product created successfully",
            Product = MapToProductModel(productItem)
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error creating product");

        return new CreateProductResponse
        {
            Success = false,
            Message = $"Error creating product: {ex.Message}"
        };
    }
}

These are the important implementation details:

• Unique ID generation: Guid.NewGuid() Creates a unique identifier

• Timestamp management: DateTime.UtcNow Ensures consistent timezone handling

• Type conversion: Convert.ToDecimal() converts double to decimal for database storage

• Input validation: Checks for required fields and valid values

• Logging: Records successful operations and errors for debugging

Creating the GetProduct Service

The GetProduct method retrieves a single product by its ID. This is the "R" in CRUD (Read).

//Services/ProductService.cs
public override async Task<GetProductResponse> GetProduct(
    GetProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Validate and parse the product ID
        if (!Guid.TryParse(request.Id, out var productId))
        {
            return new GetProductResponse
            {
                Success = false,
                Message = "Invalid product ID format. Please provide a valid GUID."
            };
        }

        // Find product in database
        var product = await _dbContext.Products.FindAsync(productId);

        if (product == null)
        {
            _logger.LogWarning("Product not found with ID: {ProductId}", productId);

            return new GetProductResponse
            {
                Success = false,
                Message = "Product not found"
            };
        }

        _logger.LogInformation("Product retrieved successfully with ID: {ProductId}", productId);

        // Return success response with product data
        return new GetProductResponse
        {
            Success = true,
            Message = "Product retrieved successfully",
            Product = MapToProductModel(product)
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error retrieving product with ID: {ProductId}", request.Id);

        return new GetProductResponse
        {
            Success = false,
            Message = $"Error retrieving product: {ex.Message}"
        };
    }
}

Important implementation details:

• ID validation: Guid.TryParse() safely validates the ID format

• Database query: FindAsync() efficiently finds records by primary key

• Null checking: Handles cases where the product doesn't exist

• Detailed logging: Tracks both successful retrievals and missing products

Creating the ListProducts Service

The ListProducts method retrieves multiple products with pagination support. This is also part of the "R" in CRUD (Read).

// Services/ProductService.cs
public override async Task<ListProductsResponse> ListProducts(
    ListProductsRequest request, 
    ServerCallContext context)
{
    try
    {
        // Set default pagination values
        var pageSize = request.PageSize <= 0 ? 10 : Math.Min(request.PageSize, 100); // Max 100 items per page
        var page = request.Page <= 0 ? 1 : request.Page;

        // Calculate skip amount for pagination
        var skip = (page - 1) * pageSize;

        // Get total count for pagination metadata
        var totalCount = await _dbContext.Products.CountAsync();

        // Retrieve paginated products
        var products = await _dbContext.Products
            .OrderBy(p => p.Created) // Consistent ordering
            .Skip(skip)
            .Take(pageSize)
            .ToListAsync();

        // Create response
        var response = new ListProductsResponse
        {
            Success = true,
            Message = products.Any() 
                ? $"Retrieved {products.Count} products (Page {page} of {Math.Ceiling((double)totalCount / pageSize)})"
                : "No products found",
            TotalCount = totalCount
        };

        // Add products to response
        response.Products.AddRange(products.Select(MapToProductModel));

        _logger.LogInformation("Listed {ProductCount} products for page {Page}", products.Count, page);

        return response;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error retrieving products list");

        return new ListProductsResponse
        {
            Success = false,
            Message = $"Error retrieving products: {ex.Message}",
            TotalCount = 0
        };
    }
}

Here are the key implementation details:

• Pagination logic: Calculates skip and take values for efficient data retrieval

• Default values: Sets sensible defaults for page size and page number

• Performance optimization: Uses Skip() and Take() for database-level pagination

• Consistent ordering: OrderBy() ensures predictable results across requests

• Metadata: Returns total count for client-side pagination UI

Creating the UpdateProduct Service

The UpdateProduct method modifies existing products. This is the "U" in CRUD (Update).

// Services/ProductService.cs
public override async Task<UpdateProductResponse> UpdateProduct(
    UpdateProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Validate product ID
        if (!Guid.TryParse(request.Id, out var productId))
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Invalid product ID format. Please provide a valid GUID."
            };
        }

        // Input validation
        if (string.IsNullOrWhiteSpace(request.Name))
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Product name is required"
            };
        }

        if (request.Price <= 0)
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Product price must be greater than zero"
            };
        }

        // Find existing product
        var existingProduct = await _dbContext.Products.FindAsync(productId);

        if (existingProduct == null)
        {
            return new UpdateProductResponse
            {
                Success = false,
                Message = "Product not found"
            };
        }

        // Update product properties
        existingProduct.Name = request.Name;
        existingProduct.Description = request.Description;
        existingProduct.Price = Convert.ToDecimal(request.Price);
        existingProduct.Tags = request.Tags;
        existingProduct.Updated = DateTime.UtcNow; // Track when updated

        // Save changes to database
        await _dbContext.SaveChangesAsync();

        _logger.LogInformation("Product updated successfully with ID: {ProductId}", productId);

        // Return success response with updated product
        return new UpdateProductResponse
        {
            Success = true,
            Message = "Product updated successfully",
            Product = MapToProductModel(existingProduct)
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error updating product with ID: {ProductId}", request.Id);

        return new UpdateProductResponse
        {
            Success = false,
            Message = $"Error updating product: {ex.Message}"
        };
    }
}

Key details:

• Existence check: Verifies the product exists before attempting updates

• Selective updates: Only updates the fields provided in the request

• Timestamp tracking: Updates the Updated field to track modification time

• Input validation: Ensures data integrity before saving

• Atomic operation: All changes are saved together or not at all

Creating the DeleteProduct Service

The DeleteProduct method removes products from the database. This is the "D" in CRUD (Delete).

 // Services/ProductService.cs
public override async Task<DeleteProductResponse> DeleteProduct(
    DeleteProductRequest request, 
    ServerCallContext context)
{
    try
    {
        // Validate product ID
        if (!Guid.TryParse(request.Id, out var productId))
        {
            return new DeleteProductResponse
            {
                Success = false,
                Message = "Invalid product ID format. Please provide a valid GUID."
            };
        }

        // Find the product to delete
        var product = await _dbContext.Products.FindAsync(productId);

        if (product == null)
        {
            return new DeleteProductResponse
            {
                Success = false,
                Message = "Product not found"
            };
        }

        // Remove product from database
        _dbContext.Products.Remove(product);
        await _dbContext.SaveChangesAsync();

        _logger.LogInformation("Product deleted successfully with ID: {ProductId}", productId);

        // Return success response
        return new DeleteProductResponse
        {
            Success = true,
            Message = "Product deleted successfully"
        };
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error deleting product with ID: {ProductId}", request.Id);

        return new DeleteProductResponse
        {
            Success = false,
            Message = $"Error deleting product: {ex.Message}"
        };
    }
}

Key details:

• Soft vs hard delete: This implements hard delete (permanent removal)

• Existence verification: Checks if the product exists before deletion

• Clean removal: Uses Entity Framework's Remove() method

• Confirmation: Returns a success message confirming deletion

Complete ProductService Implementation

Here's your complete ProductService.cs file with all CRUD operations:

// Services/ProductService.cs
using Grpc.Core;
using Microsoft.EntityFrameworkCore;
using ProductGrpc.Data;
using ProductGrpc.Models;

namespace ProductGrpc.Services
{
    public class ProductService : Product.ProductServiceBase
    {
        private readonly AppDbContext _dbContext;
        private readonly ILogger<ProductService> _logger;

        public ProductService(AppDbContext dbContext, ILogger<ProductService> logger)
        {
            _dbContext = dbContext;
            _logger = logger;
        }

        // Helper method to map Product entity to ProductModel message
        private static ProductModel MapToProductModel(Product product)
        {
            return new ProductModel
            {
                Id = product.Id.ToString(),
                Name = product.Name,
                Description = product.Description,
                Price = (double)product.Price,
                CreatedAt = product.Created.ToString("yyyy-MM-ddTHH:mm:ssZ"),
                UpdatedAt = product.Updated.ToString("yyyy-MM-ddTHH:mm:ssZ"),
                Tags = product.Tags ?? string.Empty
            };
        }

        // All CRUD methods go here (as implemented above)
        // CreateProduct, GetProduct, ListProducts, UpdateProduct, DeleteProduct
    }
}

Excellent work! You've successfully implemented all CRUD operations:

• Create: Add new products with validation

• Read: Retrieve single products and paginated lists

• Update: Modify existing products with validation

• Delete: Remove products safely

What's Next?

Now that our gRPC service is fully implemented, we need to test it! In the next section, we'll learn how to test our gRPC endpoints using Postman.

How to Test gRPC Services with Postman

Testing gRPC services requires different tools and approaches compared to traditional REST APIs. While REST APIs use HTTP/1.1 with JSON payloads, gRPC uses HTTP/2 with binary Protocol Buffer messages. Fortunately, Postman provides excellent support for gRPC testing, making it easy to test our service without writing client code.

Why gRPC Testing is Different

Here are the important differences between gRPC and REST API testing summarized:

Why we need the proto file:

• gRPC requires the service contract (.proto file) to understand available methods

• Protocol Buffers need schema definition for serialization/deserialization

• Postman uses the proto file to generate the correct request/response structure

Setting Up Postman for gRPC Testing

Step 1: Launch Postman

Open Postman on your machine. You should see the main dashboard similar to this:

Step 2: Create a New gRPC Request

Click on "New" in the top-left corner or use the "+" button. Then select "gRPC Request" from the available options.

You should see a modal dialog with different request types:

Click on "gRPC Request" to create a new gRPC request.

Step 3: Configure the gRPC Request Interface

After creating a gRPC request, you'll see the gRPC request interface:

These are the notable components of the gRPC interface:

• Server URL: Where your gRPC service is running

• Service definition: Where you import your .proto file

• Method selection: Choose which RPC method to call

• Message body: Request payload based on proto definitions

Importing the Proto File

Step 4: Access Service Definition

Locate the "Service definition" section in the gRPC request interface. Then click on "Import .proto file" or a similar option.

Step 5: Import Your Proto File

1. Click "Select Files" or "Import" button

2. Navigate to your project directory

3. Go to the Protos folder

4. Select product.proto file

5. Click "Open" to import

File Path Structure:

YourProject/
├── Protos/
│   ├── greet.proto
│   └── product.proto    ← Select this file
└── ...

Step 6: Configure Import Settings

When importing, you'll see options like:

Import Configuration:

• Import as: Select "API"

• API name: Choose a descriptive name (for example, "ProductGrpc API")

• Import location: Select your workspace

You want to import as an API because it creates a reusable API definition, allows multiple team members to use the same proto definitions, and provides better organization for multiple services.

Step 7: Verify Successful Import

After successful import, you should see:

1. API Collection: Your named API appears in the left sidebar under "APIs."

2. Available Methods: All RPC methods from your proto file are listed

3. Request/Response Schemas: Postman understands your message structures

Understanding the gRPC Request Interface

Once connected, you'll see a method selection dropdown with the following:

• CreateProduct

• GetProduct

• ListProducts

• UpdateProduct

• DeleteProduct

Excellent! You've successfully created a gRPC request in Postman, imported your proto file, configured the server connection, and set up the API collection for reuse.

What's Next?

Now that Postman is configured with your proto file, you're ready to test each CRUD operation:

1. CreateProduct: Test adding new products

2. GetProduct: Test retrieving single products

3. ListProducts: Test pagination and listing

4. UpdateProduct: Test modifying existing products

5. DeleteProduct: Test removing products

In the next section, we'll walk through testing each operation with sample data and expected responses.

How to Test Product Creation

Now that we have Postman configured with our proto file, it's time to test our gRPC service! We'll start by testing the CreateProduct Method to add a new product to our database.

Request Structure

Before sending your first request in Postman, select the RPC method from the dropdown. The request body’s shape comes directly from the Protocol Buffer definitions in your .proto file. Postman renders those proto messages as JSON for easier editing, but the proto types still apply: each field must match the type defined in the schema (including nested messages, enums, and repeated fields).

Step 1: Select the CreateProduct Method

Open your gRPC request in Postman and click the method dropdown (should show available methods). Select "CreateProduct" from the list.

You should see all the methods we defined in our proto file:

• CreateProduct

• GetProduct

• ListProducts

• UpdateProduct

• DeleteProduct

Step 2: Request Schema

When you select CreateProduct, Postman automatically generates the request structure based on our CreateProductRequest message from the proto file:

Proto Definition Reminder:

message CreateProductRequest {
  string name = 1;
  string description = 2;
  double price = 3;
  string tags = 4;
}

Postman JSON Representation:

{
  "name": "",
  "description": "",
  "price": 0,
  "tags": ""
}

Step 3: Prepare Test Data

Let's create our first product with meaningful test data. In the request body, enter:

{
  "name": "MacBook Pro 16-inch",
  "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
  "price": 2499.99,
  "tags": "laptop, apple, professional"
}

So what are these fields?

• name: Product title (required, string)

• description: Detailed product information (string)

• price: Product cost (double/number, must be > 0)

• tags: Comma-separated keywords (string)

Step 4: Send the Request

Click the "Invoke" button (or "Send" depending on Postman version) and wait for the response (should be very fast for local testing). Then check the response status (should show success).

Step 5: Analyze the Response

If everything works correctly, you should receive a response like this:

{
  "success": true,
  "message": "Product created successfully",
  "product": {
    "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
    "name": "MacBook Pro 16-inch",
    "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
    "price": 2499.99,
    "created_at": "2024-01-15T16:11:38Z",
    "updated_at": "2024-01-15T16:11:38Z",
    "tags": "laptop, apple, professional"
  }
}

Response fields:

• success: Boolean indicating operation success

• message: Human-readable status message

• product: The created product with generated fields

  • id: Auto-generated GUID

  • created_at/updated_at: UTC timestamps

  • Other fields: Echo of the input data

Visual Confirmation in Postman

Here's how a successful request looks in Postman:

Congratulations! You've successfully made your first gRPC request using Postman! You’ve also created a product in the database, received a properly formatted response, and verified the auto-generated ID and timestamps.

What's Next?

Now that we've successfully tested product creation, let's test the other CRUD operations:

1. GetProduct: Retrieve the product we just created

2. ListProducts: See all products with pagination

3. UpdateProduct: Modify the existing product

4. DeleteProduct: Remove the product from the database

Each operation will help us verify that our complete gRPC service is working correctly.

How to Test All Product Operations

Now that we've successfully created a product, let's test all the remaining CRUD operations to ensure our complete gRPC service works correctly.

Get All Products (ListProducts)

The ListProducts method retrieves all products from our database with pagination support. Since we've created some products, we should be able to see them in the response.

Step 1: Select ListProducts Method

Click the method dropdown in your Postman gRPC request. Then select "ListProducts" from the available methods. Notice the request structure – it includes pagination parameters.

Step 2: Configure the Request

The ListProductsRequest supports pagination parameters:

{
  "page": 1,
  "pageSize": 10
}

Here’s what’s going on with these parameters:

• page: Which page of results to retrieve (default: 1)

• pageSize: Number of products per page (default: 10, max: 100)

Step 3: Send the Request

Click "Invoke" to send the request and wait for the response containing all your products.

Step 4: Response

You should receive a response like this:

{
  "success": true,
  "message": "Retrieved 2 products (Page 1 of 1)",
  "totalCount": 2,
  "products": [
    {
      "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
      "name": "MacBook Pro 16-inch",
      "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
      "price": 2499.99,
      "created_at": "2024-01-15T16:11:38Z",
      "updated_at": "2024-01-15T16:11:38Z",
      "tags": "laptop, apple, professional"
    },
    {
      "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
      "name": "iPhone 15 Pro",
      "description": "Latest iPhone with titanium design",
      "price": 999.99,
      "created_at": "2024-01-15T16:15:22Z",
      "updated_at": "2024-01-15T16:15:22Z",
      "tags": "smartphone, apple, premium"
    }
  ]
}

Response structure:

• success: Operation status

• message: Descriptive message with pagination info

• totalCount: Total number of products in the database

• products: Array of product objects

Testing Pagination

Let’s now test some different pagination scenarios:

Get the first 5 products:

{
  "page": 1,
  "pageSize": 5
}

Get the second page:

{
  "page": 2,
  "pageSize": 5
}

Get Product By ID (GetProduct)

The GetProduct method retrieves a single product using its unique ID. Unlike REST APIs, where the ID is part of the URL path, gRPC passes the ID in the message body.

Step 1: Select the GetProduct Method

Select "GetProduct" from the method dropdown. Notice that the request structure requires an ID field.

Step 2: Prepare the Request

Copy a product ID from your previous ListProducts response:

{
  "id": "920b98d2-4feb-4705-8303-ce6e28bd3694"
}

Important notes:

• ID Format: Must be a valid GUID string

• Case Sensitivity: GUIDs are case-insensitive

• Validation: Invalid GUIDs will return an error

Step 3: Send the Request

Paste a valid product ID from your ListProducts response. Click "Invoke" to send the request.

Step 4: Analyze the Response

Successful response:

{
  "success": true,
  "message": "Product retrieved successfully",
  "product": {
    "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
    "name": "MacBook Pro 16-inch",
    "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 512GB SSD",
    "price": 2499.99,
    "created_at": "2024-01-15T16:11:38Z",
    "updated_at": "2024-01-15T16:11:38Z",
    "tags": "laptop, apple, professional"
  }
}

Update Product (UpdateProduct)

The UpdateProduct method modifies an existing product. You need to provide the product ID and the fields you want to update.

Step 1: Select the UpdateProduct Method

Select "UpdateProduct" from the method dropdown. Review the request structure which includes ID and all updatable fields.

Step 2: Prepare the Update Request

{
  "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
  "name": "MacBook Pro 16-inch (Updated)",
  "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 1TB SSD - Updated Storage",
  "price": 2799.99,
  "tags": "laptop, apple, professional, updated"
}

Update guidelines:

• ID: Must match an existing product

• All Fields: Currently required (not partial updates)

• Price: Must be greater than 0

• Name: Cannot be empty

Step 3: Send the Update Request

Make sure the ID exists (use one from your ListProducts response). Then click "Invoke" to send the update.

Step 4: Verify the Update

Successful response:

{
  "success": true,
  "message": "Product updated successfully",
  "product": {
    "id": "920b98d2-4feb-4705-8303-ce6e28bd3694",
    "name": "MacBook Pro 16-inch (Updated)",
    "description": "Apple MacBook Pro with M2 Pro chip, 16GB RAM, 1TB SSD - Updated Storage",
    "price": 2799.99,
    "created_at": "2024-01-15T16:11:38Z",
    "updated_at": "2024-01-15T16:25:14Z",
    "tags": "laptop, apple, professional, updated"
  }
}

Notice the changes:

• updated_at: Timestamp changed to reflect the update

• Modified Fields: All updated fields reflect new values

• created_at: Remains unchanged (original creation time)

Delete Product By ID (DeleteProduct)

The DeleteProduct method permanently removes a product from the database using its ID.

Step 1: Select DeleteProduct Method

Select "DeleteProduct" from the method dropdown. Note the simple request structure – it only requires an ID.

Step 2: Prepare the Delete Request

{
  "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890"
}

⚠️ Warning: This operation permanently deletes the product. Make sure you're using the correct ID.

Step 3: Send the Delete Request

Double-check the product ID you want to delete. Click "Invoke" to send the delete request.

Step 4: Confirm Deletion

Successful response:

{
  "success": true,
  "message": "Product deleted successfully"
}

Verification steps:

1. Try GetProduct with the same ID – it should return "Product not found"

2. Run ListProducts – the product should no longer appear in the list

3. Check totalCount – should be reduced by 1

Conclusion

Congratulations! 🎉 You've successfully completed this comprehensive journey into building gRPC services with ASP.NET Core. Throughout this handbook, you've gained hands-on experience with one of the most powerful and efficient communication frameworks available for modern distributed applications.

What You've Accomplished

Let's recap the impressive skills and knowledge you've acquired:

Foundation building

• Set up a complete gRPC project from scratch using .NET CLI

• Configured SQLite database with Entity Framework Core

• Created robust data models with proper validation

• Implemented database migrations and seeding

Learning protocol buffers

• Designed comprehensive .proto files with service definitions

• Created strongly-typed message contracts for all CRUD operations

• Understood the advantages of binary serialization over JSON

• Implemented efficient data transfer objects (DTOs)

Service implementation

• Built a complete ProductService with all CRUD operations

• Implemented proper error handling and validation

• Added comprehensive logging for debugging and monitoring

• Created efficient pagination for large datasets

• Handled data mapping between entities and Protocol Buffer messages

Testing and validation

• Configured Postman for gRPC testing

• Tested all CRUD operations with real data

• Verified data integrity and proper response formatting

Key Technical Skills Gained

gRPC Expertise:

• Understanding of the HTTP/2 protocol advantages

• Protocol Buffer schema design and evolution

• Service-to-service communication patterns

• Performance optimization techniques

🔗 You can access the code in this GitHub Repository.

Thank You!

Thank you for following along with this comprehensive tutorial. Your dedication to learning these advanced concepts will serve you well in building the next generation of distributed applications.

Happy coding, and may your services be fast, reliable, and scalable!

If you want to learn more about .NET Core, you can subscribe to my YouTube channel here.

🔗 Connect with the author:

• GitHub: @CliffTech123

• Twitter: @Clifftech_Dev

• LinkedIn: Isaiah Clifford Opoku

Async programming is essential for creating responsive and efficient applications in JavaScript. TypeScript, a superset of JavaScript, makes it even easier to work with async programming.

There are several approaches to async programming in TypeScript, including using promises, async/await, and callbacks. We will cover each of these approaches in detail so that you can choose the best one(s) for your use case.

Table of Contents

1. Why is Async Programming Important?

2. How TypeScript Makes Async Programming Easier

3. How to Use Promises in TypeScript

   • How to Create a Promise

   • How to Chain Promises

4. How to Use Async / Await in TypeScript

5. How to Use Callbacks in TypeScript

6. Conclusion

Why is Async Programming Important?

Async programming is crucial for building responsive and efficient web applications. It allows tasks to run in the background while the rest of the program continues, keeping the user interface responsive to input. Also, async programming can boost overall performance by letting multiple tasks run at the same time.

There are many real-world examples of async programming, such as accessing user cameras and microphones and handling user input events. Even if you don't frequently create asynchronous functions, it's important to know how to use them correctly to make sure your application is reliable and performs well.

How TypeScript Makes Async Programming Easier

TypeScript offers several features that simplify async programming, including type safety, type inference, type checking, and type annotations.

With type safety, you can ensure your code behaves as expected, even when dealing with asynchronous functions. For instance, TypeScript can catch errors related to null and undefined values at compile time, saving you time and effort in debugging.

TypeScript's type inference and checking also reduce the amount of boilerplate code you need to write, making your code more concise and easier to read.

And TypeScript's type annotations provide clarity and documentation for your code, which is especially helpful when working with asynchronous functions that can be complex to understand.

Now let’s dive in and learn about these three key features of asynchronous programming: promises, async/await, and callbacks.

How to Use Promises in TypeScript

Promises are a powerful tool for handling asynchronous operations in TypeScript. For instance, you might use a promise to fetch data from an external API or to perform a time-consuming task in the background while your main thread keeps running.

To use a Promise, you create a new instance of the Promise class and pass it a function that carries out the asynchronous operation. This function should call the resolve method with the result when the operation succeeds or the reject method with an error if it fails.

Once the Promise is created, you can attach callbacks to it using the then method. These callbacks will be triggered when the Promise is fulfilled, with the resolved value passed as a parameter. If the Promise is rejected, you can attach an error handler using the catch method, which will be called with the reason for the rejection.

Using Promises offers several advantages over traditional callback-based methods. For example, Promises can help prevent "callback hell," a common issue in asynchronous code where nested callbacks become hard to read and maintain.

Promises also make error handling in asynchronous code easier, as you can use the catch method to manage errors that occur anywhere in the Promise chain.

Finally, Promises can simplify your code by providing a consistent, composable way to handle asynchronous operations, regardless of their underlying implementation.

How to Create a Promise

Promise syntax:

const myPromise = new Promise((resolve, reject) => {
  // Do some asynchronous operation
  // If the operation is successful, call resolve with the result
  // If the operation fails, call reject with an error object
});

myPromise
  .then((result) => {
    // Handle the successful result
  })
  .catch((error) => {
    // Handle the error
  });

// Example 1 on how to create a promise

function myAsyncFunction(): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    // Some asynchronous operation
    setTimeout(() => {
      // Successful operation resolves promiseCheck out my latest blog post on mastering async programming in TypeScript! Learn how to work with Promises, Async/Await, and Callbacks to write efficient and scalable code. Get ready to take your TypeScript skills to the next level!
      const success = true;

      if (success) {
        // Resolve the promise with the operation result if the operation was successful
        resolve(
          `The result is success and your operation result is ${operationResult}`
        );
      } else {
        const rejectCode: number = 404;
        const rejectMessage: string = `The result is failed and your operation result is ${rejectCode}`;
        // Reject the promise with the operation result if the operation failed
        reject(new Error(rejectMessage));
      }
    }, 2000);
  });
}

// Use the promise
myAsyncFunction()
  .then((result) => {
    console.log(result); // output : The result is success and your operation result is 4
  })
  .catch((error) => {
    console.error(error); // output : The result is failed and your operation result is 404
  });

In the example above, we have a function called myAsyncFunction() that returns a promise. We use the Promise constructor to create the promise, which takes a callback function with resolve and reject arguments. If the asynchronous operation is successful, we call the resolve function. If it fails, we call the reject function.

The promise object returned by the constructor has a then() method, which takes success and failure callback functions. If the promise resolves successfully, the success callback function is called with the result. If the promise is rejected, the failure callback function is called with an error message.

The promise object also has a catch() method used to handle errors that occur during the promise chain. The catch() method takes a callback function, which is called if any error occurs in the promise chain.

Now, let's move on to how to chain promises in TypeScript.

How to Chain Promises

Chaining promises allows you to perform multiple asynchronous operations in sequence or in parallel. This is helpful when you need to carry out several async tasks one after another or at the same time. For instance, you might need to fetch data asynchronously and then process it asynchronously.

Let's look at an example of how to chain promises:

// Example on how chaining promises works
// First promise
const promise1 = new Promise((resolve, reject) => {
  const functionOne: string = "This is the first promise function";
  setTimeout(() => {
    resolve(functionOne);
  }, 1000);
});

// Second promise
const promise2 = (data: number) => {
  const functionTwo: string = "This is the second second promise  function";
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve(` ${data}  '+'  ${functionTwo} `);
    }, 1000);
  });
};

// Chaining first and second promises together
promise1
  .then(promise2)
  .then((result) => {
    console.log(result); // output: This is the first promise function + This is the second second promise function
  })
  .catch((error) => {
    console.error(error);
  });

In the example above, we have two promises: promise1 and promise2. promise1 resolves after 1 second with the string "This is the first promise function." promise2 takes a number as input and returns a promise that resolves after 1 second with a string that combines the input number and the string "This is the second promise function."

We chain the two promises together using the then method. The output promise1 is passed as input to promise2. Finally, we use the then method again to log the output of promise2 to the console. If either promise1 or promise2 rejects, the error will be caught by the catch method.

Congratulations! You have learned how to create and chain promises in TypeScript. You can now use promises to perform asynchronous operations in TypeScript. Now, let's explore how Async/Await works in TypeScript.

How to Use Async / Await in TypeScript

Async/await is a syntax introduced in ES2017 to make working with Promises easier. It allows you to write asynchronous code that looks and feels like synchronous code.

In TypeScript, you can define an asynchronous function using the async keyword. This tells the compiler that the function is asynchronous and will return a Promise.

Now, let's see how to use async/await in TypeScript.

Async / Await Syntax:

// Async / Await Syntax in TypeScript
async function functionName(): Promise<ReturnType> {
  try {
    const result = await promise;
    // code to execute after promise resolves
    return result;
  } catch (error) {
    // code to execute if promise rejects
    throw error;
  }
}

In the example above, functionName is an async function that returns a Promise of ReturnType. The await the keyword is used to wait for the promise to resolve before moving to the next line of code.

The try/catch block is used to handle any errors that occur while running the code inside the async function. If an error happens, it will be caught by the catch block, where you can handle it appropriately.

Using Arrow Functions with Async / Await

You can also use arrow functions with async/await syntax in TypeScript:

const functionName = async (): Promise<ReturnType> => {
  try {
    const result = await promise;
    // code to execute after promise resolves
    return result;
  } catch (error) {
    // code to execute if promise rejects
    throw error;
  }
};

In the example above, functionName is defined as an arrow function that returns a Promise of ReturnType. The async keyword indicates that this is an asynchronous function, and the await keyword is used to wait for the promise to resolve before moving to the next line of code.

Async / Await with an API Call

Now, let's go beyond the syntax and fetch some data from an API using async/await.

interface User {
  id: number;
  name: string;
  email: string;
}

const fetchApi = async (): Promise<void> => {
  try {
    const response = await fetch("https://jsonplaceholder.typicode.com/users");

    if (!response.ok) {
      throw new Error(
        `Failed to fetch users (HTTP status code: ${response.status})`
      );
    }

    const data: User[] = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
    throw error;
  }
};

fetchApi();

Here, we’re fetching data from the JSONPlaceholder API, converting it to JSON, and then logging it to the console. This is a real-world example of how to use async/await in TypeScript.

You should see user information in the console. This image shows the output:

Async/Await with Axios API call

// Example 2 on how to use async / await in typescript

const fetchApi = async (): Promise<void> => {
  try {
    const response = await axios.get(
      "https://jsonplaceholder.typicode.com/users"
    );
    const data = await response.data;
    console.log(data);
  } catch (error) {
    console.error(error);
  }
};

fetchApi();

In the example above, we define the fetchApi() function using async/await and the Axios.get() method to make an HTTP GET request to the specified URL. We use await to wait for the response, then extract the data using the data property of the response object. Finally, we log the data to the console with console.log(). Any errors that occur are caught and logged to the console with console.error().

We can achieve this using Axios, so you should see the same result in the console.

This image shows the output when using Axios in the console:

Note: Before you try the code above, you need to install Axios using npm or yarn.

npm install axios

yarn add axios

If you're not familiar with Axios, you can learn more about it here.

You can see that we used a try and catch block to handle errors. The try and catch block is a method for managing errors in TypeScript. So, whenever you make API calls like we just did, make sure you use a try and catch block to handle any errors.

Now, let's explore a more advanced use of the try and catch block in TypeScript:

// Example 3 on how to use async / await in typescript

interface Recipe {
  id: number;
  name: string;
  ingredients: string[];
  instructions: string[];
  prepTimeMinutes: number;
  cookTimeMinutes: number;
  servings: number;
  difficulty: string;
  cuisine: string;
  caloriesPerServing: number;
  tags: string[];
  userId: number;
  image: string;
  rating: number;
  reviewCount: number;
  mealType: string[];
}

const fetchRecipes = async (): Promise<Recipe[] | string> => {
  const api = "https://dummyjson.com/recipes";
  try {
    const response = await fetch(api);

    if (!response.ok) {
      throw new Error(`Failed to fetch recipes: ${response.statusText}`);
    }

    const { recipes } = await response.json();
    return recipes; // Return the recipes array
  } catch (error) {
    console.error("Error fetching recipes:", error);
    if (error instanceof Error) {
      return error.message;
    }
    return "An unknown error occurred.";
  }
};

// Fetch and log recipes
fetchRecipes().then((data) => {
  if (Array.isArray(data)) {
    console.log("Recipes fetched successfully:", data);
  } else {
    console.error("Error message:", data);
  }
});

In the example above, we define an interface Recipe that outlines the structure of the data we expect from the API. We then create the fetchRecipes() function using async/await and the fetch() method to make an HTTP GET request to the specified API endpoint.

We use a try/catch block to handle any errors that might occur during the API request. If the request is successful, we extract the data property from the response using await and return it. If an error occurs, we check for an error message and return it as a string if it exists.

Finally, we call the fetchRecipes() function and use .then() to log the returned data to the console. This example demonstrates how to use async/await with try/catch blocks to handle errors in a more advanced scenario, where we need to extract data from a response object and return a custom error message.

This image shows the output result of the code:

Async / Await with Promise.all

Promise.all() is a method that takes an array of promises as input (an iterable) and returns a single Promise as output. This Promise resolves when all the input promises have been resolved or if the input iterable contains no promises. It rejects immediately if any of the input promises are rejected or if non-promises throw an error, and it will reject with the first rejection message or error.

// Example of using async / await with Promise.all
interface User {
  id: number;
  name: string;
  email: string;
  profilePicture: string;
}

interface Post {
  id: number;
  title: string;
  body: string;
}

interface Comment {
  id: number;
  postId: number;
  name: string;
  email: string;
  body: string;
}

const fetchApi = async <T>(url: string): Promise<T> => {
  try {
    const response = await fetch(url);
    if (response.ok) {
      const data = await response.json();
      return data;
    } else {
      throw new Error(`Network response was not ok for ${url}`);
    }
  } catch (error) {
    console.error(error);
    throw new Error(`Error fetching data from ${url}`);
  }
};

const fetchAllApis = async (): Promise<[User[], Post[], Comment[]]> => {
  try {
    const [users, posts, comments] = await Promise.all([
      fetchApi<User[]>("https://jsonplaceholder.typicode.com/users"),
      fetchApi<Post[]>("https://jsonplaceholder.typicode.com/posts"),
      fetchApi<Comment[]>("https://jsonplaceholder.typicode.com/comments"),
    ]);
    return [users, posts, comments];
  } catch (error) {
    console.error(error);
    throw new Error("Error fetching data from one or more APIs");
  }
};

fetchAllApis()
  .then(([users, posts, comments]) => {
    console.log("Users: ", users);
    console.log("Posts: ", posts);
    console.log("Comments: ", comments);
  })
  .catch((error) => console.error(error));

In the code above, we used Promise.all to fetch multiple APIs at the same time. If you have several APIs to fetch, you can use Promise.all to get them all at once. As you can see, we used map to loop through the array of APIs and then pass it to Promise.all to fetch them simultaneously.

The image below shows the output from the API calls:

Let's see how to use Promise.all with Axios:

// Example of using async / await with axios and Promise.all

const fetchApi = async () => {
  try {
    const urls = [
      "https://jsonplaceholder.typicode.com/users",
      "https://jsonplaceholder.typicode.com/posts",
    ];
    const responses = await Promise.all(urls.map((url) => axios.get(url)));
    const data = await Promise.all(responses.map((response) => response.data));
    console.log(data);
  } catch (error) {
    console.error(error);
  }
};

fetchApi();

In the example above, we're using Promise.all to fetch data from two different URLs at the same time. First, we create an array of URLs, then use the map to create an array of Promises from the axios.get calls. We pass this array to Promise.all, which returns an array of responses. Finally, we use the map again to get the data from each response and log it to the console.

How to Use Callbacks in TypeScript

A callback is a function passed as an argument to another function. The callback function is executed inside the other function. Callbacks ensure that a function doesn't run before a task is completed – but that it then runs right after the task finishes. They help us write asynchronous JavaScript code and prevent problems and errors.

// Example of using callbacks in typescript

const add = (a: number, b: number, callback: (result: number) => void) => {
  const result = a + b;
  callback(result);
};

add(10, 20, (result) => {
  console.log(result);
});

The image below shows the callback function:

Let's see another example of using callbacks in TypeScript:

// Example of using a callback function in TypeScript

type User = {
  name: string;
  email: string;
};

const fetchUserData = (
  id: number,
  callback: (error: Error | null, user: User | null) => void
) => {
  const api = `https://jsonplaceholder.typicode.com/users/${id}`;
  fetch(api)
    .then((response) => {
      if (response.ok) {
        return response.json();
      } else {
        throw new Error("Network response was not ok.");
      }
    })
    .then((data) => {
      const user: User = {
        name: data.name,
        email: data.email,
      };
      callback(null, user);
    })
    .catch((error) => {
      callback(error, null);
    });
};

// Usage of fetchUserData with a callback function
fetchUserData(1, (error, user) => {
  if (error) {
    console.error(error);
  } else {
    console.log(user);
  }
});

In the example above, we have a function called fetchUserData that takes an id and a callback as parameters. This callback is a function with two parameters: an error and a user.

The fetchUserData function retrieves user data from a JSONPlaceholder API endpoint using the id. If the fetch is successful, it creates an User object and passes it to the callback function with a null error. If there's an error during the fetch, it sends the error to the callback function with a null user.

To use the fetchUserData function with a callback, we provide an id and a callback function as arguments. The callback function checks for errors and logs the user data if there are no errors.

The image below shows the output of the API calls:

How to Use Callbacks Responsibly

While callbacks are fundamental to asynchronous programming in TypeScript, they require careful management to avoid "callback hell" – the pyramid-shaped, deeply nested code that becomes hard to read and maintain. Here's how to use callbacks effectively:

1. Avoid deep nesting

   • Flatten your code structure by breaking complex operations into named functions

   • Use promises or async/await for complex async workflows (more on this below)

2. Error handling first

   • Always follow the Node.js convention of (error, result) parameters

   • Check for errors at every level of nested callbacks

    function processData(input: string, callback: (err: Error | null, result?: string) => void) {
      // ... always call callback with error first
    }

3. Use type annotations

   • Leverage TypeScript's type system to enforce callback signatures

   • Define clear interfaces for callback parameters

    type ApiCallback = (error: Error | null, data?: ApiResponse) => void;

4. Consider control flow libraries
   For complex async operations, use utilities like async.js for:

   • Parallel execution

   • Series execution

   • Error handling pipelines

When to Use Callbacks vs. Alternatives

There are times when callbacks are a great choice, and other times when they’re not.

Callbacks are helpful when you’re working with async operations (single completion), interfacing with older libraries or APIs that expect callbacks, handling event listeners (like click listeners or websocket events) or creating lightweight utilities with simple async needs.

In other scenarios where you need to focus on writing maintainable code with a clear async flow, callbacks cause trouble and you should prefer promises or async-await. For example, when you need to chain multiple operations, handle complex error propagation, work with modern APIs (like the Fetch API or FS Promises), or use promise.all() for parallel execution.

Example migration from callbacks to promises:

// Callback version
function fetchUser(id: number, callback: (err: Error | null, user?: User) => void) {
  // ... 
}

// Promise version
async function fetchUserAsync(id: number): Promise<User> {
  // ...
}

// Usage with async/await
try {
  const user = await fetchUserAsync(1);
} catch (error) {
  // Handle error
}

The Evolution of Async Patterns

Modern TypeScript projects often use a mix: callbacks for event-driven patterns and promises/async-await for complex async logic. The key is choosing the right tool for your specific use case while maintaining code clarity.

Conclusion

In this article, we have learned about the different ways to handle asynchronous code in TypeScript. We have learned about callbacks, promises, async/await, and how to use them in TypeScript. We have also learned about this concept.

If you want to learn more about programming and how to become a better software engineer, you can subscribe to my YouTube channel CliffTech.

Thank you for reading my article. I hope you enjoyed it. If you have any questions, feel free to reach out to me.

Connect with me on social media:

• Twitter

• Github

• Linkedin

Different types of classes serve various purposes. For instance, organizing your logic to make your code easier to navigate is helpful when building an application.

You can group or separate your code into classes, and through inheritance, you can utilize different classes as needed. Classes help encapsulate your code, enabling you to reuse your logic in other application parts. Classes have many functionalities, and we will explore some of them in detail.

In this guide, we'll explore various types of classes in C# and how you can use them to create efficient and maintainable code.

Prerequisites

Before we proceed, you should have the following:

1. Basic knowledge of C#: you should understand C# syntax and basic programming constructs like variables, loops, and conditionals.

2. Familiarity with Object-Oriented Programming (OOP) concepts: you should know how to work with classes, objects, inheritance, polymorphism, encapsulation, and abstraction.

3. Familiarity with access modifiers: you should understand public, private, internal, and protected access modifiers.

4. Experience with C# IDE/Environment: you should be able to write and run C# programs using an IDE like Visual Studio.

If you want to learn more about C#, you can check out my YouTube channel: CliffTech.

Table of Contents

• Static Classes in C Sharp

• Sealed Classes in C Sharp

• Concrete Classes in C Sharp

• Abstract Classes in C Sharp

• Singleton Classes in C Sharp

• Generic Classes in C Sharp

• Internal Classes in C Sharp

• Nested Classes in C Sharp

• Partial Classes in C Sharp

• Conclusion

The first type of class we’ll discuss is the Static Class. Let’s dive in.

Static Classes in C Sharp

Static classes are a special type of class in C# designed to provide a collection of related utility methods and properties that do not rely on instance data.

Static classes in C# are a unique type of class designed to house a collection of related utility methods and properties that don't depend on instance data.

Unlike regular classes, static classes cannot be instantiated, and they exclusively contain static members. This characteristic means they cannot be inherited, making them perfect for organizing stateless methods that don't require the features of object-oriented programming.

In essence, when we refer to stateless grouping, it implies that there's no need to create an instance to call a static method – you can simply use the class or method name directly. This approach provides a clear and efficient way to manage utility functions, enhancing code organization and accessibility.

Example of a Static Class in C

Here's an example of a static class in C#:

namespace StaticClasses
{
// Define a static class
    public static class MathUtils
    {
        // Static method to add two numbers
        public static int Add(int a, int b)
        {
            return a + b;
        }

        // Static method to subtract two numbers
        public static int Subtract(int a, int b)
        {
            return a - b;
        }

       // Static method to multiply two numbers
        public static int Multiply(int a, int b)
        {
            return a * b;
        }
    }
}

In this example:

• The MathUtils class is defined as static, meaning it cannot be instantiated.

• It contains three static methods: Add, Subtract, and Multiply.

• These methods can be called directly on the MathUtils class without creating an instance.

Before you can use this, you need to call it in your Program.cs. When you create any C# application, the entry point is Program.cs. You’ll need to go there and make sure to call these classes so that you can execute them. This is what we will be doing for the rest of the section.

How to Use Static Methods in Program.cs

Now you can use the static methods defined in the MathUtils class as follows:

 // program.cs
namespace StaticClasses
{
    class Program
    {
        static void Main(string[] args)
        {
             // Call static methods from the MathUtils class
            int sum = MathUtils.Add(5, 3);
            // Call the static method Subtract from the MathUtils class
            int difference = MathUtils.Subtract(5, 3);

            // Call the static method Multiply from the MathUtils class
            int product = MathUtils.Multiply(5, 3);

            // Display the results of the sum method
            Console.WriteLine($"Sum: {sum}"); // Output: 8
            // Display the results of the difference method
            Console.WriteLine($"Difference: {difference}"); // Output: 2
            // Display the results of the product method
            Console.WriteLine($"Product: {product}");  // Output: 15
        }
    }
}

When to Use Statice Classes vs Methods

To decide when to use static classes or methods in C#, consider the following guidelines:

1. Use Static Classes when:

   • You need a collection of utility or helper methods that do not require any instance data.

   • The methods and properties are stateless and can be accessed globally without creating an object.

   • You want to group related functions that are not tied to a specific object state.

   • You need to ensure that the class cannot be instantiated or inherited.

2. Use Static Methods when:

   • You have a class that is mostly instance-based, but you need a few methods that do not depend on instance data.

   • The method performs a task that is independent of any object state and can be executed without an instance.

   • You want to provide a utility function within a class that can be accessed without creating an object of that class.

By using static classes and methods appropriately, you can enhance code organization, improve performance by avoiding unnecessary object creation, and ensure that certain functionalities are easily accessible throughout your application.

Key Points to Remember About Static Classes in C

• Cannot be Instantiated: You cannot create objects from a static class.

• Only static members: Static classes can only have static members. They do not support instance methods or fields.

• Sealed by default: Static classes are automatically sealed, so they cannot be inherited.

• Utility and helper methods: Static classes are usually used to group related utility or helper methods that don't need an object state.

Static classes help organize and access utility methods and properties clearly and simply, making them important for creating efficient and maintainable code.

Sealed Classes in C Sharp

Sealed classes are a special type of class in C# that cannot be inherited. You can use them to prevent other classes from deriving from them, which can be useful for creating immutable types or ensuring that a class's behavior remains unchanged.

By sealing a class, you ensure that it cannot be modified or extended, making it useful for scenarios where you want to provide a specific implementation without allowing further alterations.

Example of a Sealed Class in C

Here's an example of a sealed class in C#:

namespace SealedClasses
{

    // Define an abstract class
    public abstract class Shape
    {
        // Abstract method to calculate the area
        public abstract double CalculateArea();
    }

     // Define a sealed class
    public sealed class Rectangle : Shape
    {

        //  Properties
        public double Width { get; }
        public double Height { get; }

        // Constructor
        public Rectangle(double width, double height)
        {
            Width = width;
            Height = height;
        }

       // Implement the CalculateArea method
        public override double CalculateArea()
        {
            return Width * Height;
        }
    }
}

In this example:

• The Shape class is an abstract base class with an abstract method CalculateArea().

• The Rectangle class inherits from Shape and provides an implementation for CalculateArea().

• The Rectangle class is sealed, which means it cannot be inherited from. This ensures that the class's implementation cannot be modified or extended.

How to Use the Sealed Rectangle Class in the Program.cs

Here's how you can use the Rectangle class in a Program.cs file:

namespace SealedClasses
{
    class Program
    {
        static void Main(string[] args)
        {
            Rectangle rectangle = new Rectangle(5, 3);
            double area = rectangle.CalculateArea();

            Console.WriteLine($"Area of the rectangle: {area}"); // Output: Area of the rectangle: 15
        }
    }
}

In this example, the Rectangle class is sealed to ensure that its behavior cannot be changed through inheritance. This guarantees that the Rectangle class's implementation of CalculateArea() stays the same, which helps maintain consistent behavior.

When to Use Sealed Classes

Sealed classes are particularly useful in the following contexts:

1. Framework development: When developing frameworks or libraries, you might use sealed classes to lock down certain classes that are not intended to be extended by users. This helps maintain control over the framework's behavior and ensures that users cannot introduce bugs or inconsistencies by extending these classes.

2. Preventing inheritance: If a class is designed to be a specific implementation with no need for further customization or extension, sealing it prevents other developers from creating subclasses that might alter its intended functionality.

3. Finalizing class design: When a class has reached a point where its design is considered complete and no further changes or extensions are anticipated, sealing it can signal to other developers that the class should be used as-is.

4. Avoiding overriding: In scenarios where overriding methods could lead to incorrect behavior or security issues, sealing the class ensures that its methods cannot be overridden, preserving the original logic and functionality.

Key Points to Remember About Sealed Classes

• No inheritance: Sealed classes cannot be inherited, ensuring their behavior stays the same.

• Prevent modification: They prevent further inheritance, avoiding accidental changes or extensions.

• Immutable and specific: Sealed classes are useful for creating immutable classes or when you need a specific, unchangeable implementation.

Sealed Classes vs. Static Classes

You might wonder why we need sealed classes if static classes are already sealed. The key differences are:

• Static Classes are sealed and cannot be instantiated. They are used for grouping static methods and properties.

• Sealed Classes can be instantiated but cannot be inherited. This allows for creating objects that are protected from further subclassing.

Sealed classes offer flexibility in creating classes that can be used directly without the risk of modification through inheritance.

Concrete Classes in C Sharp

Concrete classes are essential in object-oriented programming in C#. They are fully implemented classes that you can use to create objects directly.

Unlike abstract classes or interfaces, concrete classes have complete implementations of all their methods and properties, making them versatile and fundamental to most C# applications.

A concrete class is not abstract. It includes full implementations of all its members—methods, properties, fields, and so on—and can be used to create objects. These classes represent real-world entities or concepts in your application, encapsulating both data (stored in fields or properties) and behavior (defined by methods).

Example: Defining a Concrete Class in C

Here's a simple example of a concrete class in C#:

// Define a concrete class
public class Animal
{
    public void Speak()
    {
        Console.WriteLine("The animal makes a sound.");
    }
}

// Define a derived class that inherits from the Animal class
public class Dog : Animal
{
    public void Bark()
    {
        Console.WriteLine("The dog barks.");
    }
}

In this example, the Animal class is a concrete class with a method Speak that represents a generic sound made by any animal. The Dog class inherits from Animal and adds a Bark method to represent a sound specific to dogs. Both Animal and Dog are concrete classes because they can be instantiated and used to create objects.

How to Instantiate and Use Concrete Classes

Here's how you can use the Dog class in a Program.cs file:

// program.cs
class Program
{
    static void Main(string[] args)
    {
        // Create an instance of the Dog class
        Dog myDog = new Dog();

        // Call the inherited method
        myDog.Speak(); // Output: The animal makes a sound.

        // Call the method defined in the Dog class
        myDog.Bark();  // Output: The dog barks.
    }
}

In this example, we create an instance of the Dog class called myDog. We first call the Speak method, which is inherited from the Animal class, and then the Bark method from the Dog class. This shows how concrete classes can include both inherited and unique behaviors.

Real-World Example: Concrete Class for a Product

To illustrate the practical application of concrete classes, consider the following example of a Product class:

// Define a concrete class for a product
public class Product
{
    // Data properties
    public string Name { get; set; }
    public decimal Price { get; set; }

    // Method to display product information
    public void DisplayInfo()
    {
        Console.WriteLine($"Product: {Name}, Price: {Price:C}");
    }
}

This Product class is a concrete class with properties Name and Price to store information about a product. The DisplayInfo method provides a way to display the product’s details.

How to Use the Product Class

Here's how you can use the Product class:

class Program
{
    static void Main(string[] args)
    {
        // Create an instance of the Product class
        Product product = new Product
        {
            Name = "Laptop",
            Price = 1299.99m
        };

        // Display product information
        product.DisplayInfo(); // Output: Product: Laptop, Price: $1,299.99
    }
}

In this scenario, the Product class is used to create a product object. The DisplayInfo method is called to show the product's name and price. This demonstrates how concrete classes are used to model and work with real-world data.

Key Points to Remember About Concrete Classes

• Instantiable: Concrete classes can be instantiated, allowing you to create objects that represent specific entities or concepts in your application.

• Complete implementation: Concrete classes provide full implementations of all methods and properties, unlike abstract classes or interfaces.

• Common use: They are the most common type of class in C#, used to define objects with specific behavior and data.

Concrete classes are essential for C# development, enabling you to define and work with objects that model real-world entities within your applications. Understanding how to effectively use concrete classes is crucial for building robust, object-oriented software.

Abstract Classes in C Sharp

In C#, abstract classes are a powerful feature that allow you to define a blueprint for other classes without providing complete implementations. They serve as base classes that cannot be instantiated directly but can be inherited by other classes that will provide specific implementations for the abstract methods defined within them. This design helps enforce consistency across related classes while allowing flexibility in how certain behaviors are implemented.

What Does "Instantiated" Mean?

Before exploring abstract classes, let's clarify what it means to instantiate a class. Instantiation is the process of creating an object from a class. When you use the new keyword in C#, you are creating an instance (or object) of that class.

But abstract classes cannot be instantiated directly. They must be inherited by a non-abstract (concrete) class that provides implementations for the abstract methods.

Understanding Abstract Classes and Abstract Methods

Abstract classes are classes you can't create objects from directly. They act as templates for other classes. They can have both complete methods and methods without a body (abstract methods). Abstract classes help set up a common interface and shared behavior for related classes.

Abstract methods, on the other hand, are methods in an abstract class that don't have a body. Any non-abstract class that inherits from the abstract class must provide a body for these methods. This ensures all subclasses have a consistent interface.

Real-World Example: Bank Account Management

Let's explore a real-world example to illustrate the concept of abstract classes and abstract methods in C#.

using System;

// define an abstract class
namespace AbstractClasses
{
    // Abstract class
    public abstract class BankAccount
    {
        // Properties
        public string AccountNumber { get; private set; }
        public decimal Balance { get; protected set; }

        // Constructor
        public BankAccount(string accountNumber, decimal initialBalance)
        {
            AccountNumber = accountNumber;
            Balance = initialBalance;
        }

        // Abstract methods
        public abstract void Deposit(decimal amount);
        public abstract void Withdraw(decimal amount);
        public abstract void DisplayAccountInfo();
    }

    // Derived class: SavingsAccount
    public class SavingsAccount : BankAccount
    {
        private decimal interestRate;

        public SavingsAccount(string accountNumber, decimal initialBalance, decimal interestRate)
            : base(accountNumber, initialBalance)
        {
            this.interestRate = interestRate;
        }

        // Implementing abstract methods
        public override void Deposit(decimal amount)
        {
            Balance += amount;
            Console.WriteLine($"Deposited {amount} to Savings Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void Withdraw(decimal amount)
        {
            if (amount > Balance)
            {
                throw new InvalidOperationException("Insufficient funds.");
            }
            Balance -= amount;
            Console.WriteLine($"Withdrew {amount} from Savings Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void DisplayAccountInfo()
        {
            Console.WriteLine($"Savings Account {AccountNumber} - Balance: {Balance}, Interest Rate: {interestRate}%");
        }
    }

    // Derived class: CheckingAccount
    public class CheckingAccount : BankAccount
    {
        private decimal overdraftLimit;

        public CheckingAccount(string accountNumber, decimal initialBalance, decimal overdraftLimit)
            : base(accountNumber, initialBalance)
        {
            this.overdraftLimit = overdraftLimit;
        }

        // Implementing abstract methods
        public override void Deposit(decimal amount)
        {
            Balance += amount;
            Console.WriteLine($"Deposited {amount} to Checking Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void Withdraw(decimal amount)
        {
            if (amount > Balance + overdraftLimit)
            {
                throw new InvalidOperationException("Overdraft limit exceeded.");
            }
            Balance -= amount;
            Console.WriteLine($"Withdrew {amount} from Checking Account {AccountNumber}. New Balance: {Balance}");
        }

        public override void DisplayAccountInfo()
        {
            Console.WriteLine($"Checking Account {AccountNumber} - Balance: {Balance}, Overdraft Limit: {overdraftLimit}");
        }
    }
}

In this example, the BankAccount class is an abstract class that defines a common interface for different types of bank accounts. It includes abstract methods like Deposit, Withdraw, and DisplayAccountInfo, which must be implemented by any class that inherits from BankAccount.

The SavingsAccount and CheckingAccount classes inherit from BankAccount and provide specific implementations for these abstract methods. This design enforces that every type of bank account must implement deposit, withdrawal, and display functions, while still allowing each account type to implement these functions in a way that makes sense for that specific type.

How to Use Abstract Classes in a Program

Let's see how we can use the SavingsAccount and CheckingAccount classes in a Program.cs file.

namespace AbstractClasses
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a savings account
            BankAccount savings = new SavingsAccount("SA123", 1000, 1.5m);
            // Create a checking account
            BankAccount checking = new CheckingAccount("CA123", 500, 200);

            // Deposit and withdraw from the savings account
            savings.DisplayAccountInfo();

           // Deposit and withdraw from the checking account
            savings.Deposit(200);

            savings.Withdraw(100);
            // Display the updated account information
            savings.DisplayAccountInfo();

            checking.DisplayAccountInfo();

             // Deposit and withdraw from the checking account
            checking.Deposit(300);

            checking.Withdraw(600);

            // Display the updated account information
            checking.DisplayAccountInfo();

            try
            {
                checking.Withdraw(200);
            }
            catch (InvalidOperationException ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }

            checking.DisplayAccountInfo();
        }
    }
}

This program will produce the following output:

Savings Account SA123 - Balance: 1000, Interest Rate: 1.5%
Deposited 200 to Savings Account SA123. New Balance: 1200
Withdrew 100 from Savings Account SA123. New Balance: 1100
Savings Account SA123 - Balance: 1100, Interest Rate: 1.5%
Checking Account CA123 - Balance: 500, Overdraft Limit: 200
Deposited 300 to Checking Account CA123. New Balance: 800
Withdrew 600 from Checking Account CA123. New Balance: 200
Checking Account CA123 - Balance: 200, Overdraft Limit: 200
Withdrew 200 from Checking Account CA123. New Balance: 0
Checking Account CA123 - Balance: 0, Overdraft Limit: 200

In this example, the SavingsAccount and CheckingAccount objects are created, and the abstract methods Deposit, Withdraw, and DisplayAccountInfo are called. The abstract class BankAccount ensures that both account types have these methods, while the derived classes provide the specific functionality.

Key Points to Remember About Abstract Classes

• Cannot be instantiated: You can't create an instance of an abstract class directly. A subclass must inherit it and provide the implementations for the abstract methods.

• Contain abstract methods: Abstract methods in an abstract class have no body. Any non-abstract class that inherits from the abstract class must implement these methods.

• Define common interfaces: Abstract classes set a common interface for related classes, ensuring they are consistent while allowing different implementations.

Abstract classes are important in C#. They help enforce a structure across related classes but still allow for specific details. By using abstract classes, you can make your code more organized, easier to maintain, and extend.

Singleton Classes in C Sharp

Singleton classes are a design pattern that restricts the instantiation of a class to one single instance. This is particularly useful when you need a single, shared resource across your application, such as a configuration manager, logging service, or database connection.

Why Use Singleton Classes in C#?

Imagine you have a class responsible for managing a database connection. You don’t want multiple instances of this class running around, potentially causing issues with resource management or inconsistent data. A Singleton class ensures that only one instance is created and provides a global point of access to it.

Example: Defining a Singleton Class

Let’s now see how you can implement a Singleton class in C#:

// Define a singleton class
public class Singleton
{
    private static Singleton instance;
    private static readonly object lockObject = new object();

    // Private constructor prevents instantiation from outside the class
    private Singleton()
    {
    }

    // Public property to access the single instance of the class
    public static Singleton Instance
    {
        get
        {
            // Ensure thread safety
            lock (lockObject)
            {
                if (instance == null)
                {
                    instance = new Singleton();
                }
            }
            return instance;
        }
    }

    // Example method to demonstrate the singleton instance
    public void PrintMessage()
    {
        Console.WriteLine("Hello, I am a singleton class.");
    }
}

In this example, the Singleton class is defined with a private constructor, which prevents other classes from creating new instances. The static property Instance returns the single instance of the class, creating it if it doesn't already exist. The lockObject ensures that the class is thread-safe, meaning that even in a multi-threaded environment, only one instance will be created.

The PrintMessage method is just a simple example to show that the Singleton instance can be used like any other class instance.

How to Use the Singleton Class in Program.cs

Now let’s see how you can use this Singleton class in your application:

class Program
{
    static void Main(string[] args)
    {
        // Retrieve the single instance of the Singleton class
        Singleton singleton1 = Singleton.Instance;
        singleton1.PrintMessage(); // Output: Hello, I am a singleton class.

        // Retrieve the instance again
        Singleton singleton2 = Singleton.Instance;

        // Check if both instances are the same
        Console.WriteLine(singleton1 == singleton2); // Output: True
    }
}

In this example, we retrieve the Singleton instance twice. Because the class is a Singleton, both singleton1 and singleton2 refer to the same instance. The == operator confirms this by returning true.

How to Extend the Singleton Example

You can expand the Singleton pattern to handle more complex scenarios. For example, you could initialize the Singleton instance with configuration data:

public class ConfigurationManager
{
    private static ConfigurationManager instance;
    private readonly Dictionary<string, string> settings = new Dictionary<string, string>();

    private ConfigurationManager()
    {
        // Simulate loading settings from a configuration file
        settings["AppName"] = "MyApplication";
        settings["Version"] = "1.0.0";
    }

    public static ConfigurationManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = new ConfigurationManager();
            }
            return instance;
        }
    }

    public string GetSetting(string key)
    {
        return settings.ContainsKey(key) ? settings[key] : null;
    }
}

Here, ConfigurationManager is a Singleton class that loads and manages application settings. The GetSetting method allows you to retrieve specific configuration values, ensuring that all parts of your application use the same settings.

Key Points to Remember About Singleton Classes

• Single instance: Singleton classes ensure that only one instance of the class exists in the application.

• Global access: Singleton provides a global point of access to the instance, making it easy to use across different parts of your application.

• Thread safety: In multi-threaded environments, ensure your Singleton is thread-safe to avoid creating multiple instances.

• Use cases: Common use cases for Singleton include managing configurations, logging services, and database connections.

Singleton classes are a fundamental design pattern in software engineering, offering a simple yet powerful way to manage shared resources. Understanding and correctly implementing Singletons can help you write more efficient and maintainable code.

Generic Classes in C Sharp

Generic classes in C# provide a powerful way to create reusable and type-safe code. By using generic classes, you can design a single class that works with any data type, eliminating the need for type-specific implementations. This makes your code more flexible and reduces redundancy.

Why Use Generic Classes?

Imagine you need to implement a stack that stores integers. Later, you might need another stack to store strings.

Instead of writing two separate classes, you can write one generic stack class that can handle both data types—and any others you might need. Generic classes help you avoid code duplication and make your codebase easier to maintain.

Example: Defining a Generic Class

Let’s take a look at a simple implementation of a generic stack class:

// Define a generic class
public class Stack<T>
{
    private List<T> items = new List<T>();

    public void Push(T item)
    {
        items.Add(item);
    }

    public T Pop()
    {
        if (items.Count == 0)
        {
            throw new InvalidOperationException("The stack is empty.");
        }
        T item = items[items.Count - 1];
        items.RemoveAt(items.Count - 1);
        return item;
    }

    public T Peek()
    {
        if (items.Count == 0)
        {
            throw new InvalidOperationException("The stack is empty.");
        }
        return items[items.Count - 1];
    }

    public bool IsEmpty()
    {
        return items.Count == 0;
    }
}

In this example, the Stack<T> class is defined with a type parameter T. This type parameter is a placeholder that represents the type of data the stack will store. The class includes methods like Push to add an item to the stack, Pop to remove and return the top item, Peek to view the top item without removing it, and IsEmpty to check if the stack is empty.

Because Stack<T> is generic, you can use it with any data type, whether it's int, string, or even a custom class.

How to Use the Stack Class in Program.cs

Let’s see how this generic Stack class can be used in a program:

class Program
{
    static void Main(string[] args)
    {
        // Stack for integers
        Stack<int> intStack = new Stack<int>();
        intStack.Push(10);
        intStack.Push(20);
        Console.WriteLine(intStack.Pop()); // Output: 20
        Console.WriteLine(intStack.Peek()); // Output: 10

        // Stack for strings
        Stack<string> stringStack = new Stack<string>();
        stringStack.Push("Hello");
        stringStack.Push("World");
        Console.WriteLine(stringStack.Pop()); // Output: World
        Console.WriteLine(stringStack.Peek()); // Output: Hello
    }
}

In this example, we create two instances of the Stack class: one that stores integers and another that stores strings. The flexibility of generics allows us to use the same class to work with different data types, making our code more reusable and concise.

How to Extend the Generic Class

Let’s take it a step further and extend our Stack class to include a method that returns all items as an array:

public T[] ToArray()
{
    return items.ToArray();
}

Now, you can easily convert the stack’s items into an array:

int[] intArray = intStack.ToArray();
string[] stringArray = stringStack.ToArray();

This extension further showcases the power of generics, allowing the same method to work with different data types seamlessly.

Key Points to Remember About Generic Classes

• Flexibility: Generic classes can handle any data type, making them adaptable and reusable.

• Type safety: Using type parameters ensures that your code is type-safe, catching errors during compile-time instead of runtime.

• Code reuse: Generics remove the need to duplicate code for different data types, resulting in cleaner and easier-to-maintain code.

• Type parameters: Generic classes use type parameters as placeholders for the actual data types you will use when creating an instance of the class.

Generic classes are crucial in C# for building flexible, reusable, and type-safe code. By learning and using generics, you can create more reliable and maintainable applications.

Internal Classes in C Sharp

Internal classes in C# are a powerful way to encapsulate implementation details within an assembly. By using the internal access modifier, you can restrict access to certain classes, ensuring they are only accessible within the same assembly.

This is particularly useful for hiding complex logic or utility classes that are not intended to be exposed to the public API of your library or application.

Why Use Internal Classes?

In a large application, you may have classes that should only be used internally by your code and not by external consumers. For example, helper classes, utility functions, or components of a larger system that do not need to be exposed outside the assembly can be marked as internal. This ensures that your public API remains clean and focused while still allowing full functionality within the assembly.

Example: Defining an Internal Class

Let’s consider a scenario where you have a library that processes orders. You might have a class that handles the complex logic of calculating discounts, but you don't want this class to be accessible to users of your library. Instead, you only expose the main OrderProcessor class, keeping the discount logic hidden with an internal class.

// Define a public class that uses an internal class
public class OrderProcessor
{
    public void ProcessOrder(int orderId)
    {
        // Internal class is used here
        DiscountCalculator calculator = new DiscountCalculator();
        decimal discount = calculator.CalculateDiscount(orderId);
        Console.WriteLine($"Order {orderId} processed with a discount of {discount:C}");
    }

    // Internal class that handles discount calculations
    internal class DiscountCalculator
    {
        public decimal CalculateDiscount(int orderId)
        {
            // Complex discount calculation logic
            return orderId * 0.05m;
        }
    }
}

In this example, the DiscountCalculator class is marked as internal, meaning it’s only accessible within the assembly. The OrderProcessor class, which is public, uses this internal class to process orders. External users of the library can call ProcessOrder without needing to know about or interact with the DiscountCalculator class.

How to Use the Internal Class in Program.cs

Now, let's see how this works in practice:

class Program
{
    static void Main(string[] args)
    {
        OrderProcessor processor = new OrderProcessor();
        processor.ProcessOrder(12345); // Output: Order 12345 processed with a discount of $617.25
    }
}

In this example, the ProcessOrder method is publicly accessible, but the internal workings of discount calculation remain hidden, providing a clean and secure API.

Key Points to Remember About Internal Classes

• Limited access: Internal classes can only be accessed within the same assembly, which helps keep your public API simple and focused.

• Encapsulation: They are used to hide implementation details, like helper functions or complex logic, that shouldn't be publicly visible.

• Visibility control: The internal access modifier lets you control which classes and members are visible, ensuring only the necessary parts of your code are accessible to other assemblies.

Internal classes are important for managing complex applications, allowing you to control what parts of your code can be accessed from outside your assembly. By hiding details and limiting access, you can keep your codebase clean, easy to maintain, and secure.

Nested Classes in C Sharp

Nested classes in C# are defined within another class. This structure is useful for grouping related classes together and encapsulating the implementation details. Nested classes can be either static or non-static, and they have direct access to the private members of their enclosing class.

Why Use Nested Classes?

Nested classes are particularly useful when a class is closely tied to the logic of another class and isn’t meant to be used independently. They allow you to encapsulate helper classes, hide them from other parts of the program, and keep related code together. This can lead to a cleaner, more organized codebase.

Example: Defining a Nested Class

Let’s consider a scenario where we have a class that represents a Car and another class that represents a Engine. Since the Engine class is closely related to the Car class and doesn’t make much sense on its own, we can define it as a nested class within Car.

// Define a class with a nested class
public class Car
{
    // Define private fields
    private string model;
    private Engine carEngine;

   // Constructor
    public Car(string model)
    {
        this.model = model;
        carEngine = new Engine();
    }


    // Method to start the car
    public void StartCar()
    {
        carEngine.StartEngine();
        Console.WriteLine($"{model} is starting...");
    }

    // Nested class
    public class Engine
    {
        public void StartEngine()
        {
            Console.WriteLine("Engine started.");
        }
    }
}

In this example, the Car class has a private field model and a method StartCar that starts the car. The Engine class is nested within the Car class and contains a StartEngine method. By nesting Engine inside Car, we express the close relationship between the two.

How to Use the Nested Class in Program.cs

Let’s see how we can use the Car class and its nested Engine class in a program:

class Program
{
    static void Main(string[] args)
    {
        Car myCar = new Car("Toyota");
        myCar.StartCar(); // Output: Engine started. Toyota is starting...

        // Although you can create an instance of the nested class separately, it usually makes sense to use it through the outer class
        Car.Engine engine = new Car.Engine();
        engine.StartEngine(); // Output: Engine started.
    }
}

In this example, we create an instance of the Car class and call the StartCar method, which internally calls the StartEngine method of the nested Engine class. While it's possible to instantiate the nested class separately, it’s more common to access it through the outer class, emphasizing the relationship between the two.

Key Points to Remember About Nested Classes

• Encapsulation: Nested classes keep details hidden that shouldn't be seen outside the main class.

• Access to private members: Nested classes can access private parts of the main class, making them good for helper classes that need to work with the main class's internal parts.

• Organization: Use nested classes to keep related classes together, which makes the code cleaner and more organized.

• Static or non-static: Nested classes can be static or non-static. Static nested classes can't access the instance parts of the main class directly, but non-static nested classes can.

Nested classes are a useful way to organize your code, especially for complex objects with closely related parts. Keeping related classes together makes your code easier to manage and maintain.

Partial Classes in C Sharp

Partial classes in C# allow you to split a class definition across multiple files. This feature is particularly useful in large projects, where it can be beneficial to break a complex class into smaller, more manageable sections.

By using the partial keyword, you can organize your code better, especially when working with generated code or collaborating in a team environment.

Why Use Partial Classes?

Imagine you’re working on a large application where a single class contains hundreds of lines of code. This can become difficult to manage and maintain. By using partial classes, you can divide the class into logical parts, each residing in a separate file. This not only makes the code more readable but also allows multiple developers to work on different parts of the class simultaneously without causing merge conflicts.

Example: Defining a Partial Class in C

Let’s say we have a class that handles various operations for an employee management system. Instead of putting all methods in one file, we can split them across multiple files using partial classes.

File 1: PartialClass_Methods1.cs

// Define a partial class
public partial class EmployeeOperations
{
    public void AddEmployee(string name)
    {
        Console.WriteLine($"Employee {name} added.");
    }
}

File 2: PartialClass_Methods2.cs

// Define the other part of the partial class
public partial class EmployeeOperations
{
    public void RemoveEmployee(string name)
    {
        Console.WriteLine($"Employee {name} removed.");
    }
}

In these examples, the EmployeeOperations class is split into two files, each containing a part of the class. The first file handles adding employees, while the second file handles removing them.

How to Use the Partial Class in Program.cs

Now, let’s use the EmployeeOperations class in our Program.cs file:

class Program
{
    static void Main(string[] args)
    {
        EmployeeOperations operations = new EmployeeOperations();

        operations.AddEmployee("John Doe");    // Output: Employee John Doe added.
        operations.RemoveEmployee("John Doe"); // Output: Employee John Doe removed.
    }
}

In this example, the EmployeeOperations class, although defined in multiple files, behaves like a single class. The methods AddEmployee and RemoveEmployee are seamlessly combined, providing a clean and organized way to manage operations.

Key Points to Remember About Partial Classes

• Code organization: Partial classes help keep large classes organized by splitting them into smaller, focused sections.

• Team collaboration: Multiple developers can work on different parts of the same class without interfering with each other’s code.

• Generated code: Often used with auto-generated code, where part of the class is generated by a tool, and the rest is written manually.

Partial classes are a powerful feature in C# that allows for better code management, especially in large-scale applications. By breaking down a class into logical components, you can maintain clean, readable, and maintainable code.

Conclusion

Classes are the building blocks of object-oriented programming in C#. By understanding the different types of classes—abstract, static, sealed, concrete, and singleton—you can create well-structured, maintainable, and efficient code.

Whether you’re designing utility classes, defining abstract interfaces, or encapsulating complex logic, classes play a crucial role in shaping your application’s architecture.

Imagine building robust APIs with minimal code and zero boilerplate—no more wrestling with controllers, routing, or middleware. That’s what minimal APIs allow you to do. The idea with these APIs is to streamline the development process, making it incredibly easy and efficient.

In this article, we'll dive into the world of minimal APIs in .NET 8 and guide you through creating a fully functional bookstore API. You'll learn how to get all books, retrieve a book by its ID, add new books, and even delete books. Let’s get started.

Table of Contents

• Prerequisites

• Introduction to Minimal APIs

• How to Create a Minimal API

• HTTP Methods in Controller-based and Minimal APIs

• Minimal API Project Files

• How to Create the Models

• How to Create the Database Context

• How to Create a Contract

• How to Add Services

• How to Create Exceptions

• How to Create the API Endpoints

• How to Add Seed Data to the Database

• How to Perform a Migration

• How to Test the API Endpoints

• Conclusion

Prerequisites

Before we get going, make sure you have the following prerequisites installed on your machine:

• .NET 8 SDK

• Visual Studio Code or any other code editor of your choice

• C# Dev Kit for Visual Studio Code

Alternatively, you can use Visual Studio 2022, which comes with built-in support for .NET 8. But in this article, we'll be using Visual Studio Code. It’s lightweight, easy to use, and cross-platform.

We’ll use Swagger UI to test our API. Swagger UI is a powerful tool that allows you to interact with your API directly from your browser. It provides a user-friendly interface to test your API endpoints, making it easier to test and debug your API.

When you create a new project, it will automatically install the necessary packages and configure the project to use Swagger UI. .NET 8 includes Swagger UI by default, so whether you create your application in Visual Studio or with .NET, Swagger UI will be configured for you.

Run your application, and the Swagger UI will automatically open in your browser – but since we are using VS Code, we need to click on the port number on our terminal.

You can find the source code for this project on GitHub.

Introduction to Minimal APIs

Imagine working in a codebase with numerous endpoints, making it quite large and complex. Traditionally, building an API in ASP.NET Core involves using controllers, routing, middleware, and a significant amount of boilerplate code. But there are two approaches to building an API in ASP.NET Core: the traditional way and the minimal way.

The traditional way is familiar to most developers, involving controllers and extensive infrastructure code. The minimal way, introduced in .NET 6, allows you to create APIs with minimal code and zero boilerplate. This approach simplifies the development process, enabling you to focus on writing business logic rather than dealing with infrastructure code.

Minimal APIs are lightweight, fast, and perfect for building small to medium-sized APIs. They are ideal for prototyping, building microservices, or creating simple APIs that don't require much complexity. In this handbook, we'll explore the world of minimal APIs in .NET 6 and learn how to create a fully functional bookstore API from scratch.

How to Create a Minimal API

Creating a minimal API is straightforward when using the dotnet CLI, as the default template is already a minimal API. But if you use Visual Studio, you'll need to remove the boilerplate code that comes with the project template.

Let's start by using the dotnet CLI to create a minimal API project.

dotnet new webapi  -n BookStoreApi

The dotnet new webapi command creates a new minimal API project named BookStoreApi. This project contains the necessary files and folders to get you started.

Let's explore the project structure:

• Program.cs: The entry point of the application, where the host is configured.

• bookapi-minimal.sln: The solution file that contains the project.

• bookapi-minimal.http: A file that contains sample HTTP requests to test the API.

• bookapi-minimal.csproj: The project file that contains the project configuration.

• appsettings.json: The configuration file that stores application settings.

• appsettings.Development.json : The configuration file for the development environment.

When you open the program.cs file, you'll notice that the code is minimal. The Program.cs file contains the following code:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

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

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

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")
.WithOpenApi();

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

If you don't fully understand the code yet, don't worry—we'll cover it in detail in the upcoming sections. The key takeaway is that minimal APIs require very little code, which is one of their main advantages.

The default code sets up a simple weather forecast API that you can use to test your setup. It generates a list of weather forecasts and returns them when you make a GET request to the /weatherforecast endpoint. Also, the code includes Swagger UI to help you test the API.

Pay special attention to the app.MapGet method, which maps a route to a handler function. In this case, it maps the /weatherforecast route to a function that returns a list of weather forecasts. We'll use similar methods to create our own endpoints in the next sections.

Before we start creating our project folder structure, let's understand the HTTP methods in both Controller-based and Minimal APIs.

HTTP Methods in Controller-based and Minimal APIs

In a Controller-based approach, which is the traditional way of creating web APIs, you need to create a controller class and define methods for each HTTP method. For example:

• To create a GET method, you use the [HttpGet] attribute.

• To create a POST method, you use the [HttpPost] attribute.

• To create a PUT method, you use the [HttpPut] attribute.

• To create a DELETE method, you use the [HttpDelete] attribute.

This is how endpoints are created in a Controller-based approach.

In contrast, Minimal APIs use methods like app.MapGet, app.MapPost, app.MapPut, and app.MapDelete to create endpoints. This is the main difference between the two approaches: Controller-based APIs use attributes to define endpoints, while Minimal APIs use methods.

Now that you understand how to handle HTTP requests in both Controller-based and Minimal APIs, let's create our project folder structure.

Before we create our project folder structure, let's first run what we have. As we learned earlier, when you create a project with either Visual Studio or .NET CLI, it comes with a default WeatherForecast project which we can run and see on the UI. Let's run it to ensure everything works before we go on to create our project folder.

Run this command:

dotnet run

You should see the following output:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5228
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: D:\Devolopemnt\Dotnet\bookapi-minimal

This means the application is running and listening on http://localhost:5228. As I mentioned above, since we are using the dotnet CLI and Visual Studio Code, the application will not automatically open the browser for us. We need to do this manually.

Open your browser and navigate to http://localhost:5228/swagger/index.html to see the default response from the API.

You should see something like this:

Now the next thing for us to do is find a way to structure our project and create the necessary files and folders to get us started.

Minimal API Project Files

To organize our project, we will create a structured folder hierarchy. This will help keep our code clean and maintainable. Here is the folder structure we will use:

• AppContext: Contains the database context and related configurations.

• Configurations: Holds Entity Framework Core configurations and seed data for the database.

• Contracts: Contains Data Transfer Objects (DTOs) used in our application.

• Endpoints: Where we define and configure our minimal API endpoints.

• Exceptions: Contains custom exception classes used in the project.

• Extensions: Holds extension methods that we will use throughout the project.

• Models: Contains business logic models.

• Services: Contains service classes that implement business logic.

• Interfaces: Holds interface definitions used to map our services.

In Visual Studio Code, you can create this folder structure as follows:

- AppContext
- Configurations
- Contracts
- Endpoints
- Exceptions
- Extensions
- Models
- Services
- Interfaces

After setting up, your project folder structure should look like this:

Now that our project Structure is set up we can go ahead and start writing our code. Let's start by creating our models.

How to Create the Models

In this section, we will create models for our application. Models are the building blocks of our application, representing the data that our application will work with. For our example, we will create a model for a book.

To get started, create a folder named Models in your project directory. Inside this folder, create a file named BookModel.cs and add the following code:

// Models/BookModel.cs


namespace bookapi_minimal.Models
{
    public class BookModel
    {
        public Guid Id { get; set; }
        public string Title { get; set; }
        public string Author { get; set; }
        public string Description { get; set; }
        public string Category { get; set; }
        public string Language { get; set; }
        public int TotalPages { get; set; }
    }
}

This BookModel class defines the properties that represent the details of a book, such as its title, author, description, category, language, and total pages. Each property is designed to hold specific information about the book, making it easy to manage and manipulate book data within our application.

Now that we have created our model, let's create our database context.

How to Create the Database Context

The database context is a class that represents a session with the database. It’s responsible for interacting with the database and executing database operations. In our application, we will use Entity Framework Core to interact with our database.

Install the Required Packages

Before creating our database context, we need to install the following packages:

• Microsoft.EntityFrameworkCore.Design

• Microsoft.EntityFrameworkCore

• Microsoft.EntityFrameworkCore.SqlServer

• Microsoft.EntityFrameworkCore.Tools

• FluentValidation.DependencyInjectionExtensions

You can install these packages using the following commands:

dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package FluentValidation.DependencyInjectionExtensions

Verify Package Installation

To verify that the packages are installed, open the bookapi-minimal.csproj file in your project's root directory. You should see the installed packages listed as follows:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <RootNamespace>bookapi_minimal</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
   <PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.9.2" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.6" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

This confirms that the packages have been successfully installed.

Now let's create our database context.

In the AppContext folder, create a new file named ApplicationContext.cs and add the following code:

// AppContext/ApplicationContext.cs

using bookapi_minimal.Models;
using Microsoft.EntityFrameworkCore;

namespace bookapi_minimal.AppContext
{

    public class ApplicationContext(DbContextOptions<ApplicationContext> options) : DbContext(options)
    {

        // Default schema for the database context
        private const string DefaultSchema = "bookapi";


       // DbSet to represent the collection of books in our database
        public DbSet<BookModel> Books { get; set; }

        // Constructor to configure the database context

        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            base.OnModelCreating(modelBuilder);
            modelBuilder.HasDefaultSchema(DefaultSchema);

            modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationContext).Assembly);

            modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationContext).Assembly);

        }

    }
}

Let's break down the code above:

• We define a class named ApplicationContext that inherits from DbContext. The DbContext class is part of Entity Framework Core and represents a session with the database.

• The constructor accepts an instance of DbContextOptions<ApplicationContext>. This constructor is used to configure the database context options.

• We define a property named Books type DbSet<BookModel>. This property represents the collection of books in our database.

• We override the OnModelCreating method to configure the database schema and apply any configurations defined in our application.

Now that we have created our database context, let's create our extension method and register our database context in the dependency injection container.

Create an Extension Method

Before we create the extension method, let's understand what an extension method is in the context of ASP.NET Core.

An extension method is a static method that adds new functionality to an existing type without modifying the original type. In ASP.NET Core, extension methods are commonly used to extend the functionality of the IServiceCollection interface, which is used to register services in the dependency injection container.

Services are components that provide functionality to an application, such as database access, logging, and configuration. By creating an extension method for the IServiceCollection interface, you can simplify the process of registering your services in the dependency injection container.

Instead of putting everything in the Program.cs file, we will create an extension method to register our services in the dependency injection container. This will help us keep our code clean and organized.

In the Extensions folder, create a new file named ServiceExtensions.cs and add the following code:

using System.Reflection;
using bookapi_minimal.AppContext;
using FluentValidation;
using Microsoft.EntityFrameworkCore;

namespace bookapi_minimal.Extensions
{
    public static class ServiceExtensions
    {
        public static void AddApplicationServices(this IHostApplicationBuilder builder)
        {
            if (builder == null) throw new ArgumentNullException(nameof(builder));
            if (builder.Configuration == null) throw new ArgumentNullException(nameof(builder.Configuration));

            // Adding the database context
            builder.Services.AddDbContext<ApplicationContext>(configure =>
            {
                configure.UseSqlServer(builder.Configuration.GetConnectionString("sqlConnection"));
            });

            // Adding validators from the current assembly
            builder.Services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());
        }
    }
}

Let's break down the code above:

• We define a static class named ServiceExtensions that contains an extension method named AddApplicationServices. This method extends the IHostApplicationBuilder interface, which is used to configure the application's request processing pipeline.

• The AddApplicationServices method accepts an instance of IHostApplicationBuilder as a parameter. This parameter is used to access the application's configuration and services.

• We add the ApplicationContext to the dependency injection container and configure it to use SQL Server as the database provider. We retrieve the connection string from the appsettings.json file using the GetConnectionString method.

• We add validators from the current assembly using the AddValidatorsFromAssembly method. This method scans the current assembly for classes that implement the IValidator interface and registers them in the dependency injection container.

Next, we need to add the connection string to the appsettings.json file. Add the following code to your appsettings.json file:

{ 
     "ConnectionStrings": {
    "sqlConnection": "Server=localhost\\SQLEXPRESS02;Database=BookAPIMinimalAPI;Integrated Security=true;TrustServerCertificate=true;"
  }
  }

Make sure to replace your_password it with your actual SQL Server password.

Your appsettings.json file should look like this:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "sqlConnection": "Server=localhost\\SQLEXPRESS02;Database=BookAPIMinimalAPI;Integrated Security=true;TrustServerCertificate=true;"
  },
  "AllowedHosts": "*"
}

Congratulations! You have successfully created the database context, extension method, and connection string for your application. In the next section, we will create a Contract.

How to Create a Contract

Contracts are Data Transfer Objects (DTOs) that define the structure of the data exchanged between the client and the server. In our application, we will create contracts to represent the data sent and received by our API endpoints.

Here are the contracts we are going to create:

• CreateBookRequest: This represents the data sent when creating a new book.

• UpdateBookRequest: tHI Represents the data sent when updating an existing book.

• BookResponse: Represents the data returned when retrieving a book.

• ErrorResponse: Represents the error response returned when an exception occurs.

• ApiResponse: Represents the response returned by the API.

In the Contracts folder, create a new file named CreateBookRequest and add the following code:

// Contracts/CreateBookRequest.cs

namespace bookapi_minimal.Contracts
{

    public record CreateBookRequest
    { 

        public string Title { get; init; }
        public string Author { get; init; }
        public string Description { get; init; }
        public string Category { get; init; }
        public string Language { get; init; }
        public int TotalPages { get; init; }
    }
}

In the Contracts folder, create a new file named UpdateBookRequest and add the following code:

// Contracts/UpdateBookRequest.cs

namespace bookapi_minimal.Contracts
{

    public record UpdateBookRequest
    {
       public string Title { get; set; }
        public string Author { get; set; }
        public string Description { get; set; }
        public string Category { get; set; }
        public string Language { get; set; }
        public int TotalPages { get; set; }

    }
}

In the Contracts folder, create a new file named BookResponse and add the following code:

// Contracts/BookResponse.cs
namespace bookapi_minimal.Contracts
{

    public record BookResponse
    {
        public Guid Id { get; set; }
        public string Title { get; set; }
        public string Author { get; set; }
        public string Description { get; set; }
        public string Category { get; set; }
        public string Language { get; set; }
        public int TotalPages { get; set; }
    }
}

In the Contracts folder, create a new file named ErrorResponse and add the following code:

// Contracts/ErrorResponse.cs
namespace bookapi_minimal.Contracts
{

        public record ErrorResponse
    {
        public string Title { get; set; }
        public int StatusCode { get; set; }
        public string Message { get; set; }

    }

}

In the Contracts folder, create a new file named ApiResponse and add the following code:

// Contracts/ApiResponse.cs
namespace bookapi_minimal.Contracts
{

    public class ApiResponse<T>
    {
        public T Data { get; set; }
        public string Message { get; set; }

        public ApiResponse(T data, string message)
        {
            Data = data;
            Message = message;
        }
    }
}

These contracts help us define the structure of the data exchanged between the client and the server, making it easier to work with the data in our application.

In the next section, we will create services to implement the business logic of our application.

How to Add Services

Services are components that provide functionality to an application. In our application, we will create services to implement the business logic of our application. We will create services to handle CRUD operations for books, validate book data, and handle exceptions.

In ASP.NET Core, services are registered in the dependency injection container and can be injected into other components, such as controllers and endpoints, But this is a minimal API so we will inject the services directly into the endpoints.

Let's create an interface for our services. In the Interfaces folder, create a new file named IBookService.cs and add the following code:

 // Interfaces/IBookService.cs



using bookapi_minimal.Contracts;

namespace bookapi_minimal.Interfaces
{
      public interface IBookService
    {
        Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest);
        Task<BookResponse> GetBookByIdAsync(Guid id);
        Task<IEnumerable<BookResponse>> GetBooksAsync();
        Task<BookResponse> UpdateBookAsync(Guid id,  UpdateBookRequest  updateBookRequest);
        Task<bool> DeleteBookAsync(Guid id);
    }
}

Let's break down the code above: We have defined an interface named IBookService that contains methods to handle CRUD operations for books. The interface defines the following methods:

• AddBookAsync: Adds a new book to the database.

• GetBookByIdAsync: Retrieves a book by its ID.

• GetBooksAsync: Retrieves all books from the database.

• UpdateBookAsync: Updates an existing book.

We are using the Contract we created earlier in the Contracts folder. The IBookService interface defines the structure of the methods that will be implemented by the service classes. This helps us separate the interface from the implementation, making it easier to maintain and test our code.

Now that we have created the interface, let's create the service class that implements the interface.

How to Implement the Book Service

This service will implement the IBookService interface and provide the business logic for our application. In the Services folder, create a new file named BookService.cs . Your initial file should look like this:

// Services/BookService.cs

namespace bookapi_minimal.Services
{
    public class BookService
    {

    }
}

The first thing we need to do is add the interface to the BookService class. Update the BookService class to implement the IBookService interface as follows:

// Services/BookService.cs



using bookapi_minimal.Interfaces;

namespace bookapi_minimal.Services
{
    public class BookService:IBookService
    {

    }
}

When you do this, your VS Code might show an error because we have not implemented the methods in the interface. Let's go ahead and implement the methods in the BookService class.

In VS Code you can use the Ctrl + . shortcut to implement the methods in the interface. Then you will see the following code generated for you:

using bookapi_minimal.Contracts;
using bookapi_minimal.Interfaces;

namespace bookapi_minimal.Services
{
     // Service class for managing books
   public class BookService : IBookService
   {
       // Method to add a new book to the database
       public Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest)
       {
           throw new NotImplementedException();
       }

      // Method to Delete a book from the database
       public Task<bool> DeleteBookAsync(Guid id)
       {
           throw new NotImplementedException();
       }

       // Method to Get a book from the database by its ID

       public Task<BookResponse> GetBookByIdAsync(Guid id)
       {
           throw new NotImplementedException();
       }

      // Method to Get all books from the database
       public Task<IEnumerable<BookResponse>> GetBooksAsync()
       {
           throw new NotImplementedException();
       }

       // Method to Update a book in the database
       public Task<BookResponse> UpdateBookAsync(Guid id, UpdateBookRequest updateBookRequest)
       {
           throw new NotImplementedException();
       }
   }
}

Now you can see that the methods in the interface have been implemented in the BookService class. We will implement the business logic for each method in the next section.

Before we do that, let's add the necessary dependencies to the BookService class. We need to inject the ApplicationContext and ILogger dependencies into the BookService class. ApplicationContext is used to interact with the database, while ILogger is used for logging.

To inject the dependencies, update the BookService class as follows:

// Services/BookService.cs

// ...
 private readonly ApplicationContext _context; // Database context
  private readonly ILogger<BookService> _logger; // Logger for logging information and errors

//..

Since we have added the dependencies, we need to update the BookService constructor to accept the dependencies. Update the BookService constructor as follows:

// Services/BookService.cs

// ...

  // Constructor to initialize the database context and logger
 public BookService(ApplicationContext context, ILogger<BookService> logger)
 {
            _context = context;
            _logger = logger;
}

// ...

Now that we have added the dependencies and updated the constructor, we can implement the business logic for each method in the BookService class.

Let's create logic for the CREATE, READ, UPDATE, and DELETE operations in the BookService class.

How to Implement the AddBookAsync Method

As I mentioned earlier, we’ll use the AddBookAsync method to add a new book to the database. In this method, we will create a new book entity, map the data from the CreateBookRequest object to the book entity, and save the book entity to the database. We will also return the book entity as an BookResponse object.

Update the AddBookAsync method in the BookService class as follows:

// Services/BookService.cs

// ...
 /// <summary>
        /// Add a new book
        /// </summary>
        /// <param name="createBookRequest">Book request to be added</param>
        /// <returns>Details of the created book</returns>
        public async Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest)
        {
            try
            {
                var book = new BookModel
                {
                    Title = createBookRequest.Title,
                    Author = createBookRequest.Author,
                    Description = createBookRequest.Description,
                    Category = createBookRequest.Category,
                    Language = createBookRequest.Language,
                    TotalPages = createBookRequest.TotalPages
                };

                // Add the book to the database
                _context.Books.Add(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book added successfully.");

                // Return the details of the created book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error adding book: {ex.Message}");
                throw;
            }
        }
// ...

In this code, we are creating a new book entity from the CreateBookRequest object, mapping the data from the CreateBookRequest object to the book entity, saving the book entity to the database, and returning the book entity as a BookResponse object.

We are also logging information and errors using the ILogger dependency. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the AddBookAsync method, let's implement the GetBookByIdAsync method.

How to Implement the GetBookByIdAsync Method

The GetBookByIdAsync method is used to retrieve a book by its ID from the database. In this method, we will query the database for the book with the specified ID, map the book entity to a BookResponse object, and return the BookResponse object.

Update the GetBookByIdAsync method in the BookService class as follows:

// Services/BookService.cs

//... 

    /// <summary>
        /// Get a book by its ID
        /// </summary>
        /// <param name="id">ID of the book</param>
        /// <returns>Details of the book</returns>
        public async Task<BookResponse>  GetBookByIdAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Return the details of the book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving book: {ex.Message}");
                throw;
            }
        }

//...

In this code, we are querying the database for the book with the specified ID, mapping the book entity to a BookResponse object, and returning the BookResponse object. We are also logging information and errors using the ILogger dependency.

If the book with the specified ID is not found, we log a warning message and return null. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the GetBookByIdAsync method, let's implement the GetBooksAsync method.

How to Implement the GetBooksAsync Method

The GetBooksAsync method is used to retrieve all books from the database. In this method, we will query the database for all books, map each book entity to a BookResponse object, and return a list of BookResponse objects.

Update the GetBooksAsync method in the BookService class as follows:

// Services/BookService.cs

//... 


  /// <summary>
        /// Get all books
        /// </summary>
        /// <returns>List of all books</returns>
        public async Task<IEnumerable<BookResponse>> GetBooksAsync()
        {
            try
            {
                // Get all books from the database
                var books = await _context.Books.ToListAsync();

                // Return the details of all books
                return books.Select(book => new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                });
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving books: {ex.Message}");
                throw;
            }
        }
//...

Here, we are querying the database for all books, mapping each book entity to an BookResponse object, and returning a list of BookResponse objects. We are also logging information and errors using the ILogger dependency. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the GetBooksAsync method, let's implement the UpdateBookAsync method.

How to Implement the UpdateBookAsync Method

The UpdateBookAsync method is used to update an existing book in the database. In this method, we will query the database for the book with the specified ID, update the book entity with the data from the UpdateBookRequest object, save the updated book entity to the database, and return the updated book entity as a BookResponse object.

Update the UpdateBookAsync method in the BookService class as follows:

// Services/BookService.cs
 //...
 /// <summary>
        /// Update an existing book
        /// </summary>
        /// <param name="id">ID of the book to be updated</param>
        /// <param name="book">Updated book model</param>
        /// <returns>Details of the updated book</returns>
        public async Task<BookResponse> UpdateBookAsync(Guid id, UpdateBookRequest book)
        {
            try
            {
                // Find the existing book by its ID
                var existingBook = await _context.Books.FindAsync(id);
                if (existingBook == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Update the book details
                existingBook.Title = book.Title;
                existingBook.Author = book.Author;
                existingBook.Description = book.Description;
                existingBook.Category = book.Category;
                existingBook.Language = book.Language;
                existingBook.TotalPages = book.TotalPages;

                // Save the changes to the database
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book updated successfully.");

                // Return the details of the updated book
                return new BookResponse
                {
                    Id = existingBook.Id,
                    Title = existingBook.Title,
                    Author = existingBook.Author,
                    Description = existingBook.Description,
                    Category = existingBook.Category,
                    Language = existingBook.Language,
                    TotalPages = existingBook.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error updating book: {ex.Message}");
                throw;
            }
        }
//...

Here, we are querying the database for the book with the specified ID, updating the book entity with the data from the UpdateBookRequest object, saving the updated book entity to the database, and returning the updated book entity as a BookResponse object. We are also logging information and errors using the ILogger dependency.

If the book with the specified ID is not found, we log a warning message and return null. If an exception occurs during the process, we log the error message and rethrow the exception.

Now that we have implemented the UpdateBookAsync method, let's implement the DeleteBookAsync method.

How to Implement the DeleteBookAsync Method

The DeleteBookAsync method is used to delete an existing book from the database. In this method, we will query the database for the book with the specified ID, remove the book entity from the database, and return a boolean value indicating whether the book was successfully deleted.

Update the DeleteBookAsync method in the BookService class as follows:

// Services/BookService.cs

 //...


/// <summary>
        /// Delete a book by its ID
        /// </summary>
        /// <param name="id">ID of the book to be deleted</param>
        /// <returns>True if the book was deleted, false otherwise</returns>
        public async Task<bool> DeleteBookAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return false;
                }

                // Remove the book from the database
                _context.Books.Remove(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation($"Book with ID {id} deleted successfully.");
                return true;
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error deleting book: {ex.Message}");
                throw;
            }
        }
//...

In this code, we are querying the database for the book with the specified ID, removing the book entity from the database, and returning a boolean value indicating whether the book was successfully deleted. We are also logging information and errors using the ILogger dependency.

If the book with the specified ID is not found, we log a warning message and return false. If an exception occurs during the process, we log the error message and rethrow the exception.

Now you have successfully implemented the business logic for the AddBookAsync, GetBookByIdAsync, GetBooksAsync, UpdateBookAsync, and DeleteBookAsync methods in the BookService class. These methods handle the CRUD operations for books, validate book data, and handle exceptions. By now, your BookService class should look like this:

using bookapi_minimal.AppContext;
using bookapi_minimal.Contracts;
using bookapi_minimal.Interfaces;
using bookapi_minimal.Models;
using Microsoft.EntityFrameworkCore;

namespace bookapi_minimal.Services
{
    public class BookService : IBookService
    {
          private readonly ApplicationContext _context; // Database context
        private readonly ILogger<BookService> _logger; // Logger for logging information and error
          // Constructor to initialize the database context and logger
        public BookService(ApplicationContext context, ILogger<BookService> logger)
        {
            _context = context;
            _logger = logger;
        }

           /// Add a new book
        /// </summary>
        /// <param name="createBookRequest">Book request to be added</param>
        /// <returns>Details of the created book</returns>
        public async Task<BookResponse> AddBookAsync(CreateBookRequest createBookRequest)
        {
            try
            {
                var book = new BookModel
                {
                    Title = createBookRequest.Title,
                    Author = createBookRequest.Author,
                    Description = createBookRequest.Description,
                    Category = createBookRequest.Category,
                    Language = createBookRequest.Language,
                    TotalPages = createBookRequest.TotalPages
                };

                // Add the book to the database
                _context.Books.Add(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book added successfully.");

                // Return the details of the created book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error adding book: {ex.Message}");
                throw;
            }
        }

          /// <summary>
        /// Get a book by its ID
        /// </summary>
        /// <param name="id">ID of the book</param>
        /// <returns>Details of the book</returns>
        public async Task<BookResponse>  GetBookByIdAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Return the details of the book
                return new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving book: {ex.Message}");
                throw;
            }
        }



  /// <summary>
        /// Get all books
        /// </summary>
        /// <returns>List of all books</returns>
        public async Task<IEnumerable<BookResponse>> GetBooksAsync()
        {
            try
            {
                // Get all books from the database
                var books = await _context.Books.ToListAsync();

                // Return the details of all books
                return books.Select(book => new BookResponse
                {
                    Id = book.Id,
                    Title = book.Title,
                    Author = book.Author,
                    Description = book.Description,
                    Category = book.Category,
                    Language = book.Language,
                    TotalPages = book.TotalPages
                });
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error retrieving books: {ex.Message}");
                throw;
            }
        }


         /// <summary>
        /// Update an existing book
        /// </summary>
        /// <param name="id">ID of the book to be updated</param>
        /// <param name="book">Updated book model</param>
        /// <returns>Details of the updated book</returns>
        public async Task<BookResponse> UpdateBookAsync(Guid id, UpdateBookRequest book)
        {
            try
            {
                // Find the existing book by its ID
                var existingBook = await _context.Books.FindAsync(id);
                if (existingBook == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return null;
                }

                // Update the book details
                existingBook.Title = book.Title;
                existingBook.Author = book.Author;
                existingBook.Description = book.Description;
                existingBook.Category = book.Category;
                existingBook.Language = book.Language;
                existingBook.TotalPages = book.TotalPages;

                // Save the changes to the database
                await _context.SaveChangesAsync();
                _logger.LogInformation("Book updated successfully.");

                // Return the details of the updated book
                return new BookResponse
                {
                    Id = existingBook.Id,
                    Title = existingBook.Title,
                    Author = existingBook.Author,
                    Description = existingBook.Description,
                    Category = existingBook.Category,
                    Language = existingBook.Language,
                    TotalPages = existingBook.TotalPages
                };
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error updating book: {ex.Message}");
                throw;
            }
        }



        /// <summary>
        /// Delete a book by its ID
        /// </summary>
        /// <param name="id">ID of the book to be deleted</param>
        /// <returns>True if the book was deleted, false otherwise</returns>
        public async Task<bool> DeleteBookAsync(Guid id)
        {
            try
            {
                // Find the book by its ID
                var book = await _context.Books.FindAsync(id);
                if (book == null)
                {
                    _logger.LogWarning($"Book with ID {id} not found.");
                    return false;
                }

                // Remove the book from the database
                _context.Books.Remove(book);
                await _context.SaveChangesAsync();
                _logger.LogInformation($"Book with ID {id} deleted successfully.");
                return true;
            }
            catch (Exception ex)
            {
                _logger.LogError($"Error deleting book: {ex.Message}");
                throw;
            }
        }

    }
}

Congratulations! You have successfully implemented the business logic for the AddBookAsync, GetBookByIdAsync, GetBooksAsync, UpdateBookAsync, and DeleteBookAsync methods in the BookService class.

There's one thing we need to do: we need to register the service in our extension method. Let's go ahead and do that.

In your ServiceExtensions.cs file, add the following code:

// Extensions/ServiceExtensions.cs

//..

 builder.Services.AddScoped<IBookService, BookService>();
//...

This will register the BookService class as a scoped service. This means that the service will be created once per request and disposed of after the request is complete.

Now that we have the service working, let's go ahead and create the exception classes.

How to Create Exceptions

Properly handling exceptions is crucial for ensuring the stability and reliability of an application. In the context of ASP.NET Core, there are two main types of exceptions:

• System Exceptions: These are exceptions thrown by the .NET runtime or the underlying system.

• Application Exceptions: These are exceptions thrown by the application code to handle specific errors or conditions.

In ASP.NET Core with .NET 8, a new feature called global exception handling was introduced. This feature allows you to handle exceptions globally in your application, making it easier to manage errors and provide a consistent user experience.

In our application, we will create custom exception classes to handle specific errors and conditions. We’ll also leverage the global exception handling feature to manage exceptions globally, ensuring a uniform approach to error handling across the entire application.

We are going to create the following exception classes:

• NoBookFoundException: Thrown when a book with the specified ID is not found.

• BookDoesNotExistException: Thrown when a book with the specified ID does not exist.

• GlobalExceptionHandler: Handles exceptions globally in the application.

In the Exceptions folder, create a new file named NoBookFoundException.cs and add the following code:

// Exceptions/NoBookFoundException.cs

namespace bookapi_minimal.Exceptions
{

    public class NoBookFoundException : Exception
    {

        public NoBookFoundException() : base("No books found")
        {}
    }
}

In this code, we are creating a custom exception class named NoBookFoundException that inherits from the Exception class. The NoBookFoundException class is used to handle the scenario where no books are found in the database. We are also providing a custom error message for the exception.

In the Exceptions folder, create a new file named BookDoesNotExistException.cs and add the following code:

namespace bookapi_minimal.Exceptions
{
     public class BookDoesNotExistException : Exception
    {
        private int id { get; set; }

        public BookDoesNotExistException(int id) : base($"Book with id {id} does not exist")
        {
            this.id = id;
        } 

    }
}

In this code, we are creating a custom exception class named BookDoesNotExistException that inherits from the Exception class. The BookDoesNotExistException class is used to handle the scenario where a book with the specified ID does not exist in the database. We are also providing a custom error message for the exception.

In the Exceptions folder, create a new file named GlobalExceptionHandler.cs and add the following code:

// Exceptions/GlobalExceptionHandler.cs

using System.Net;
using bookapi_minimal.Contracts;
using Microsoft.AspNetCore.Diagnostics;

namespace bookapi_minimal.Exceptions
{

   // Global exception handler class implementing IExceptionHandler
    public class GlobalExceptionHandler : IExceptionHandler
    {
        private readonly ILogger<GlobalExceptionHandler> _logger;

        // Constructor to initialize the logger
        public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
        {
            _logger = logger;
        }

        // Method to handle exceptions asynchronously
        public async ValueTask<bool> TryHandleAsync(
            HttpContext httpContext,
            Exception exception,
            CancellationToken cancellationToken)
        {
            // Log the exception details
            _logger.LogError(exception, "An error occurred while processing your request");

            var errorResponse = new ErrorResponse
            {
                Message = exception.Message,
                Title = exception.GetType().Name
            };

            // Determine the status code based on the type of exception
            switch (exception)
            {
                case BadHttpRequestException:
                    errorResponse.StatusCode = (int)HttpStatusCode.BadRequest;
                    break;

                case NoBookFoundException:
                case BookDoesNotExistException:
                    errorResponse.StatusCode = (int)HttpStatusCode.NotFound;
                    break;

                default:
                    errorResponse.StatusCode = (int)HttpStatusCode.InternalServerError;
                    break;
            }

            // Set the response status code
            httpContext.Response.StatusCode = errorResponse.StatusCode;

            // Write the error response as JSON
            await httpContext.Response.WriteAsJsonAsync(errorResponse, cancellationToken);

            // Return true to indicate that the exception was handled
            return true;
        }
    }
}

Let's break down the code above:

• We define a class named GlobalExceptionHandler that implements the IExceptionHandler interface. The IExceptionHandler interface is used to handle exceptions globally in the application.

• The GlobalExceptionHandler class contains a constructor that initializes the ILogger<GlobalExceptionHandler> dependency. The ILogger is used for logging information and errors.

• The TryHandleAsync method is used to handle exceptions asynchronously. This method accepts the HttpContext, Exception, and CancellationToken as parameters.

• We log the exception details using the ILogger dependency.

• We create an ErrorResponse object to represent the error response returned by the API. The ErrorResponse object contains the error message, title, and status code.

• We determine the status code based on the type of exception. If the exception is a BadHttpRequestException, we set the status code to BadRequest. If the exception is a NoBookFoundException or BookDoesNotExistException, we set the status code to NotFound. Otherwise, we set the status code to InternalServerError.

• We set the response status code using the httpContext.Response.StatusCode property.

• We write the error response as JSON using the httpContext.Response.WriteAsJsonAsync method.

• We return true to indicate that the exception was handled successfully.

Now that we have created the exception classes, let's register the GlobalExceptionHandler in the dependency injection container. Since we created an Extension method for registering services in the dependency injection container, we will add the GlobalExceptionHandler to the ServiceExtensions class.

Update the ServiceExtensions class in the Extensions folder as follows:

// Extensions/ServiceExtensions.cs
//...
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

builder.Services.AddProblemDetails();

//...

The AddExceptionHandler method registers the GlobalExceptionHandler in the dependency injection container. The AddProblemDetails method registers the ProblemDetails class in the dependency injection container.

Now that we have registered the GlobalExceptionHandler in the dependency injection container, we can use it to handle exceptions globally in our application. In the next section, we will create the API endpoints to interact with the book data.

How to Create the API Endpoints

In the context of minimal APIs in ASP.NET Core, there are many ways to set up your endpoints.

You can define them directly in your Program.cs file. But as your project grows and you need to add more endpoints or functionality, it’s helpful to organize your code better. One way to achieve this is by creating a separate class to handle all the endpoints.

As we’ve discussed above, minimal APIs don’t use controllers or views like traditional ASP.NET Core applications. Instead, they use methods such as MapGet, MapPost, MapPut, and MapDelete to define HTTP methods and routes for API endpoints.

To get started, navigate to the Endpoints folder and create a new file named BookEndpoints.cs. Add the following code to the file:

// Endpoints/BookEndpoints.cs



namespace bookapi_minimal.Endpoints
{
     public static class BookEndPoint
    {
        public static IEndpointRouteBuilder MapBookEndPoint(this IEndpointRouteBuilder app)
        {


            return app;
        }
    }
}

The BookEndpoints class contains a MapBookEndPoint method that returns an IEndpointRouteBuilder object. The IEndpointRouteBuilder object is used to define the HTTP methods and routes for the API endpoints. In the next sections, we will define the API endpoints for creating, reading, updating, and deleting books.

How to Create the AddBookAsync Books Endpoint

In this section, we will create the AddBookAsync endpoint. This endpoint will accept a Book object as a JSON payload and add it to the database. We will use the MapPost method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs


//...
   // Endpoint to add a new book
      app.MapPost("/books", async (CreateBookRequest createBookRequest, IBookService bookService) =>
        {
        var result = await bookService.AddBookAsync(createBookRequest);
        return Results.Created($"/books/{result.Id}", result); 
        });


//...

• Route Definition: The MapPost method defines the route for the endpoint as /books.

• Request Model: The endpoint accepts an CreateBookRequest object as a JSON payload. The CreateBookRequest object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns a Created result. The Created result contains the location of the newly created book and the Book object.

How to Create the GetBookAsync Book Endpoint

In this section, we will create the GetBookAsync endpoint. This endpoint will accept a book ID as a query parameter and return the book with the specified ID. We will use the MapGet method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs

// ...
    // Endpoint to get all books
    app.MapGet("/books", async (IBookService bookService) =>
     {
    var result = await bookService.GetBooksAsync();
    return Results.Ok(result);
});


//...

• Route Definition: The MapGet method defines the route for the endpoint as /books.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns an Ok result. The Ok result contains the Book object.

How to Create the GetBookByIdAsync Book Endpoint

In this section, we will create the GetBookByIdAsync endpoint. This endpoint will accept a book ID as a route parameter and return the book with the specified ID. We will use the MapGet method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs
//...
// Endpoint to get a book by ID

  app.MapGet("/books/{id:guid}", async (Guid id, IBookService bookService) =>
  {
    var result = await bookService.GetBookByIdAsync(id);
    return result != null ? Results.Ok(result) : Results.NotFound();
});

//...

• Route Definition: The MapGet method defines the route for the endpoint as /books/{id:guid}. The {id:guid} parameter specifies that the id parameter should be a GUID.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns an Ok result if the book is found. The NotFound result is returned if the book is not found.

How to Create the UpdateBookAsync Book Endpoint

In this section, we will create the UpdateBookAsync endpoint. This endpoint will accept a book ID as a route parameter and an Book object as a JSON payload and update the book with the specified ID. We will use the MapPut method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs

//...
   // Endpoint to update a book by ID
    app.MapPut("/books/{id:guid}", async (Guid id, UpdateBookRequest updateBookRequest, IBookService bookService) =>
 {
var result = await bookService.UpdateBookAsync(id, updateBookRequest);
return result != null ? Results.Ok(result) : Results.NotFound();
});

//...

• Route Definition: The MapPut method defines the route for the endpoint as /books/{id:guid}. The {id:guid} parameter specifies that the id parameter should be a GUID.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns an Ok result if the book is found. The NotFound result is returned if the book is not found.

How to Create the DeleteBookAsync Book Endpoint

In this section, we will create the DeleteBookAsync endpoint. This endpoint will accept a book ID as a route parameter and delete the book with the specified ID. We will use the MapDelete method to define the HTTP method and route for this endpoint.

Add the following code to the BookEndpoints class:

// Endpoints/BookEndpoints.cs

//...
   // Endpoint to delete a book by ID
 app.MapDelete("/books/{id:guid}", async (Guid id, IBookService bookService) =>
{
var result = await bookService.DeleteBookAsync(id);
   return result ? Results.NoContent() : Results.NotFound();
});


//...

• Route Definition: The MapDelete method defines the route for the endpoint as /books/{id:guid}. The {id:guid} parameter specifies that the id parameter should be a GUID.

• Request Model: The endpoint accepts a Book object as a JSON payload. The Book object contains the data required to create a new book.

• Response Model: The endpoint returns a Book object as a JSON payload. The Book object contains the data for the newly created book.

• Return Value: The endpoint returns a NoContent result if the book is deleted successfully. The NotFound result is returned if the book is not found.

Now we have defined all the methods for the book endpoints. So your endpoint class should look like this:

// Endpoints/BookEndpoints.cs
using bookapi_minimal.Contracts;
using bookapi_minimal.Interfaces;

namespace bookapi_minimal.Endpoints
{
     public static class BookEndPoint
    {
        public static IEndpointRouteBuilder MapBookEndPoint(this IEndpointRouteBuilder app)
        {
            // Define the endpoints

            // Endpoint to add a new book
            app.MapPost("/books", async (CreateBookRequest createBookRequest, IBookService bookService) =>
            {
                var result = await bookService.AddBookAsync(createBookRequest);
                return Results.Created($"/books/{result.Id}", result); 
            });


               // Endpoint to get all books
            app.MapGet("/books", async (IBookService bookService) =>
            {
                var result = await bookService.GetBooksAsync();
                return Results.Ok(result);
            });

            // Endpoint to get a book by ID
            app.MapGet("/books/{id:guid}", async (Guid id, IBookService bookService) =>
            {
                var result = await bookService.GetBookByIdAsync(id);
                return result != null ? Results.Ok(result) : Results.NotFound();
            });


            // Endpoint to update a book by ID
            app.MapPut("/books/{id:guid}", async (Guid id, UpdateBookRequest updateBookRequest, IBookService bookService) =>
            {
                var result = await bookService.UpdateBookAsync(id, updateBookRequest);
                return result != null ? Results.Ok(result) : Results.NotFound();
            });

            // Endpoint to delete a book by ID
            app.MapDelete("/books/{id:guid}", async (Guid id, IBookService bookService) =>
            {
                var result = await bookService.DeleteBookAsync(id);
                return result ? Results.NoContent() : Results.NotFound();
            });

            return app;
        }
    }
}

Congratulations! You have created all the endpoints for the book API. The endpoints handle the CRUD operations for books and return the appropriate responses based on the request and data.

How to Register the Endpoints

After defining the API endpoints for the book API, the next step is to register these endpoints in the Program.cs file. We will use the MapBookEndpoints method to register the book endpoints.

We should also clean up our Program.cs class to ensure it remains organized and maintainable.

// Program.cs

using System.Reflection;
using bookapi_minimal.Endpoints;
using bookapi_minimal.Services;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);


builder.AddApplicationServices();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c=>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Mimal API", Version = "v1", Description = "Showing how you can build minimal " +
        "api with .net" });


    // Set the comments path for the Swagger JSON and UI.
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);

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

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

app.UseHttpsRedirection();
app.UseExceptionHandler();


app.MapGroup("/api/v1/")
   .WithTags(" Book endpoints")
   .MapBookEndPoint();

app.Run();

Let's break down the key components of the Program.cs file:

• AddApplicationServices: This method registers the necessary services for the API. It is an extension method we created earlier to add services to the dependency injection container.

• AddSwaggerGen: This method registers the Swagger generator, which is used to create the Swagger documentation for the API. We specify the title, version, and description of the API in the Swagger document.

• MapGroup: This method groups the endpoints. It takes a path as a parameter and returns an IEndpointRouteBuilder object. We use the WithTags method to add tags to the endpoints and the MapBookEndpoints method to register the book endpoints.

• Run: This method starts the application.

To enable Swagger documentation, you need to add the GenerateDocumentationFile property to your .csproj file. In this example, the file is named bookapi-minimal.csproj, but the name may vary based on your project.

Add the following line to your .csproj file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

By the end, bookapi-minimal.csproj should look like this:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <RootNamespace>bookapi_minimal</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
   <PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.9.2" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.6" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.8">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

Now that we have registered the book endpoints in the Program.cs file, we can run the application and test the API endpoints using Swagger.

When you run the application, you should see the Swagger documentation at the following URL: https://localhost:5001/swagger/index.html. The Swagger documentation provides information about the API endpoints, request and response models, and allows you to test the endpoints directly from the browser. You should see something like this:

Congratulations! You have implemented the business logic for the book service, created custom exceptions, defined API endpoints, and registered the endpoints in the Program.cs file. You have also enabled Swagger documentation to test the API endpoints.

How to Add Seed Data to the Database

One more important step is to seed the database with initial data when the application starts. This seed data will populate the database, allowing you to test your API endpoints without manually adding data.

Let's add some seed data before performing migrations and testing our API endpoints.

To achieve this, we will create a new class in our Configuration folder called BookTypeConfigurations and add the following code:

using bookapi_minimal.Models;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

namespace bookapi_minimal.Configurations
{
    public class BookTypeConfigurations : IEntityTypeConfiguration<BookModel>
    {
        public void Configure(EntityTypeBuilder<BookModel> builder)
        {
            // Configure the table name
            builder.ToTable("Books");

            // Configure the primary key
            builder.HasKey(x => x.Id);

            // Configure properties
            builder.Property(x => x.Id).ValueGeneratedOnAdd();
            builder.Property(x => x.Title).IsRequired().HasMaxLength(100);
            builder.Property(x => x.Author).IsRequired().HasMaxLength(100);
            builder.Property(x => x.Description).IsRequired().HasMaxLength(500);
            builder.Property(x => x.Category).IsRequired().HasMaxLength(100);
            builder.Property(x => x.Language).IsRequired().HasMaxLength(50);
            builder.Property(x => x.TotalPages).IsRequired();

            // Seed data
            builder.HasData(
                new BookModel
                {
                    Id = Guid.NewGuid(),
                    Title = "The Alchemist",
                    Author = "Paulo Coelho",
                    Description = "The Alchemist follows the journey of an Andalusian shepherd",
                    Category = "Fiction",
                    Language = "English",
                    TotalPages = 208
                },
                new BookModel
                {
                    Id = Guid.NewGuid(),
                    Title = "To Kill a Mockingbird",
                    Author = "Harper Lee",
                    Description = "A novel about the serious issues of rape and racial inequality.",
                    Category = "Fiction",
                    Language = "English",
                    TotalPages = 281
                },
                new BookModel
                {
                    Id = Guid.NewGuid(),
                    Title = "1984",
                    Author = "George Orwell",
                    Description = "A dystopian social science fiction novel and cautionary tale about the dangers of totalitarianism. ",
                  Category = "Fiction",
                  Language = "English",
                  TotalPages = 328
                } 
            );
        }
    }
}

Let's break down the code above:

In Entity Framework Core, you can use the IEntityTypeConfiguration interface to configure the entity type and seed data for the database. The BookTypeConfigurations class implements the IEntityTypeConfiguration<BookModel> interface and provides the configuration for the BookModel entity.

• Configure Method: This method is used to configure the BookModel entity type. It defines the table name, primary key, and properties for the BookModel entity.

  • Table Name: The ToTable method specifies the name of the table to be created in the database. In this case, the table name is set to "Books".

  • Primary Key: The HasKey method specifies the primary key for the BookModel entity. The primary key is set to the Id property.

  • Properties: The Property method configures the properties of the BookModel entity. It specifies the data type, length, and constraints for each property.

• Seed Data: The HasData method seeds the database with initial data. It creates three BookModel objects with sample data for testing the API endpoints.

Now that we have created the BookTypeConfigurations class, we need to register this configuration in the ApplicationContext class. This ensures that the configuration is applied when the database is created or migrated.

We’re finally almost ready to test our API. But before we do that, we need to perform migrations to create the database and apply the seed data.

Remember that we added our database connection string in the appsettings.json file? Now let's perform a migration and later update our database for the migration to take effect.

How to Perform a Migration

Migrations allow you to update the database schema based on changes made to your model classes. In Entity Framework Core, you can use the dotnet ef migrations add command to create a new migration reflecting these changes.

To perform a migration, run the following command in the terminal:

dotnet ef migrations add InitialCreate

If the command is successful, you should see an output similar to this:

Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

You will now see a new folder called Migrations in your project. This folder contains the migration files that were created based on the changes made to your model classes. These migration files include the SQL commands required to update the database schema.

How to Update the Database

After creating the migration, you need to apply the migration to update the database schema. You can use the dotnet ef database update command to apply the migration and update the database. Make sure the SQL Server is running.

Run the following command in the terminal:

dotnet ef database update

This will update the database schema based on the changes made to your model classes. Make sure there are no errors on your database connection string.

How to Test the API Endpoints

Now we can test our endpoints using Swagger. To do this, run the application by executing the following command in the terminal:

dotnet run

This will run our application. You can open your browser and navigate to https://localhost:5001/swagger/index.html to access the Swagger documentation. You should see a list of API endpoints, request and response models, and the ability to test the endpoints directly from the browser.

If your port number is different from 5001, don't worry – it will still work. The port might change depending on the type of machine you're using, but it will still achieve the same result.

How to Test the Get All Books Endpoint

To test the Get All Books endpoint, follow these steps:

1. In the Swagger documentation, click on the GET /api/v1/books endpoint.

2. Click the Try it out button.

3. Click the Execute button.

This will send a request to the API to retrieve all the books in the database.

You should see the response from the API, which will include the list of books that were seeded in the database.

The image below shows the response from the API:

How to Test the Get Book by ID Endpoint

To test the Get Book by ID endpoint, follow these steps:

1. In the Swagger documentation, click on the GET /api/v1/books/{id} endpoint.

2. Enter the ID of a book in the id field. You can use one of the book IDs that was seeded in the database.

3. Click the Try it out button.

This will send a request to the API to retrieve the book with the specified ID. You should see the response from the API, which will include the book with the specified ID.

The image below shows the response from the API:

How to Test the Add Book Endpoint

To test the Add Book endpoint, follow these steps:

1. In the Swagger documentation, click on the POST /api/v1/books endpoint.

2. Click the Try it out button.

3. Enter the book details in the request body.

4. Click the Execute button.

This will send a request to the API to add a new book to the database.

You should see the response from the API, which will include the newly created book.

The image below shows the response from the API:

How to Test the Update Book Endpoint

To test the Update Book endpoint, follow these steps:

1. In the Swagger documentation, click on the PUT /api/v1/books/{id} endpoint.

2. Enter the ID of a book in the id field. You can use the id of one of the books that we just added.

3. Click the Try it out button.

This will send a request to the API to update the book with the specified ID.

You should see the response from the API, which will include the updated book.

The image below shows the response from the API:

How to Test the Delete Book Endpoint

To test the Delete Book endpoint, follow these steps:

1. In the Swagger documentation, click on the DELETE /api/v1/books/{id} endpoint.

2. Enter the ID of a book in the id field. You can use any of the ids from the books that we just added or the seeded data.

3. Click the Try it out button.

This will send a request to the API to delete the book with the specified ID.

The image below shows the response from the API:

Congratulations! You have implemented all the CRUD operations for books and tested the API endpoints using Swagger, verifying that they work as expected. You can now build on this foundation to add more features and functionality to your API.

Conclusion

This handbook explored how to create a minimal API in ASP.NET Core with .NET 8. We built a comprehensive book API that supports CRUD operations, implemented custom exceptions, defined and registered API endpoints, and enabled Swagger documentation for easy testing.

Following this tutorial, you have gained a solid foundation for building minimal APIs with ASP.NET Core. You can now apply this knowledge and create robust APIs for various domains and industries.

I hope you found this tutorial both helpful and informative. Thank you for reading!

Feel free to connect with me on social media:

• Twitter

• LinkedIn

• GitHub

This tutorial will serve as your introductory guide to TypeScript. It's designed to cater to learners at all stages – from beginners to advanced users. It teaches both fundamental and advanced TypeScript concepts, making it a helpful resource for anyone looking to delve into TypeScript.

The aim of this guide is not to be an exhaustive resource, but rather a concise and handy reference. It distills the essence of TypeScript into a digestible format.

Whether you're a novice just starting out, an intermediate learner aiming to consolidate your knowledge, or an advanced user in need of a quick refresher, this guide is crafted to meet your TypeScript learning requirements.

After carefully reading through this tutorial and practicing the examples it contains, you should have the skills to build robust, scalable, and maintainable TypeScript applications. We'll cover key TypeScript concepts like types, functions, classes, interfaces, generics, and more.

Table of Contents

• Prerequisites

• Who is this guide for?

• TypeScript vs. JavaScript

• Advantages of TypeScript

• Code Generation

• Installation

• Configuration

• Understanding tsconfig.json

• TypeScript Basics

• Type Declarations and Variables in TypeScript

• Functions in TypeScript

• Classes and Objects in TypeScript

• Interfaces in TypeScript

• Enums in TypeScript

• Generics in TypeScript

Prerequisites

Before you begin going through this guide, you should have a basic understanding of JavaScript. Familiarity with object-oriented programming concepts like classes, interfaces, and inheritance is also recommended.

But if you're new to these concepts, don't worry - we'll cover them in detail in this guide.

Who is this Guide For?

This guide is for anyone looking to learn TypeScript. Whether you're a beginner, an intermediate learner, or an advanced user, this guide is designed to meet your TypeScript learning needs.

It's also a handy reference for anyone looking to brush up on their TypeScript skills.

TypeScript vs JavaScript

TypeScript is a statically-typed superset of JavaScript, designed to enhance the development of large-scale applications.

It introduces optional static typing, classes, and interfaces to JavaScript, drawing parallels with languages like C# and Java. TypeScript code is transpiled to plain JavaScript, ensuring compatibility across various JavaScript environments.

While TypeScript and JavaScript can operate in the same environment, they exhibit key differences. The main one is that TypeScript is statically typed, providing type safety, while JavaScript is dynamically typed.

Let's delve into some of these differences:

TypeScript code is written in .ts or .tsx files, whereas JavaScript code resides in .js or .jsx files. The .tsx and .jsx extensions indicate that the file may contain JSX syntax, a popular choice for UI development in libraries like React.

Let's explore the differences between JavaScript and TypeScript through an example:

// JavaScript
function add(a, b) {
  return a + b;
}

// Calling the function
add(1, 2); // Returns: 3

In the JavaScript example above, the add function takes two parameters, a and b, and returns their sum. The function is invoked with the arguments 1 and 2, yielding 3. Notice that the function parameters are not annotated with types, which is typical in JavaScript.

Now, let's see how we can write the same function in TypeScript:

// TypeScript
function add(a: number, b: number): number {
  return a + b;
}

// Calling the function
add(1, 2); // Returns: 3

In the TypeScript version, we've annotated the parameters a and b with the number type. We've also specified that the function returns a number.

This is a key difference between JavaScript and TypeScript. TypeScript enforces type safety, meaning it checks the types of values at compile time and throws errors if they don't match the expected types.

This feature helps catch errors early in the development process, making TypeScript a popular choice for large-scale applications.

TypeScript and JavaScript are both powerful languages used in a wide range of applications. Let's summarize their key differences:

Advantages of TypeScript

TypeScript offers several advantages over JavaScript:

2. Improved Tooling: TypeScript's static typing enables better tooling support. Features like autocompletion, type inference, and type checking make the development process more efficient and enjoyable.

3. Better Documentation: TypeScript codebases are often easier to understand and maintain. The type annotations serve as implicit documentation, making it easier to understand what kind of values a function expects and returns.

4. Advanced Features: TypeScript supports advanced JavaScript features such as decorators and async/await, and it also introduces features not available in JavaScript, such as interfaces, enums, and tuples.

5. Refactoring: TypeScript's tooling makes refactoring larger codebases safer and more predictable. You can make large-scale changes with confidence.

6. Gradual Adoption: TypeScript is a superset of JavaScript, which means you can gradually adopt TypeScript in your projects. You can start by renaming your .js files to .ts and then you can gradually add type annotations as you see fit.

7. Community and Ecosystem: TypeScript has a growing community and ecosystem. Many popular JavaScript libraries, such as React and Angular, have TypeScript definitions, which makes it easier to use them in a TypeScript project.

Code Generation

TypeScript code isn't natively understood by browsers or Node.js, so it needs to be transpiled into JavaScript. This transpilation process is handled by the TypeScript compiler (tsc), which reads TypeScript code and generates equivalent JavaScript code.

To transpile a TypeScript file, you can use the tsc command followed by the filename:

$ tsc index.ts

This command transpiles the index.ts file into a index.js file in the same directory. The resulting JavaScript code can be executed in any JavaScript environment, such as a browser or Node.js.

Watching for File Changes

During active development, it's beneficial to have your TypeScript code automatically recompiled whenever you make changes. The TypeScript compiler provides a --watch option for this purpose:

$ tsc index.ts --watch

With this command, the compiler will monitor the index.ts file and automatically recompile it whenever it detects a change.

Configuring the TypeScript Compiler

For larger projects, it's common to have a configuration file, tsconfig.json, to manage compiler options. This file allows you to specify the root level files and the compiler options required to compile the project.

Here's an example of a tsconfig.json file:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

In this configuration, the compilerOptions object contains options for the compiler. The target option specifies the ECMAScript target version, the module option sets the module system, the strict option enables a wide range of type checking behavior, and the outDir option specifies the output directory for the compiled JavaScript files.

The include and exclude options are used to specify the files to be compiled and ignored, respectively.

To compile the project based on the tsconfig.json file, you can run the tsc command without any arguments:

$ tsc

This command will compile all TypeScript files in the project according to the options specified in the tsconfig.json file.

TypeScript Basics

In this section , we'll go through the basics of TypeScript. You'll see more examples of how TypeScript is statically typed, and you'll learn more about its tooling and error checking.

Installation

Before we dive into TypeScript, you'll need to make sure that you have Node.js installed on your system. Node.js is a runtime environment that allows you to run JavaScript outside of the browser. You can download Node.js from the official website.

Once Node.js is installed, you can install TypeScript using the Node Package Manager (npm), which comes bundled with Node.js.

Open your terminal and run the following command:

npm install -g typescript

This command installs TypeScript globally on your system. You can confirm the installation by running the tsc command, which stands for TypeScript compiler:

tsc --version

This command should display the version of TypeScript that you've installed.

Now that TypeScript is installed, we're ready to start our journey into the world of TypeScript!

Configuration

Great! Now that we have TypeScript installed, let's talk about something else important: configuration. For larger projects, it's common to have a configuration file, tsconfig.json, to manage compiler options. This file allows you to specify the root level files and the compiler options required to compile the project.

When you run the tsc command, the compiler looks for a tsconfig.json file in the current directory. If it finds one, it uses the options specified in the file to compile the project. If it doesn't find one, it uses the default options.

To generate a tsconfig.json file, you can run the following command:

tsc --init

Understanding tsconfig.json

Now that we have TypeScript installed and configured, let's dive deeper into the tsconfig.json file. This file is a crucial part of any TypeScript project. It holds various settings that determine how your TypeScript code gets compiled into JavaScript.

To create a tsconfig.json file, you can use the tsc --init command as I showed above. This command generates a tsconfig.json file in your current directory with some default settings.

Here's an example of what a tsconfig.json file might look like:

{
 "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist"
 },
 "include": ["src/**/*.ts"],
 "exclude": ["node_modules"]
}

In this configuration:

• The compilerOptions object contains settings for the TypeScript compiler.

• The target option tells the compiler which version of ECMAScript to compile your code down to.

• The module option sets the module system for your project.

• The strict option enables a wide range of type checking behavior.

• The outDir option specifies the directory where the compiled JavaScript files will be placed.

• The include and exclude options tell the compiler which files to include and exclude during the compilation process.

After setting up your tsconfig.json file, you can compile your TypeScript project by simply running the tsc command in your terminal. This command will compile all TypeScript files in your project according to the options specified in your tsconfig.json file.

Type Declarations and Variables in TypeScript

Let's now learn more about types. TypeScript supports several types, including number, string, boolean, object, null, undefined, symbol, bigint, and any. Let's explore each of these types in detail.

1. number: This type is used for numeric values. It can be an integer or floating-point value.

Example:

let age: number = 30;
let weight: number = 65.5;

2. string: This type is used for textual data. It can be defined using single quotes, double quotes, or template literals.

Example:

let name: string = 'John Doe';
let greeting: string = `Hello, ${name}`;

3. boolean: This type is used for logical values. It can only be true or false.

Example:

let isAdult: boolean = true;
let isStudent: boolean = false;

4. object: This type is used for complex data structures. An object can have properties and methods.

Example:

let person: object = { name: 'John Doe', age: 30 };
let date: object = new Date();

5. null: This type has only one value: null. It is used when you want to explicitly set a variable to have no value or object.

Example:

let emptyValue: null = null;
let anotherEmptyValue: null = null;

6. undefined: This type has only one value: undefined. It is used when a variable has been declared but has not yet been assigned a value.

Example:

let unassignedValue: undefined = undefined;
let anotherUnassignedValue: undefined;

7. symbol: This type is used to create unique identifiers for objects.

Example:

let symbol1: symbol = Symbol('symbol1');
let symbol2: symbol = Symbol('symbol2');

8. bigint: This type is used for whole numbers larger than 2^53 - 1, which is the upper limit for the number type.

Example:

let bigNumber: bigint = 9007199254740993n;
let anotherBigNumber: bigint = BigInt(9007199254740993);

9. any: This type is used when the type of a variable could be anything. It is a way of opting out of type-checking.

Example:

let variable: any = 'I am a string';
variable = 42; // I am a number now

Now let talk about some different ways you can declare variables in TypeScript.

TypeScript provides a way to define the shape of an object, including its properties and methods, using type declarations. This allows you to create reusable types that can be used to define the structure of objects throughout your codebase.

1. Type Aliases: Type aliases are a way to create a new name for an existing type. They are often used to define complex types that are used in multiple places.

Example:

type Point = {
  x: number;
  y: number;
}

let origin: Point = { x: 0, y: 0 };

In this example, Point is a type alias for an object with x and y properties. It is used to define the type of the origin object.

2. Intersection Types: Intersection types are a way to combine multiple types into a single type. They are often used to create complex types that have the properties of multiple other types.

Example:

type Printable = {
  print: () => void;
};

type Loggable = {
  log: () => void;
};

type Logger = Printable & Loggable;

let logger: Logger = {
  print: () => console.log('Printing...'),
  log: () => console.log('Logging...'),
};

In this example, Printable and Loggable are two types that have a print and log method, respectively. The Logger type is an intersection of Printable and Loggable, so it has both a print and log method.

3. Union Types: Union types are a way to define a type that can be one of several different types. They are often used to create flexible types that can represent a variety of values.

Example:

type ID = string | number;

let id: ID = '123';
id = 123;

In this example, ID is a union type that can be either a string or a number. It is used to define the type of the id variable, which can be assigned a string or a number.

4. Type Assertions: Type assertions are a way to tell the TypeScript compiler that you know more about the type of a value than it does. They are similar to type casting in other languages.

Example:

let value: any = 'Hello, TypeScript!';
let length: number = (value as string).length;

In this example, the as keyword is used to assert that value is of type string. This allows us to access the length property of the string.

Functions in TypeScript

Functions are the building blocks of any programming language. They encapsulate logic into reusable units of code, promoting code reuse and modularity. In TypeScript, functions can be defined using the function keyword or arrow functions (=>). Both methods have their own use cases and characteristics.

Let's talk about some types of functions in TypeScript:

1. Function Declarations: Functions can be declared using the function keyword followed by a unique function name. The function body is enclosed in curly braces {}.

Example:

function greet(name: string): void {
  console.log(`Hello, ${name}!`);
}

greet('Alice');  // Outputs: Hello, Alice!

In this example, greet is a function that takes one parameter, name, of type string. The function doesn't return anything, so its return type is void.

2. Arrow Functions: Arrow functions are a more modern syntax for writing functions in TypeScript and JavaScript. They are especially useful when writing small, inline functions.

Example:

const greet = (name: string): void => {
  console.log(`Hello, ${name}!`);
}

greet('Bob');  // Outputs: Hello, Bob!

In this example, greet is an arrow function that behaves exactly the same as the greet function in the previous example. The => symbol separates the function parameters and the function body.

3. Function Types: In TypeScript, you can specify the types of the parameters and the return value of a function. This provides type safety, ensuring that the function is called with the correct types of arguments and that it returns the correct type of value.

Example:

function add(a: number, b: number): number {
  return a + b;
}

let sum: number = add(1, 2);  // sum is 3

In this example, the add function takes two parameters, a and b, both of type number, and returns a number.

4. Optional and Default Parameters: TypeScript allows function parameters to be optional or have default values.

Example:

function greet(name: string, greeting: string = 'Hello'): void {
  console.log(`${greeting}, ${name}!`);
}

greet('Charlie');  // Outputs: Hello, Charlie!
greet('Charlie', 'Hi');  // Outputs: Hi, Charlie!

In this example, the greet function has two parameters, name and greeting. The greeting parameter is optional and has a default value of 'Hello'.

5. Rest Parameters: TypeScript supports rest parameters, which allow you to pass an arbitrary number of arguments to a function.

Example:

function sum(...numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

let total: number = sum(1, 2, 3, 4, 5); // total is 15

In this example, the sum function takes an arbitrary number of arguments and returns their sum.

Classes and Objects in TypeScript

Classes are a fundamental part of object-oriented programming (OOP). They are templates for creating objects, providing initial values for state (member variables) and implementations of behavior (member functions or methods).

TypeScript supports classes, which are declared using the class keyword. One advantage of TypeScript classes is that they support object-oriented programming (OOP) features such as inheritance, encapsulation, and polymorphism.

1. Class Declaration: In TypeScript, classes are declared using the class keyword.

Example:

class Person {
  name: string;
  age: number;

  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }

  greet(): void {
    console.log(`Hello, my name is ${this.name} and I am ${this.age} years old.`);
  }
}

let john = new Person('John', 25);
john.greet(); // Outputs: Hello, my name is John and I am 25 years old.

In this example, Person is a class with two properties, name and age, and a method greet. The constructor is a special method for creating and initializing an object created with a class.

2. Inheritance: TypeScript supports inheritance, a mechanism of basing a class upon another class, retaining similar implementation. Inheritance is achieved using the extends keyword.

Example:

class Employee extends Person {
  department: string;

  constructor(name: string, age: number, department: string) {
    super(name, age);
    this.department = department;
  }

  greet(): void {
    super.greet();
    console.log(`I work in ${this.department}.`);
  }
}

let jane = new Employee('Jane', 30, 'HR');
jane.greet(); // Outputs: Hello, my name is Jane and I am 30 years old. I work in HR.

In this example, Employee is a class that extends Person. It adds a new property department and overrides the greet method. The super keyword is used to call corresponding methods of the parent class.

3. Abstract Classes: Abstract classes are classes that cannot be instantiated directly. They are used as base classes for other classes and can contain abstract methods that must be implemented by derived classes.

Example:

abstract class Shape {
  abstract area(): number;
}

class Circle extends Shape {
  radius: number;

  constructor(radius: number) {
    super();
    this.radius = radius;
  }

  area(): number {
    return Math.PI * this.radius ** 2;
  }
}

let circle = new Circle(5);
console.log(circle.area()); // Outputs: 78.54

In this example, Shape is an abstract class with an abstract method area. The Circle class extends Shape and implements the area method. Abstract classes are useful for defining a common interface for a set of classes.

4. Encapsulation: Encapsulation is the bundling of data (properties) and methods that operate on the data (methods) into a single unit called a class. In TypeScript, encapsulation is achieved by using access modifiers such as public, private, and protected.

Example:

class Person {
  private name: string;
  protected age: number;

  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }

  greet(): void {
    console.log(`Hello, my name is ${this.name} and I am ${this.age} years old.`);
  }
}

let john = new Person("John", 25);
console.log(john.name); // Error: Property "name" is private
console.log(john.age);  // Error: Property "age" is protected

In this example, name is a private property of the Person class, so it cannot be accessed from outside the class. age is a protected property, so it can be accessed from subclasses but not from outside the class.

5. Polymorphism: Polymorphism is the ability of an object to take on many forms. In TypeScript, polymorphism is achieved through method overriding, where a method in a subclass has the same name and signature as a method in its superclass.

Example:

class Animal {
  speak(): void {
    console.log('Animal makes a sound');
  }
}

class Dog extends Animal {
  speak(): void {
    console.log('Dog barks');
  }
}

let animal: Animal = new Dog();
animal.speak(); // Outputs: Dog barks

In this example, Animal is a base class with a speak method. Dog is a subclass that overrides the speak method. When an instance of Dog is assigned to a variable of type Animal, the speak method of Dog is called.

6. Access Modifiers: TypeScript supports the access modifiers public, private, and protected. By default, each member is public.

Example:

class Animal {
  private name: string;

  constructor(name: string) {
    this.name = name;
  }

  public getName(): string {
    return this.name;
  }
}

let dog = new Animal('Dog');
console.log(dog.getName()); // Outputs: Dog

In this example, name is a private member of the Animal class. It can only be accessed within the Animal class. The getName method is public, so it can be called from outside the class.

Interfaces in TypeScript

Interfaces in TypeScript are powerful ways to define contracts within your code. They are used to type-check whether an object fits a certain structure.

By defining an interface we can name a specific combination of variables, making sure they will always be used as a set.

1. Interface Declaration: Interfaces are declared with the interface keyword.

Example:

interface Person {
  name: string;
  age: number;
}

let john: Person = { name: 'John', age: 25 };

In this example, Person is an interface that describes an object that has a name of type string and an age of type number.

2. Optional Properties: Interface properties can be marked as optional with ?.

Example:

interface Person {
  name: string;
  age?: number;
}

let alice: Person = { name: 'Alice' };

In this example, age is an optional property in the Person interface. The object alice is still a Person even though it doesn't have an age.

3. Function Types: Interfaces can also describe function types.

Example:

interface GreetFunction {
  (name: string, age: number): string;
}

let greet: GreetFunction = function(name: string, age: number): string {
  return `Hello, my name is ${name} and I am ${age} years old.`;
};

In this example, GreetFunction is an interface that describes a function that takes a name and an age and returns a string.

4. Extending Interfaces: Interfaces can extend one another, creating a new interface that inherits the members of the base interface.

Example:

interface Animal {
  name: string;
}

interface Dog extends Animal {
  breed: string;
}

let myDog: Dog = { name: 'Rex', breed: 'German Shepherd' };

In this example, Dog extends Animal, so a Dog has both a name and a breed.

Enums in TypeScript

Enums are a way to define a set of named constants. They are often used to represent a set of related values, such as the days of the week or the months of the year.

TypeScript supports both numeric and string enums, providing a flexible way to define and work with sets of constants.

1. Numeric Enums: Numeric enums are a way to define a set of named constants with numeric values. By default, the values of the constants start at 0 and increment by 1 for each subsequent constant.

Example:

enum Day {
  Sunday,
  Monday,
  Tuesday,
  Wednesday,
  Thursday,
  Friday,
  Saturday
}

let today: Day = Day.Monday;

In this example, Day is a numeric enum that represents the days of the week. The constants Sunday, Monday, Tuesday, and so on are assigned numeric values starting from 0.

2. String Enums: String enums are a way to define a set of named constants with string values. Unlike numeric enums, the values of the constants in a string enum are initialized with the value of the constant name.

Example:

enum Month {
  January = 'January',
  February = 'February',
  March = 'March',
  April = 'April',
  May = 'May',
  June = 'June',
  July = 'July',
  August = 'August',
  September = 'September',
  October = 'October',
  November = 'November',
  December = 'December'
}

let currentMonth: Month = Month.June;

In this example, Month is a string enum that represents the months of the year. The constants January, February, March, and so on are assigned string values equal to their names.

3. Computed Enums: Enums can have computed values, which are initialized with an expression instead of a constant value. This allows for more flexibility in defining the values of the constants.

Example:

enum Color {
  Red = 1,
  Green = Math.pow(2, 2),
  Blue = Math.pow(2, 3)
}

let color: Color = Color.Green;

In this example, Color is an enum with computed values. The constants Red, Green, and Blue are assigned the values 1, 4, and 8, respectively, using the Math.pow function.

4. Reverse Mapping: Enums in TypeScript support reverse mapping, which means that you can access the name of a constant from its value. This is useful for debugging and logging purposes.

Example:

enum Day {
  Sunday,
  Monday,
  Tuesday,
  Wednesday,
  Thursday,
  Friday,
  Saturday
}

let dayName: string = Day[1]; // 'Monday'

In this example, the Day enum is used to access the name

Generics in TypeScript

Generics are a way to define a function or class that can be used with different types of data. They are often used to create reusable components that can work with different types of data.

TypeScript supports generics, allowing you to write type-safe code that is flexible and reusable.

Now let's look at some examples of generic functions and classes.

1. Generic Functions: Generic functions are functions that can work with a variety of data types. They are defined using type parameters, which are placeholders for the actual types that will be used when the function is called.

Example:

function identity<T>(value: T): T {
  return value;
}

let result1: number = identity<number>(42);
let result2: string = identity<string>('Hello, TypeScript!');

In this example, identity is a generic function that takes a type parameter T and returns a value of type T. The type parameter T is used to specify the type of the argument and the return value.

2. Generic Classes: Generic classes are classes that can work with a variety of data types. They are defined using type parameters, which are placeholders for the actual types that will be used when the class is instantiated.

Example:

class Box<T> {
  value: T;

  constructor(value: T) {
    this.value = value;
  }
}

let box1: Box<number> = new Box<number>(42);
let box2: Box<string> = new Box<string>('Hello, TypeScript!');

In this example, Box is a generic class that takes a type parameter T and has a property value of type T. The type parameter T is used to specify the type of the value stored in the box.

3. Generic Constraints: Generic constraints are a way to restrict the types that can be used with a generic function or class. They are defined using the extends keyword, followed by the type or interface that the type parameter must extend.

Example:

interface Printable {
  print(): void;
}

function printValue<T extends Printable>(value: T): void {
  value.print();
}

class Person implements Printable {
  print(): void {
    console.log('Printing person...');
  }
}

let person: Person = new Person();
printValue(person);

In this example, Printable is an interface that defines a print method. The printValue function is a generic function that takes a type parameter T that must extend Printable. The Person class implements the Printable interface.

At this point you have a basic understanding of TypeScript and you can start diving into more advanced concepts.

Conclusion

In this article, you've learned the basics of TypeScript.

We talked about the basic syntax of TypeScript, such as variables, functions, and classes.

You also learned about TypeScript's built-in types, such as numbers, strings, and booleans.

We discussed TypeScript's built-in enumerations, such as number enums, string enums, and computed enums. And you learned about TypeScript's generic types, such as generic functions and classes.

Thank you for reading!

Throughout this tutorial, you'll learn how to create, read, update, and delete Todo items, and how to leverage Entity Framework Core to interact with a database.

Table of Contents

• Prerequisites
• How to Enhance Your Development Experience with Visual Studio Code Extensions
• Learning Outcomes
• What is .NET Core?
• .NET Core vs .NET Framework
• Step 1: Set Up Your Project Directory
• Step 2: Establish Your Project Structure
• Step 3: Create the Todo Model
• Step 4: Set Up the Database Context
• Step 5: Define Data Transfer Objects (DTOs)
• Step 6: Implement Object Mapping for the Todo API
• Step 7: Implement Global Exception Handling Middleware
• Step 8: Implement the Service Layer and Service Interface
• step 9: Implement the CreateTodoAsync Method in the Service Class
• Step 10: Implement the GetAllAsync Method in the Service Class
• step 11: Create the TodoController Class
• Step 12: Implement the CreateTodoAsync Method in the TodoController Class
• Step 13: Implement Migrations and Update the Database
• Step 14: Verify Your API with Postman
• Step 15: Retrieve All Todo Items
• Step 16: Implement the GetByIdAsync Method
• Step 17: Implement the UpdateTodoAsync Method
• Step 18: Implement the DeleteTodoAsync Method
• Step 19: Test Your API Endpoints with Postman
• Conclusion

Before we dive in, let's ensure you're equipped with the necessary prerequisites.

Prerequisites

Before you get started, make sure you have the necessary tools installed on your machine. Here are the download links:

• .NET SDK
• Visual Studio Code
• Visual Studio 2019
• Postman
• SQLServer

After installing the .NET SDK, it's important to verify its installation and check the version. For this tutorial, we'll be using .NET 8.0.

To check the version of the .NET SDK installed on your machine, open the terminal and run the following command:

dotnet --version

If the .NET SDK is installed correctly, the version number will be displayed in the terminal:

8.0

If you see a different version number, ensure you have .NET 8.0 installed on your machine.

How to Enhance Your Development Experience with Visual Studio Code Extensions

Visual Studio Code, a lightweight and open-source code editor, is an excellent tool for building .NET Core applications. And you can further enhance its functionality with extensions that streamline the development process.

Here are two recommended extensions for .NET Core development:

• C# for Visual Studio Code
• C# Namespace Autocompletion

To install these extensions, follow these steps:

1. Open Visual Studio Code.
2. Click on the Extensions icon in the Activity Bar on the side of the window to open the Extensions view.
3. In the search bar, type the name of the extension.
4. In the search results, locate the correct extension and click on the Install button.

Here's how the Extensions view looks in Visual Studio Code:

• C# Devkit Extension for Visual Studio Code

• Namespace Autocompletion Extension for Visual Studio Code

In the images above, the extensions are already installed. If they're not installed on your system, you can do so by clicking on the Install button.

With these essential tools in place, we're now fully equipped to start building our Todo API.

Learning Outcomes

By the end of this tutorial, you'll have learned how to:

• Set up a new .NET Core project using the .NET Core CLI
• Define a model for a Todo item
• Create a database context to interact with the database
• Implement routing and controllers for the Todo API
• Create a service class to handle business logic
• Implement CRUD operations for the Todo API
• Handle exceptions globally using middleware
• Test the API endpoints using Postman

If you're new to C# and .NET, don't worry. I'll explain all the concepts in depth to ensure you understand them. For additional information, you can refer to the C# documentation.

Before we delve into the code, let's clarify what .NET Core is.

What is .NET Core?

.NET Core, also known as ASP.NET, is a cross-platform framework that facilitates the building of web applications, APIs, and services. It's a free, open-source, and high-performance framework, designed for creating modern, cloud-based, internet-connected applications. It's the successor to the .NET Framework.

But what's the difference between .NET Core and .NET Framework?

.NET Core vs .NET Framework

.NET Core and .NET Framework are two distinct frameworks used for application development. .NET Core is a cross-platform framework that operates on Windows, macOS, and Linux. It's a modular, open-source, and free-to-use framework, designed for building modern, cloud-based, internet-connected applications.

On the other hand, .NET Framework is a Windows-only framework used for building Windows desktop applications, web applications, and services. Unlike .NET Core, it's not open-source or free to use. However, it's a mature framework that has been around for a long time.

With a foundational understanding of .NET Core and .NET Framework under your belt, we're ready to dive into building our Todo API.

In this tutorial, we'll leverage .NET Core to construct a Todo API that performs CRUD operations. Our journey will take us through creating a new project, defining the Todo model, setting up the database, and implementing the CRUD operations.

Let's begin with Visual Studio Code. In this tutorial, we'll be using the .NET Core CLI to create our project and build our API. If you prefer Visual Studio 2019, you can follow along using that IDE as well but we will be using Visual Studio Code for this article.

Step 1: Set Up Your Project Directory

First, navigate to the directory where you want to house your project. This could be any folder on your system where you'd like to store your code.

Once you're in the desired directory, open the terminal. You can do this in Visual Studio Code by going to View -> Terminal or by pressing Ctrl + a backtick.

With the terminal open, type the following command: