Fuji Nguyen, Author of OnionAPI Template

.NET 7 was officially launched on November 8, 2022, succeeding .NET 6. With the release of the Visual Studio template OnionAPI v7, developers can now scaffold .NET 7 REST API projects utilizing the Clean Architecture pattern, as depicted in the accompanying diagram.

When you initiate a new project using the OnionAPI template in Visual Studio, it will create a solution containing five distinct projects. Each project is prefixed with the project name and features its own customizable namespace. Here’s a breakdown of the purpose of each project:

• Domain: Houses the entities and shared models.
• Application: Contains interfaces, CQRS functionalities, exceptions, and behaviors.
• Infrastructure.Persistence: This project includes the data access API based on Entity Framework.
• Infrastructure.Shared: Provides common services like Mail Service, Date Time Service, Mock services, and more.
• WebApi: This is where the API controllers are located to expose REST API resources and endpoints accessible via Swagger.

Tutorial Overview

This tutorial is divided into four parts:

1. Downloading and Installing the Template: Learn how to set up the OnionAPI template in Visual Studio.
2. Creating a New Web API Project: Utilize the OnionAPI template to scaffold a new ASP.NET Core Web API project running on .NET v7.
3. Exploring the Generated Source Code: Get acquainted with the source code produced by the template.
4. Testing the Web API Project: Conduct a test run of the Web API project to ensure everything functions correctly.

Prerequisites:

• Latest .NET Core 7 SDK
• Visual Studio 2022 Community Edition — a free code editor for C#

Part 1: Downloading and Installing the Template

To set up the OnionAPI template from the Visual Studio Marketplace, follow these steps:

1. Open Visual Studio 2022 and navigate to the "Extensions" menu.
2. Click on "Manage Extensions."
3. In the "Manage Extensions" window, select the "Online" tab on the left.
4. Use the search bar to locate the template by searching for "OnionAPI." Refer to the visual aid in the next section.
5. Once you find the template, click the "Download" button.
6. Visual Studio will download and install the template. A restart may be required for it to appear.

Part 2: Creating a New Web API Project

To scaffold a new Web API project using the Visual Studio template, do the following:

1. Open Visual Studio and select "Create a new project" from the start page or File menu.
2. In the "Create a new project" dialog, search for and select the OnionAPI Template, then click "Next."
3. In the "Configure your new project" dialog, provide a name (e.g., MyNetcore7WebAPI) and select a save location. Click "Create."

The OnionAPI template will generate a new ASP.NET Core Web API project adhering to the Clean Architecture principles.

Part 3: Exploring the Generated Source Code

The scaffolded source code may initially seem overwhelming due to its organization into five projects across three folders: Core, Infrastructure, and Presentation, corresponding to the Clean Architecture layers.

Are you curious about where the API controllers are? They can be found in the Controllers folder within the WebAPI project. For clarity, check the visual guide provided.

The controllers do not operate in isolation; they utilize a CQRS pattern, passing requests to Handlers for processing. The Handlers are located in the Features folder within the Application project.

Handlers manage the application’s business logic and may access the database repository when necessary. For added security, Fluent Validation is integrated to ensure data integrity.

Part 4: Testing the Web API Project

The OnionAPI template conveniently sets up two REST resources: Employees and Positions. The Employees resource is a mock API that generates data at runtime using the Bogus library. The Positions resource pulls data from a real database table, which is seeded with 1,000 rows of dummy data upon the first run.

To test the REST API in Swagger:

1. Click on the Employees > GET option to expand.
2. Hit the "Try it out" button.
3. Enter desired parameters, such as searching for "Chief" in the employeeTitle field.
4. Specify the order by column name and click "Execute."

Examine the JSON output to witness the capabilities of the REST API.

Understanding the JSON output is crucial; it includes pagination details and a structured response for easy frontend consumption.

If you want to reduce the amount of data sent over the network, you can specify which columns to return in the Fields parameter.

The scaffolded code also provides CRUD operation examples for the Positions resource, illustrating methods like POST, GET, PUT, and DELETE.

Serilog is integrated within the template to facilitate monitoring of WebAPI requests and error events. You can view structured logs in both the output console and text files.

Video Demonstration

This video illustrates how to create a new ASP.NET Web API project using the OnionAPI Visual Studio template and how to access the API endpoints via Swagger UI after running the project.

Further Learning

I’m thrilled to announce a new blog series dedicated to building dynamic web applications using Single Page Application (SPA) architecture, along with modern tools such as Angular 15, Bootstrap 5, and .NET 7 API. This series will include an extensive project demo and multipart blog posts that explore full-stack components in detail, offering the latest tools and techniques in the industry.

The WebAPI layer in this series will be generated with the powerful OnionAPI template, and I will provide a detailed explanation of the generated source code to enhance your understanding.

Recommended Contents

• Fullstack Angular 15, Bootstrap 5 & .NET 7 API: Project Demo and Tutorial
• Server-Side Pagination, Sorting, Filtering, and Modal Detail Display
• In-depth Guide to REST API from Design to Implementation
• EF Core Pagination for 2 Million Rows, Performance Tune-up, and Lessons Learned
• Creating Realistic Test Data with Bogus Library
• Guide to CRUD Operations with CQRS and Mediator Pattern in REST API
• Migrating Entity Framework Core from MS SQL to Oracle
• Exploring Serilog and AutoWrapper for Error Handling
• Understanding FluentValidation
• Leveraging MediatR and AutoMapper in CQRS
• Utilizing Bogus Library for Fake Data in ASP.NET Core Web API

Fuji Nguyen