Multi-tenancy is a common architectural concept for modern SaaS applications, enabling a single application to serve multiple customers (each known as a tenant) while maintaining data isolation, scalability, and operational efficiency. The "Separate database per tenant" approach offers the highest level of data isolation, making it ideal for scenarios with strict data privacy, security, and performance requirements.

In this article, we’ll explore how to use this advanced multi-tenancy model using the powerful capabilities of the ABP Framework and the .NET platform.

In this article, I will use ABP Studio for creating the application. ABP Studio allows to select "separate database per tenant" option only for commercial licenses.

Understanding Database Models for a Multi-Tenant Application

In the next sections, I will explain various models for database models of a multi-tenant solution:

• Single (shared) Database Model
• Separate Tenant Databases Model
• Hybrid Multi-Tenant Database Model

Let's start with the first one...

Single (shared) Database Model

In the shared database model, all the application data stored in a single physical database. In the following diagram, you see different kind of users use the application, and the application stored their data in a main database:

This is the default behavior when you create a new ABP application, because it is simple to begin with and proper for most applications.

In this model, a single database table may contain data of multiple tenants. Each row in these tables have a TenantId field which is used to distinguish the tenant data and isolate a tenant's data from other tenant users. To make your entities multi-tenant aware, all you have to do is to implement the IMultiTenant interface provided by the ABP Framework.

Here, is an example Product entity that should support multi-tenancy:

using System;
using Volo.Abp.Domain.Entities;
using Volo.Abp.MultiTenancy;

namespace MtDemoApp
{
    public class Product : AggregateRoot<Guid>, IMultiTenant //Implementing the interface
    {
        public Guid? TenantId { get; set; } //Defined by the IMultiTenant interface
        public string Name { get; set; }
        public float Price { get; set; }
    }
}

In this way, ABP Framework automatically isolates data using the TenantId property. You don't need to care about how to set TenantId or filter data when you need to query from database - all automated.

Separate Tenant Databases Model

In the separate tenant database model, each tenant has a dedicated physical database (with a separate connection string), as shown below:

ABP Framework can automatically select the right database from the current user's tenant context. Again, it is completely automated. You just need to set a connection string for a tenant, as we will do later in this article.

Even each tenant has a separate database, we still need to a main database to store host-side data, like a table of tenants, their connection strings and some other management data for tenants. Also, tenant-independent (or tenant-shared) application data is stored in the main database.

Hybrid Multi-Tenant Database Model

Lastly, you may want to have a hybrid model, where some tenants shares a single database (they don't have separate databases) but some of them have dedicated databases. In the following figure, Tenant C has its own physical database, but all other tenants data stored in the main database of the application.

ABP Framework handles the complexity: If a tenant has a separate database it uses that tenant's database, otherwise it filters the tenant data by the TenantId field in shared tables.

Understanding the Separate Tenant Schema Approach

When you create a new ABP solution, it has a single DbContext class (for Entity Framework Core) by default. It also includes the necessary EF Core code-first database migrations to create and update the database. As a result of this approach, the main database schema (tables and their fields) will be identical with a tenant database schema. As a drawback of that, tenant databases have some tables that are not meaningful and not used. For example, Tenants table (a list of tenants) will be created in the tenant database, but will never be used (because tenant list is stored in the main database).

As a solution to that problem, ABP Studio provides a "Use separate tenant schema" option on the Multi-Tenancy step of the solution creation wizard:

This option is only available for the Layered Monolith (optionally Modular) Solution Template. We don't provide that option in other templates, because:

• Single-Layer template is recommended for more simpler applications with an easy-to-understand architecture. We don't want to add these kind of complications in that template.
• Microservice template already has a separate database for each service. Having multiple database schema (and multiple DbContext classes) for each service makes it over complicated without bringing much value.

While you can manually convert your applications so they support separate database schema approach (ABP is flexible), it is not recommended to do it for these solution types.

Note that "Separate database per tenant" approach is already supported by default for the Single-Layer template too. "Separate tenant schema" is something different as I explained in this section.

Creating a new Application

Follow the Get Started tutorial to create a new ABP application. Remember to select the "Use separate tenant schema" option since I want to demonstrate it in this article.

Understanding the DbContext Structure

When you open the solution in your IDE, you will see the following structure under the .EntityFrameworkCore project:

There are 3 DbContext-related classes here (MtDemoApp is your application name):

• MtDemoAppDbContext class is used to map entities for the main (host + shared) database.
• MtDemoAppTenantDbContext class is used to map entities for tenant that have separate physical databases.
• MtDemoAppDbContextBase is an abstract base class for the classes explained above. In this way, you can configure common mapping logic here.

Let's see these classes a bit closer...

The Main DbContext Class

Here the main DbContext class:

public class MtDemoAppDbContext : MtDemoAppDbContextBase<MtDemoAppDbContext>
{
    public MtDemoAppDbContext(DbContextOptions<MtDemoAppDbContext> options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        builder.SetMultiTenancySide(MultiTenancySides.Both);

        base.OnModelCreating(builder);
    }
}

• It inherits from the MtDemoAppDbContextBase as I mentioned before. So, any configuration made in the base class is also valid here.
• OnModelCreating overrides the base method and sets the multi-tenancy side as MultiTenancySides.Both. Both means this database can store host data as well as tenant data. This is needed because we store data in this database for the tenants who don't have a separate database.

The Tenant DbContext class

Here is the tenant-specific DbContext class:

public class MtDemoAppTenantDbContext : MtDemoAppDbContextBase<MtDemoAppTenantDbContext>
{
    public MtDemoAppTenantDbContext(DbContextOptions<MtDemoAppTenantDbContext> options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        builder.SetMultiTenancySide(MultiTenancySides.Tenant);

        base.OnModelCreating(builder);
    }
}

The only difference is that we used MultiTenancySides.Tenant as the multi-tenancy side here, since this DbContext will only have entities/tables for tenants that have separate databases.

The Base DbContext Class

Here is the base DbContext class:

public abstract class MtDemoAppDbContextBase<TDbContext> : AbpDbContext<TDbContext>
    where TDbContext : DbContext
{
    
    public MtDemoAppDbContextBase(DbContextOptions<TDbContext> options)
        : base(options)
    {

    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);

        /* Include modules to your migration db context */

        builder.ConfigurePermissionManagement();
        builder.ConfigureSettingManagement();
        builder.ConfigureBackgroundJobs();
        builder.ConfigureAuditLogging();
        builder.ConfigureIdentityPro();
        builder.ConfigureOpenIddictPro();
        builder.ConfigureFeatureManagement();
        builder.ConfigureLanguageManagement();
        builder.ConfigureSaas();
        builder.ConfigureTextTemplateManagement();
        builder.ConfigureBlobStoring();
        builder.ConfigureGdpr();

        /* Configure your own tables/entities inside here */

        //builder.Entity<YourEntity>(b =>
        //{
        //    b.ToTable(MtDemoAppConsts.DbTablePrefix + "YourEntities", MtDemoAppConsts.DbSchema);
        //    b.ConfigureByConvention(); //auto configure for the base class props
        //    //...
        //});

        //if (builder.IsHostDatabase())
        //{
        //    /* Tip: Configure mappings like that for the entities only
               * available in the host side,
        //     * but should not be in the tenant databases. */
        //}
    }
}

This DbContext class configures database mappings for all the application modules used by this application by calling their extension methods, like builder.ConfigureBackgroundJobs(). Each of these extension methods are defined as multi-tenancy aware and care about what you've set for the multi-tenancy side.

Where to Configure Your Entities?

You can configure your entity mappings in the OnModelCreating method in any of the DbContext classes that was explained:

• If you configure in the main DbContext class, these configuration will be valid only for the main database. So, don't configure tenant-related configuration here, otherwise, it won't be applied for the tenants who have separate databases.
• If you configure in the tenant DbContext class, it will be valid only for the tenants with separate databases. You rarely need to do that. You typically want to make same configuration in the base DbContext to support hybrid scenarios (some tenants use the main (shared) database and some tenants have separate databases).
• If you configure in the base DbContext class, it will be valid for the main database and tenant databases. You typically define tenant-related configuration here. That means, if you have a multi-tenant Product entity, then you should define its EF Core database mapping configuration here, so the Products table is created in the main database as well as in the tenant databases.

The recommended approach is to configure all the mapping in the base class, but add controls like builder.IsHostDatabase() and builder.IsTenantDatabase() to conditionally configure the mappings:

Adding Database Migrations

In this section, I will show how to configure your entity mappings, generate database migrations and apply to the database.

Defining an Entity

Let's define a Product entity in the .Domain layer of your application:

using System;
using Volo.Abp.Domain.Entities;
using Volo.Abp.MultiTenancy;

namespace MtDemoApp
{
    public class Product : AggregateRoot<Guid>, IMultiTenant
    {
        public Guid? TenantId { get; set; }
        public string Name { get; set; }
        public float Price { get; set; }
    }
}

Configuring the Database Mapping

Open the MtDemoAppDbContextBase class and add the following property to the class:

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

Then add the following mapping code inside the OnModelCreating method (after all other existing code):

builder.Entity<Product>(b =>
{
    b.ToTable(MtDemoAppConsts.DbTablePrefix + "Products", MtDemoAppConsts.DbSchema);
    b.ConfigureByConvention(); //auto-configure for the base class props
    b.Property(x => x.Name).IsRequired().HasMaxLength(100);
});

We made the configuration in the base class since the Products table should be created in all databases, not only in the main database.

DbTablePrefix and DbSchema are optional and configurable in your application. You can change or remove them.

Add a New Database Migration for the Main Database

To add a new EF Core database migration, we can use ABP Studio UI or EF Core command-line commands. I will show both of these approaches here.

Using the ABP Studio "Add Migrations" UI

You can right-click the .EntityFrameworkCore package in the ABP Studio's Solution Explorer panel and select EF Core CLI -> Add Migration command as shown below:

You set a migration name on the opened dialog:

If you select the Update Database checkbox it will apply changes to the database after generating the migration code.

Lastly, select the main DbContext class for this migration:

This dialog is shown when your application has multiple DbContext classes. Once you click the OK button, a new migration class is added under the Migrations folder of the .EntityFrameworkCore project (you can see in your coding editor):

Since we selected the Update Database option, the database table is also created. The following screenshot shows the AppProducts table (App is the default prefix for your tables, but you can change or remove it) in Microsoft SQL Server Management Studio:

Using a Command-Line Terminal

If you prefer to use the command-line terminal (instead of ABP Studio UI), open a command-line terminal in the directory of the .EntityFrameworkCore project. As a shortcut, you can right-click the .EntityFrameworkCore project in ABP Studio, then select Open with -> Terminal command as shown in the following figure:

Then you can use the EF Core command-line tool to add a new database migration:

dotnet ef migrations add "Added_Product_Entity" --context MtDemoAppDbContext

It is important to set the --context parameter since we have two DbContext classes in the same project.

After adding the migration, you can update the database:

dotnet ef database update "Added_Product_Entity" --context MtDemoAppDbContext

If you are using Visual Studio, you can also use the Package Manager Console inside your IDE to add migrations and update the database.

Add a New Database Migration for the Tenant Database

We added a database migration for the main (shared) database. We also need to add a new database migration for tenants who have separate databases.

This time, no need to configure the DbContext since we did it in the base DbContext class, so it is valid for both of the DbContext classes. Just right-click the .EntityFrameworkCore package in the ABP Studio's Solution Explorer panel and select EF Core CLI -> Add Migration command as shown below:

You can set the same or a different migration name here:

The important part is to select the Tenant DbContext in the next dialog, because we want to change the tenant database this time:

After clicking the OK button, it will add a new database migration class, but this time to the TenantMigrations folder:

ABP Studio is smart enough to select the right folder name for the new migration by mapping with the DbContext name. However, you could manually type TenantMigrations in the Output directory textbox.

Since we selected the Update Database option, it also applied changes to the database. But, which database? Interestingly, it automatically creates a second database for tenants with the project name + _Tenant suffix:

This new database is never used on runtime or production. It is only created to allow you to see the schema (tables and their fields) on development time to be sure that everything is as expected. As you see, some tables (like Saas* and OpenIddict*) are not available in that database, since they are used on the host side and only necessary to be in the main database.

So, where is the real tenant database? If a tenant's database is dedicated (separate), it is created on runtime as I will explain in the Managing Tenant Databases and Connection Strings section later.

You can see that database's connection string in the appsettings.development.json file of the .DbMigrator project in the solution. If you want to understand how it works, you can check source code of the DbContextFactory classes in the .EntityFrameworkCore project:

These factory classes are used to create DbContext instances when you execute Add Migration and Update Database commands.

Managing Tenant Databases and Connection Strings

Until now, we even didn't run the application. It is the time to do it.

Running the Application with ABP Studio

You can run the .Web project in your IDE. But I prefer to use ABP Studio's Solution Runner feature here. You can open the Solution Runner panel in ABP Studio and click the play icon near to the solution root (MyDemoApp):

Once the application runs (and you see the blue link icon near to it), right click and select the Browse command:

It will open the application's UI in the built-in browser of ABP Studio. You can Login the application (with admin as user name and 1q2w3E* as the default password) and navigate to the Saas -> Tenants page.

Creating a New Tenant with the Shared Database

The Tenants page of the SaaS module is shown below:

As you see, there is no tenant at the beginning. I can click the + New tenant button to create the first tenant:

On this screen, we can set the base tenant information. If you click the Database connection strings tab, you can see the following UI:

For this first tenant, I will keep it as default and use the shared (main) database for this tenant's data. After clicking the Save button, the tenant is created and an initial data seed operation is automatically performed for us. To see an example, you can open the database, show rows of the AbpUsers table:

As you see, a new admin user has been created with a TenantId. The first row is the admin user of the host side. So, ABP allows to define same user name in different tenants, because their data (users in this example) are completely isolated from each other.

Sign in with the new Tenant

We created a new tenant. In this step, we will sign in with the new tenant's admin user to see the application UI by that new tenant. To do that, we should logout from the host admin user first. Click the user name (admin) on the top right area of the application and select the Log out command:

Click the Login button again, which redirects you to the Login page:

In this page, click the switch button near to the TENANT selection area and type acme as Name:

Once you click the Save button, you are now in the acme tenant's context. You can see it on the TENANT selection area:

This kind of tenant switch feature is very useful in development to quickly change tenants to test your application. However, in production, you typically want to use subdomain/domain names or another mechanism to determine tenants automatically. When you configure domain based resolution, the tenant selection area is automatically disappears from the login page. You can check the multi-tenant document to learn how to configure it.

After switching to the acme tenant, we can use admin as user name and the password you set during the tenant creation (I had set it as 1q2w3E*) to login to the application.

Here a screenshot from the Roles page after signing in as the acme tenant's admin user:

Notice that each tenant has its own roles, users, permissions, and other data. If you change roles here, it doesn't affect other tenants or the host side.

Also, you can see that there are less menu items compared to host side. For example, tenant management page is not available for tenants as you can expect.

Switch Back to the Host Side

To switch back to the host side to add a new tenant, logout from the application, click the Login button again to open the login page and then again click the switch button to change the current tenant context:

In this dialog, clear the Name field and then Save the dialog to switch back to the host side. Then you can use the standard admin user name with 1q2w3E* password to login to the application as the host administrator.

Creating a New Tenant with a Separate Database

Finally, we came to the point that we will create a new tenant with a separate, dedicated database. Open the Tenants page of the SaaS module and click the + New tenant button:

Just fill these information as you wish, then open the Database connection strings tab:

Uncheck the Use the shared database option and set a connection string to the Default connection string for this tenant. I used Server=(LocalDb)\MSSQLLocalDB;Database=MtDemoApp_Volosoft;Trusted_Connection=True;TrustServerCertificate=true as the connection string value. The database name is MtDemoApp_Volosoft. You can Test the connection string to be sure that it is a valid connection string.

Once you click the Save button, the new tenant is created, a new database is created on the fly, all the database migrations are applied and the initial data seed is performed. You can open the SQL Server Management Studio to see the new database:

You can check the tables (e.g. AbpUsers) to see that only this new tenant's data is stored in this database. To test the application, switch to the Volosoft tenant (as like explained in the Sign in with the new Tenant section before), create a new role or user and check the database.

Migrating Existing Tenant Databases

In the previous section, we've seen that a tenant database is automatically created on runtime if you set a connection string for that tenant. Also, all the current migrations are automatically applied to the database, so it becomes up to date.

But what about existing tenant databases when a new migration is added to the application? Maybe you have a few tenants with their separate databases, or you may have thousands of tenants with separate databases. How will you apply database schema changes to all of these databases?

The startup template comes with a solution to this problem. There is a .DbMigrator console application in the solution that is responsible to apply schema (table and their fields) changes to all of the databases in the system (the main database and all the separate tenant databases). It also executes the data seeding if seed data is available. All you need to do is to execute this application on your production environment while deploying a new version of your application (of course, it is also very useful in the development environment). It checks and upgrades all the databases before the new version of your application is deployed.

Here is the console log screen when I run the .DbMigrator application on my development environment:

As you can see in the logs, it first migrates for the main (host) database, then migrates the tenant databases one by one. It doesn't make schema migration for the acme tenant since it has not a separate database, but uses the main database.

In brief, when you make changes on your entity classes;

1. Add a new migration for the main DbContext class as I explained in this article.
2. Add a new migration for the tenant DbContext class as I explained in this article.
3. Run the .DbMigrator application in your development environment to ensure all the databases are up to date.
4. When you deploy your application to production or test environments, remember to run the .DbMigrator application first, then update your application. Or better, setup a CI/CD pipeline that automates this process. You can run the .DbMigrator every time while deploying the application, regardless of whether there is a schema change or not.

If you have too many tenants with separate database, then the migration process may take too much time. .DbMigrator provides the fundamental solution. But for more advanced scenarios or bigger systems, you can always develop your own solution. Just check the .DbMigrator application to understand how it was implemented. All the necessary code located in your solution, so you can easily understand and freely customize.

Conclusion

In this article, I covered two important aspects of multi-tenant application development:

• How ABP startup templates provide a multi-tenant application setup, so some tenants may store their data in a single (main, shared) database while some others may have their own dedicated database.
• Demonstrate how it can manage database migration process on the fly for multiple databases.

I started by defining different database models for multi-tenant applications (Single database, separate databases, and hybrid), showed how to create an ABP application that supports hybrid model, explained the DbContext structure that is coming with the solution template, demonstrated how to define entities, create and apply database migrations in such an application.

I hope this article gives you a good understanding the problem and the solution provided by the ABP Framework. Please write your questions or comments under this article.

Enjoy coding! :)

Further Reading

• ABP Multi-Tenancy document
• Multi-Tenancy Architecture with .NET

Either you are building an e-commerce application or a simple blog, user comments (about your products or blog posts) can grow rapidly, making it harder for users to get the gist of discussions at a glance. AI is a pretty good tool to solve the problem. By using AI, you can summarize all the user comments and show a single paragraph to your users, so they can easily understand the overall thought of users about the product or the blog post.

In this tutorial, we’ll walk through a real-life implementation of using AI to summarize multiple user comments in an application. I will implement the solution based on ABP's CMS Kit library, as it already features a commenting system and a demo application that displays user comments on gallery images (it has not a comment summary feature yet, we will implement it in this tutorial).

A Screenshot

Here, an example screenshot from the application with the comment summary feature:

Cloning the Repository

If you want to follow the development, you can clone the CMS Kit Demo repository to your computer and make it running by following the instructions on the README file.

I suggest to you to play a little with the application (create a new user for yourself, add some comments to the images in the gallery), so you understand how it works.

Preparing the Solution for AI

I will use Microsoft AI Extensions Library to use the AI features. It is an abstraction library that can work with multiple AI models and tools. I will use an OpenAI model in the demo.

The first step is to add the Microsoft.Extensions.AI.OpenAI NuGet package to the project:

dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease

The Microsoft AI Extensions Library was in preview at the time when I wrote this article. If it has a stable release now, you can remove the --prerelease parameter for the preceding command.

We will store the OpenAI key and model name in user secrets. So, locate the root path of the CMS Kit project (src\CmsKitDemo folder) and execute the following commands in order in a command-line terminal:

dotnet user-secrets init
dotnet user-secrets set OpenAIKey <your-openai-key>
dotnet user-secrets set ModelName <your-openai-model-name>

For this example, you need to have an OpenAI API Key. That's all. Now, we are ready to use the AI.

Implementing the AI Summarization

Let's start from the most important point of this article: Comment summarization. I will create a class named AiCommentSummarizer to implement the summarization work. Here, the full content of that class:

using System.Text;
using Microsoft.Extensions.AI;
using OpenAI;
using Volo.Abp.DependencyInjection;

namespace CmsKitDemo.Utils;

public class AiCommentSummarizer : ITransientDependency
{
    private readonly IConfiguration _configuration;

    public AiCommentSummarizer(IConfiguration configuration)
    {
        _configuration = configuration;
    }
    
    public async Task<string> SummarizeAsync(string[] commentTexts)
    {
        // Get the model and key from the configuration
        var aiModel = _configuration["ModelName"];
        var apiKey = _configuration["OpenAIKey"];

        if (aiModel.IsNullOrEmpty() || apiKey.IsNullOrEmpty())
        {
            return "";
        }

        // Create the IChatClient
        var client = new OpenAIClient(apiKey)
            .GetChatClient(aiModel)
            .AsIChatClient();

        // Create a prompt (input for AI)
        var promptBuilder = new StringBuilder();

        promptBuilder.AppendLine(
            @"There are comments from different users of our website about an image.
We want to summarize the comments into a single comment.
Return a single comment with a maximum of 512 characters. Comments are separated by a newline character and given below."
        );
        promptBuilder.AppendLine();
        
        foreach (var commentText in commentTexts)
        {
            promptBuilder.AppendLine("User comment:");
            promptBuilder.AppendLine(commentText);
            promptBuilder.AppendLine();
        }
        
        // Submit the prompt and get the response
        var response = await client.GetResponseAsync(
            promptBuilder.ToString(),
            new ChatOptions { MaxOutputTokens = 1024 }
        );

        return response.Text;
    }
}

That class is pretty simple and already decorated with comments:

• First, we are getting the API Key and an OpenAI model name from user secrets. I used gpt-4.1 as the model name, but you can use another available model.
• Then we are obtaining an IChatClient reference for OpenAI. IChatClient interface is an abstraction that is provided by the Microsoft AI Extensions Library library, so we can implement rest of the code independently from OpenAI.
• Then we continue by building a proper prompt (input) for the AI operation.
• And finally we are using the AI to generate a response (the summary).

At this point, all the AI-related work has already been done. The rest of this article explains how to integrate that summarization feature with the CMS Kit Demo application.

Adding a CommentsSummary Property to the GalleryImage Entity

The GalleryImage entity is used to represent an image on the image gallery. I add a CommentsSummary property to that entity:

public class GalleryImage : CreationAuditedAggregateRoot<Guid>
{
    public string Description { get; set; }

    public Guid CoverImageMediaId { get; set; }
    
    public string CommentsSummary { get; set; } // The new property is here

    //...
}

Since the CMS Kit Demo application uses Entity Framework Core, I need to add a new database schema migration and update the database:

dotnet ef migrations add Added_Summary_To_GalleryImage
dotnet ef database update

Updating the Summary

Great, we have a GalleryImage.CommentsSummary property now. But, how will it be updated when a users adds or removes a comment for an image? To implement that;

• We will listen all the change events for user comments (when a user adds, removes or updates a comment).
• Whenever a comment is changed, we will find the related gallery image, retrieve all the user comments for this image, use the AiCommentSummarizer class to summarize all the comments.
• Finally, we wil set the GalleryImage.CommentsSummary property with the generated summary text.

Here, the implementation:

using CmsKitDemo.Entities;
using CmsKitDemo.Utils;
using Microsoft.EntityFrameworkCore;
using Volo.Abp.DependencyInjection;
using Volo.Abp.Domain.Entities.Events;
using Volo.Abp.Domain.Repositories;
using Volo.Abp.EventBus;
using Volo.CmsKit.Comments;

namespace CmsKitDemo.EventHandlers;

public class GalleryImageCommentListener : 
             ILocalEventHandler<EntityChangedEventData<Comment>>,
             ITransientDependency
{
    private readonly IRepository<GalleryImage, Guid> _galleryImageRepository;
    private readonly IRepository<Comment, Guid> _commentRepository;
    private readonly AiCommentSummarizer _aiCommentSummarizer;

    public GalleryImageCommentListener(
        IRepository<GalleryImage, Guid> galleryImageRepository,
        IRepository<Comment, Guid> commentRepository,
        AiCommentSummarizer aiCommentSummarizer)
    {
        _galleryImageRepository = galleryImageRepository;
        _commentRepository = commentRepository;
        _aiCommentSummarizer = aiCommentSummarizer;
    }
    
    public async Task HandleEventAsync(EntityChangedEventData<Comment> eventData)
    {
        var comment = eventData.Entity;
        
        //Here, we only interest in comments related to image gallery items
        if (comment.EntityType != CmsKitDemoConsts.ImageGalleryEntityType)
        {
            return;
        }

        if (!Guid.TryParse(comment.EntityId, out var galleryImageId))
        {
            return;
        }
        
        // Get the related image from database
        var galleryImage = await _galleryImageRepository.FindAsync(galleryImageId);
        if (galleryImage == null)
        {
            return;
        }
        
        // Get all the comments related to the image
        var queryable = await _commentRepository.GetQueryableAsync();
        var allCommentTexts = await queryable
            .Where(c => c.EntityType == CmsKitDemoConsts.ImageGalleryEntityType &&
                        c.EntityId == comment.EntityId)
            .Select(c => c.Text)
            .ToArrayAsync();

        // Update the summary of comments related to the image
        if (allCommentTexts.Length <= 0)
        {
            galleryImage.CommentsSummary = "";
        }
        else
        {
            galleryImage.CommentsSummary =
                await _aiCommentSummarizer.SummarizeAsync(allCommentTexts);
        }

        // Update the image in database
        await _galleryImageRepository.UpdateAsync(galleryImage);
    }
}

Let's explain that class:

• GalleryImageCommentListener implements the ILocalEventHandler<EntityChangedEventData<Comment>> interface. In this way, it can handle an event whenever a Comment entity is changed (created, updated or deleted). We are using ABP's local event bus and its pre-defined events.
• HandleEventAsync is called by the ABP Framework whenever a new Comment is created, or an existing Comment is deleted or updated.
• ABP's Comment entity is reusable and it can be associated with any kind of objects (blog posts, images, etc). So, first we are checking if this comment is related to an image gallery item.
• Then we are getting the related GalleryImage entity from the database.
• And getting all comments (including the new one) from the database for this image.
• Finally, using the AiCommentSummarizer class to generate the summary and set the CommentsSummary property.

Show the Summary Card on the UI

Everything is ready on the backend. Now, we can show the summary text on the user interface. To do, that, I added CommentsSummary property also to the GalleryImageDto class and used it on the /Pages/Gallery/Detail.cshtml view:

@if (!Model.Image.CommentsSummary.IsNullOrEmpty())
{
    <div class="card mt-3">
        <div class="card-body">
            <h6 class="card-title">Summary of the User Comments</h6>
            <p class="mb-auto">@Model.Image.CommentsSummary</p>
        </div>
    </div>
}

That section renders the following card on the user interface:

Conclusion

In this article, I demonstrated how to use Microsoft AI Extensions Library to work with OpenAI for summarization of multiple user comments. I reused the ABP's CMS Kit Demo application to show it in a more real world example.

Source Code

• Source code of the CMS Kit Demo application
• All the changes made for this article (as a pull request)

In this article, I will compare Aspire by ABP Studio by explaining their similarities and differences.

Introduction

While Aspire and ABP Studio are tools for different purpose with different scope and they have different approaches to solve the problems, many developers still may confuse since they also have some similar functionalities and solves some common problems.

In this article, I will clarify all, and you will have a clear understanding of what are the similarities and differences of them. Let's start by briefly define what are Aspire and ABP Studio.

What is Aspire?

Aspire is a cloud-ready framework designed to simplify building distributed, observable, and production-ready applications. It provides a set of opinionated tools and NuGet packages tailored for cloud-native concerns like orchestration, service integration (e.g., Redis, PostgreSQL), and telemetry. Aspire focuses on the local development experience, making it easier to manage complex, multi-service apps by abstracting away configuration details.

Here, a screenshot from Aspire dashboard that is used for application monitoring and inspection:

What is ABP Studio?

ABP Studio is a cross-platform desktop application designed to simplify development on the ABP Framework by automating various tasks and offering a streamlined, integrated development environment. It allows developers to build, run, test, monitor, and deploy applications more efficiently. With features like Kubernetes integration and support for complex multi-application systems, ABP Studio enhances productivity, especially in microservice or modular monolith architectures.

Here, a screenshot from the ABP Studio Solution Runner panel that is used to run, browse, monitor and inspect applications:

A Brief Comparison

Before deep diving details, I want to show a table of features to compare ABP Studio and Aspire side by side:

Comparing the Features

In the next sections, I will go through each feature and explain differences and similarities.

Integration Packages

ABP Framework has tens of integration packages to 3rd-party libraries and services. Aspire also has some library integrations. But these integrations have different purposes:

• ABP Framework's integrations (like MongoDB, RabbitMQ, Dapr, etc) are integrations for its abstractions and aimed to be used directly by your application code. They are complete and sophisticated integrations with the ABP Framework and your codebase.
• Aspire's integrations (like MongoDB, RabbitMQ, Dapr, etc), on the other hand, for simplifying configuration, service discovery, orchestration and monitoring of these tools within Aspire host. Basically, these are mostly for integrating to Aspire, not for integrating to your application.

For example, ABP's MongoDB integration allows you to use MongoDB over repository services, automatically handles database transactions, audit logs, event publishing on data saves, dynamic connection string management, multi-tenancy integration and so on.

On the other hand, Aspire's MongoDB integration basically adds MongoDB driver library to your Aspire host application and configures it so you can discover MongoDB server on runtime, use a MongoDB Docker container and see its health status, logs and traces on Aspire dashboard.

Starter Templates

Both of ABP Studio and Aspire provide startup solution templates for new applications. However, there are huge differences between these startup solution templates and their purpose are completely different.

• ABP Studio provides production-ready and advanced solution templates for layered, modular or microservice solution development. They are well configured for local development and deploying to Kubernetes and other production environments. They provide different UI and database options, many optional modules and configuration. For example, you can check the microservice solution template to see how sophisticated it is.
• Aspire's project templates' main purpose is to provide a minimal application structure that is pre-integrated to Aspire libraries and configured for local development environment.

So, when you start with Aspire project template, you will need to deal with a lot of work to make your solution production and enterprise ready. On the other hand, ABP Studio's solution templates are ready to launch your system from the first day and they provide you a perfect starting point for your new business idea.

Monitoring & Application Running

Monitoring applications and services is an important requirement for building complex distributed systems. Both of ABP Studio and Aspire provide excellent tools for that purpose.

• ABP Studio's Solution Runner panel provides a powerful UI to run and monitor applications and services. You can see all HTTP requests, distributed events, exceptions and detailed application logs, trace and find problems in your system. You can use its fully functional built-in browser to navigate application UIs easily. You can also create multiple profiles to group and configure the applications for different teams.
• Aspire's dashboard can be used to see the states of the running applications and containers, explore their console output, logs, traces and metrics to understand what is happing in your distributed system.

Both tools are pretty useful for monitoring. In addition to monitoring, ABP Studio offers an advanced UI to control the running applications, build, start and stop individually or by a group of applications.

Architecting / Building Solutions

One of the unique features of ABP Studio is that it is an architectural tool that helps you create the structure and architecture of your solution. You can create any kind of application, from single-layer simple web applications to layered multi-application solutions, from monolith modular to microservice systems. In the next section, I will briefly explains these architectural features.

Building Modular Monolith Solutions

With ABP Studio, you can create a new solution, create modules and establish relations (dependencies) between modules to architect your overall modular monolith system easily.

Here, a screenshot where we are adding an existing package reference to the Products module of a modular CRM solution:

You can see the Modular Application Development tutorial to learn how to build such an application step by step.

Building Microservice Solutions

ABP Studio provides a full featured microservice startup solution template and the fundamental tooling to build large-scale microservice systems.

Here a screenshot that shows how to add new microservices, API gateways or web applications to a microservice solution:

Aspire has no such a feature and has no such a plan to provide that kind of architectural solution building experience.

Kubernetes Integration

Another great ABP Studio feature is Kubernetes Integration. It allows you to develop your distributed / microservice solutions as integrated to Kubernetes.

Here, a few tasks you can accomplish using ABP Studio's Kubernetes integration:

• Build docker images of your applications and services
• Install and uninstall Helm charts to your Kubernetes cluster
• Connect to internal services of your Kubernetes cluster
• Monitor services and applications that are running in your Kubernetes cluster
• Intercept traffic of a service and redirect requests to your local machine. In that way, you can develop, test and run individual services or applications in your local computer that is fully integrated to other services and applications running in Kubernetes.

ABP Studio's Kubernetes Integration makes microservice development so easy and comfortable. On the other hand, Aspire has no such a Kubernetes integrated development experience.

The ABP Platform

Until now, I directly compared ABP Studio and Aspire features. Aspire is directly built on .NET and ASP.NET Core. However, ABP Studio is not a standalone tool that is built on .NET and ASP.NET Core. It is built on the ABP Platform (which is built on .NET and ASP.NET Core).

The following diagram shows ABP Platform components at a glance:

So, when you use ABP Studio, you also take full power of the open source ABP Framework and other ABP Platform features.

ABP and Aspire Integration

I have a good news to you. It is actually possible and pretty easy to make ABP Platform and Aspire working together.

You can check @berkansasmaz's great article: How to use Aspire with ABP framework.

Licensing

ABP Studio has a Community Edition which is completely free and available to everyone. It includes many of the features I mentioned here. There is also a commercial edition that is included in commercial ABP licenses. You can check that blog post which clearly explains the license differences and introduces the fundamental ABP Studio features.

On the other hand, Aspire is a free tool developed and published by Microsoft. It has no commercial version.

Conclusion

Both Aspire and ABP Studio serve distinct purposes, catering to different types of development environments. While Aspire excels in simplifying cloud-native application setups and observability, ABP Studio provides a comprehensive framework for modular monoliths and microservice architectures with full-fledged enterprise level production-ready startup solution templates and integrated tools.

In the previous section, it was mentioned that it is possible to use them together. You don't have to select one of them. However, in my opinion, when you use ABP Studio, you won't need Aspire since ABP Studio can do everything and much more. If you have budget, I suggest to purchase a commercial ABP Studio license so you can fully unlock its power.

Resources / Further Reading

• ABP Studio documentation
• Aspire documentation
• How to use Aspire with ABP framework

We'd already provided tools like ABP CLI and ABP Suite for these kind of purposes before. ABP Studio takes this one long step further and offers a tool that you can use continuously throughout your coding activities, help you for non-coding activities to make you focus on your software development.

I am very excited to announce that the ABP Studio (beta) is generally available to everyone. It is now downloadable on the get started page of the new ABP Platform website.

What is ABP Studio?

ABP Studio is a cross-platform desktop application for ABP and .NET developers. It aims to provide a comfortable development environment for you by automating things, providing insights about your solution, making develop, run, browse, monitor, trace and deploy your solutions much easier.

From now on, ABP Studio is the default way to start with the ABP Platform;

• The get started page has updated so it offers to download ABP Studio to create a new ABP based solution.

• The ABP CLI (Volo.Abp.Cli) is replaced by the ABP Studio CLI (Volo.Abp.Studio.Cli). The new ABP Studio CLI is compatible with the old one, and extends it by introducing new commands.

• Startup solution templates are completely renewed. The solution structures are similar to the old ones, but they are totally new templates built with the new templating engine.

• All the documentation and tutorials now uses ABP Studio and ABP Studio CLI.

ABP Studio is in beta stage now. It is also in rapid development and release cycle. We frequently release new feature and patch versions. Please file an issue if you have any problem.

If you want to continue to use the old CLI and old startup templates, please refer that document.

The Easiest Way to Start with ABP

As mentioned before, the startup solution templates are completely renewed with ABP Studio. They provide much more options compared to the old startup templates. The following screenshot is taken from the New Solution wizard of ABP Studio, which provides an comfortable and easy way to create new solutions:

For example, you can now select most of the non-fundamental modules as optional while creating a new solution:

Developing Microservices Solutions is Now Much Easier

The most important change is made on the microservice startup template (which is available only for Business or higher license holders). We've designed the solution structure, integrations, Kubernetes/Helm configuration, database migrations and all others from scratch and well documented all the decisions we've applied. Developing microservice solutions with ABP is now easier and more understandable than ever.

Architecting Your Complex Solutions

One of the main purposes to build ABP Studio was to simplify to create multi-modular and distributed systems. Either you create a modular monolith application or a microservice solution, ABP Studio's solution explorer provides a convenient way to design your high-level solution structure.

You see a microservice solution in the following screenshot:

That ABP Studio solution contains multiple separate .NET solutions (.sln) each has multiple .NET projects (.csproj). ABP Studio allows you to easily manage such a multi-solution system on a single view. You can create new packages and modules, import existing packages and modules, manage their dependencies and so on.

Run and Test Your Multi-Application Solutions with a Single Click

One of the biggest shortcomings we face when developing distributed or complex solutions is being able to easily run all components of the solutions so that we can test and debug a single service or application without caring about all the runtime dependencies.

Here a screenshot from the ABP Studio's Solution Runner view:

When you use ABP Studio, it is dramatically easier to run, monitor, test, debug and develop your applications and services. You can browse your web UI applications, monitor all the HTTP requests, distributed events, exceptions and logs in real time on a single screen. In this way, you can easily run all the systems and trace the problems when you have.

All you need to click the Play button or right-click and select the Run -> Start All command:

The nice thing is that you can create multiple profiles for each of your teams so that they can run only the applications they need to develop the application they are working on.

Seamlessly Develop Your Service as Integrated to Kubernetes

Kubernetes is the de-facto tool to deploy, run and scale complex systems. However, it can also be a great tool to develop such solutions in a local environment.

With ABP Studio's Kubernetes Integration system, it is now possible to deploy and run a complex system in a Kubernetes cluster. Then you can establish a bridge between your local development environment and the Kubernetes cluster. In this way, you can develop, run, test and debug an application or service in your local development environment as it is running in the Kubernetes cluster. All incoming and outgoing traffic is properly routed and managed by ABP Studio. You just focus on the service you are responsible to develop and let the Kubernetes run rest of the system for you.

You can see all the Helm charts in a solution in the Kubernetes panel of ABP Studio:

Here, you can easily build, install and uninstall the Helm charts to your Kubernetes cluster. In the Kubernetes tab, you can connect to the Kubernetes cluster and intercept a service to develop it locally. See the documentation for more information.

The good news is that all the monitoring data (HTTP Requests, Events, Exceptions, Logs,...) is still visible in real time with the Kubernetes integration too.

Use the ABP Suite as Integrated to ABP Studio

ABP Suite is a tool that is basically used to generate code for ABP Solutions. It has started by creating simple CRUD pages, and now it does much more. It can establish relations with existing entities, create complex user interfaces like parent/child tables and so on...

ABP Suite can be used directly inside ABP Studio by clicking the ABP Suite -> Open command:

This will open ABP Suite in a new tab for the current solution and focus on the CRUD page generation:

The new ABP Studio solution templates and ABP Suite code generation are compatible with each other. Here a screenshot from the generated CRUD UI for a very simple Book entity:

The Community Edition vs Commercial Licenses

ABP Studio has a Community Edition which is completely free and available to everyone. As you can guess, there are come differences between the community edition and commercial editions. ABP Platform has 4 fundamental license types;

• Open source (free)

• Team

• Business

• Enterprise

Here, the comparison table for ABP Studio features for these license types:

Microservice startup template and Kubernetes integration features are available only for commercial licenses since these are considered more enterprise requirements. Also, the solution size is limited with the ABP Community edition. If you are building a large or distributed solution, consider to purchase a commercial license.

Conclusion

I've introduced the ABP Studio General Availability with this post. It is still in the beta stage. You can expect frequent releases during the beta phase. We will add new features and fix issues quickly. Please download and use it now. If you find any problem, do not hesitate to open an issue on GitHub.

• We are merging the subdomains of the ABP.IO Platform websites: Community.abp.io, commercial.abp.io, blog.abp.io, docs.abp.io websites and their contents are being merged into the main domain, abp.io.

• ABP (open source) and ABP Commercial documents are being merged into a single documentation.

• Introducing ABP Studio Community Edition.

These changes won't effect the license conditions. The open source part will remain the same and the commercial license contents will also be the same. The aim of the changes is to make the platform more consistent, holistic, understandable and easy to start.

Let's dive deep...

Merging the ABP.IO Websites

ABP.IO website has many subdomains currently:

• abp.io: Home page of the open source ABP Framework project.

• community.abp.io: A website that community can share contents and we organize events.

• commercial.abp.io: A website to promote and sell commercial ABP licenses which have pre-built modules, themes, tooling and support on top of the ABP Framework.

• docs.abp.io: The technical documentation of the ABP Framework and ABP Commercial.

• blog.abp.io: A blog website to announce the news on the platform.

• support.abp.io: Premium support for the ABP Commercial customers.

All these subdomains (except the support website for now) are being merged to the abp.io domain. All their contents and UI designs are being revised and enriched.

Some fundamental purposes of that change are;

• Making content more coherent and holistic,

• Making the design more harmonious,

• Making the contents of the old subdomains more visible and reachable,

• Allow you to navigate through the web pages much easier,

• Reducing duplications between different websites,

I will highlight a few important changes in the next sections.

The New Mega Menu

As I said above, the abp.io UI design is also being revised. One of the big revisions is the main menu. We are replacing the current main navigation by a mega menu as shown in the following figure:

We believe that new mega menu will allow you to navigate through the web pages much easier.

The New Get Started Page

We are constantly working to improve ABP's onboarding experience. With the new platform changes, we now offer ABP Studio as the starting point for the ABP Platform. You can still use the ABP CLI to created new ABP solutions, but the new ABP Studio makes it much easier and understandable. It also provides features to easily run and monitor your applications, even in the Community edition.

You can easily download and install ABP Studio, login with your abp.io account and create your first ABP solution.

The New Pricing Page

Since the ABP Commercial website has merged with the main website, you will see the Pricing page located on the main menu of the abp.io website. We have completely revised the design and content of this page to better reflect which features are open source and free, and what is included in the paid licenses.

As mentioned above, all the free & open source features are still free & open source. In addition, we included the ABP Studio Community edition (will be explained below) to the free license.

Merging the ABP Platform Documentation

Currently, ABP Framework (open source) and ABP Commercial documents are completely separated. You can switch between them on the left side:

Based on our and customers' experiences, there are some problems with that approach:

• Getting started, development tutorials, release notes, road map and some other documents are duplicated (or very similar) among ABP Framework and ABP Commercial documents.

• For ABP Commercial users, it is not clear if they also need to read the ABP Framework (open source) documentation or not. Also, when they read the framework document, some parts are different for ABP Commercial users, and it is also not clear in some cases.

We are currently working to completely merge the ABP Framework (open source) and ABP Commercial documentation, remove duplications and revisit the contents. We will clearly indicate if a part of a document requires a paid license.

The left navigation panel tree is also completely revisited and simplified:

The ABP Studio Community Edition

ABP Studio is a cross-platform desktop application designed for ABP and .NET developers. It aims to provide a comfortable development environment by automating tasks, providing insights about your solution, and simplifying the processes of creation, development, execution, browsing, monitoring, tracing, and deploying your solutions.

Here, a screenshot from the Solution Runner screen of ABP Studio:

ABP Studio has been started as a commercial product, as a part of ABP Commercial. We are very excited to announce that the Community Edition will be available soon for free. It will have some missing features and limitations compared to the full edition, but will be enough to create, explore and run ABP solutions easily.

We will be offering ABP Studio as a starting point to the ABP platform. The Getting Started and other documents will use ABP Studio to create new solutions and perform ABP-related operations.

Other News

We are also working on some other topics related to these changes. Some of them are;

• Completely renewing the startup templates (with ABP Studio), so they will be more flexible and will provide more options.

• Providing a tool to automatically convert ABP solutions created with open source startup templates into ABP commercial.

Questions

I tried to explain all the important changes in this post. However, you may have some questions in your mind.

What should open source users expect?

Since the ABP Commercial website content is merged with the main abp.io website, you will see paid features being introduced on the main website. The pricing page will also be available on the same website. This may lead you to wonder whether the ABP Platform is a fully paid product. The simple answer to this question is "No". Actually, nothing has changed on the open source side. Everything will be the same. Additionally, open source users will now have ABP Studio Community Edition for free. So open source has more for its users than before.

What should ABP Commercial customers expect?

ABP Commercial license holders may wonder if any license change happens. The answer is "No". All the license types, rules, restrictions and features are the same. With the changes explained in this post, you will follow the documentation easier (since you won't need to go to another website for the framework documentation) and you will better understand what special features are available to you.

Last Words

With this post, we wanted to announce the changes to be made on the ABP platform to the ABP community, so don't be surprised or curious about what happened. If you have any questions or suggestions, feel free to write a comment for this blog post or send an email to info@abp.io.

Entity Framework Core 8.0 is being shipped in a week as a part of .NET 8.0. In this article, I will introduce the new Complex Types feature of EF Core 8 and show some examples of how you can use it in your projects built with ABP Framework.

What is a Value Object?

A Value Object is a simple object that has no conceptual identity (Id). Instead, a Value Object is identified by its properties.

A Value Object is typically owned by a parent Entity object. Using Complex Types with EF Core 8 is the best way to create Value Objects that are stored as a part of your main entity.

Creating an ABP Project

WARNING: ABP Framework has not a .NET 8.0 compatible version yet. It is planned to be released on November 15, 2023. I created this project with ABP 7.4.1 (based on .NET 7.0), then manually changed the TargetFramework (in the csproj) to net8.0 and added the Microsoft.EntityFrameworkCore.SqlServer package with version 8.0.0-rc.2.23480.1. After that, the project is being compiled, but some parts of this article may not work as expected until ABP Framework 8.0-RC.1 is released.

I will update the article once ABP Framework 8.0-RC.1 is released.

I will show code examples, so I am creating a new ABP project using the following ABP CLI command:

abp new ComplexTypeDemo -t app-nolayers

I prefer a non-layered project to keep the things simple. If you are new to ABP Framework, follow the Getting Started tutorial to learn how to create a new project from scratch.

Once I created the solution, I am running the following command to execute the database migrations in order to create the initial database:

dotnet run --project ComplexTypeDemo --migrate-database

We could also execute the migrate-database.ps1 (that is coming as a part of the solution) as a shortcut.

Creating a Complex Type

Assume that we have a Customer entity as shown below:

public class Customer : BasicAggregateRoot<Guid>
{
    public string Name { get; set; }
    public Address HomeAddress { get; set; }
    public Address BusinessAddress { get; set; }
}

Here, we have two address properties, one for home and the other one for business. Since an address is a multi-values property, we can define it as a separate object:

public class Address
{
    public string City { get; set; }
    public string Line1 { get; set; }
    public string? Line2 { get; set; }
    public string PostCode { get; set; }
}

Address is a typical complex object. It is actually a part of the Customer object, but we wanted to collect its parts into a dedicated class to make it a domain concept and easily manage its properties together.

Configure EF Core Mappings

We should set the Address class as a Complex Type in our EF Core mapping configuration. There are two ways of it.

As the first way, we can add the ComplexType attribute on top of the Address class:

[ComplexType] // Added this line
public class Address
{
    ...
}

As an alternative, we can configure the mapping using the fluent mapping API. You can write the following code into the OnModelCreating method of your DbContext class:

builder.Entity<Customer>(b =>
{
    b.ToTable("Customers");
    b.ComplexProperty(x => x.HomeAddress);     // Mapping a Complex Type
    b.ComplexProperty(x => x.BusinessAddress); // Mapping another Complex Type
    //... configure other properties
});

You can further configure the properties of the Address class:

b.ComplexProperty(x => x.HomeAddress, a =>
{
    a.Property(x => x.City).HasMaxLength(50).IsRequired();
});

Once you configure the mappings, you can use the EF Core command-line tool to create a database migration:

dotnet ef migrations add "Added_Customer_And_Address"

And update the database:

dotnet ef database update

If you check the fields of the Customers table in your database, you will see the following fields:

• Id
• Name
• HomeAddress_City
• HomeAddress_Line1
• HomeAddress_Line2
• HomeAddress_PostCode
• BusinessAddress_City
• BusinessAddress_Line1
• BusinessAddress_Line2
• BusinessAddress_PostCode

As you see, EF Core stores the Address properties as a part of your main entity.

Querying Objects

You can query entities from database using the properties of a complex type as same as you query by the properties of the main entity.

Example: Find customers by BusinessAddress.PostCode:

public class MyService : ITransientDependency
{
    private readonly IRepository<Customer, Guid> _customerRepository;

    public MyService(IRepository<Customer, Guid> customerRepository)
    {
        _customerRepository = customerRepository;
    }

    public async Task DemoAsync()
    {
        var customers = await _customerRepository.GetListAsync(
            c => c.BusinessAddress.PostCode == "12345"
        );
        
        //...
    }
}

Mutable vs Immutable

Entity Framework Core Complex Types can work with mutable and immutable types. In the Address example above, I've shown a simple mutable class - that means you can change an individual property of an Address object after creating it (or after querying from database). However, designing Value Objects as immutable is a highly common approach.

For example, you can use C#'s struct type to define an immutable Address type:

public readonly struct Address(string line1, string? line2, string city, string postCode)
{
    public string City { get; } = city;
    public string Line1 { get; } = line1;
    public string? Line2 { get; } = line2;
    public string PostCode { get; } = postCode;
}

See the Microsoft's documentation for more examples and different usages.

Final Notes

There are more details about using Complex Types in your applications. I want to mention some of them here:

• You can have nested complex types. For example, Address may have one or more PhoneNumber objects as its properties. Everything will work seamlessly.
• A single instance of a Complex Type can be set to multiple properties (of the same or different entities). In that case, changing the Complex object's properties will affect all of the properties. However, try to avoid that since it may create unnecessary complexities in your code that is hard to understand.
• You can manipulate mutable complex object properties just as another property in your entity. EF Core change tracking system will track them as you expect.
• Currently, EF Core doesn't support to have a collection of complex objects in an entity. It works only for properties.

For more details and examples, see the Microsoft's document in the References section.

Source Code

You can find the sample project here:

https://github.com/hikalkan/samples/tree/master/EfCoreComplexTypeDemo

References

• Value objects using Complex Types in What's new with EF Core 8.0 document by Microsoft.
• ABP Entity Framework Core integration document

Throughout the day, the conference provided an excellent platform for networking, learning, and knowledge sharing within the .NET community. The quality and depth of the specialist presentations by the 20 specialist speakers were truly remarkable. From discussions of cutting-edge .NET Core features to software architecture, cloud-based software, and DevOps, each session inspired and informed attendees. Volosoft’s Co-Founder and lead architect of ABP Framework, Halil Ibrahim Kalkan was one of those talented speakers within the agenda. His captivating talk on "Dealing with Concurrency and Multi - Threading in .NET " was well received by the audience.

View this post on Instagram

A post shared by Volosoft (@volosoftcompany)

Our booth in the main hall was full of excitement as we had the chance to meet and chat with the community face-to-face. We were excited to present ABP Platform to the attendees with live demos and interactive visual demonstrations, showcase new features, and share updated documentations. It is always brilliant to meet with the community and get to know them better in person. For this event, the commitment and enthusiasm of the conference participants made the experience even more rewarding for us.

We also want to give a special thank you to everyone who visited our booth and engaged in meaningful conversations. Your curiosity and passion for .NET was truly inspiring. We hope that our interactions during the event created new contacts and opened doors to exciting collaborations and opportunities. Finally, we would like to express our appreciation for the gifts and raffles that we had the privilege of providing. The surprise gifts and fun items were a small token of our gratitude and appreciation for your support and participation. We hope you enjoy your treats and that they remind us of the wonderful times we all had at the conference.

We draw the raffle ‼️ And the winner is @umitgnr 🎁 #dotnetkonf23
pic.twitter.com/PEuXwjhL6Q

— Volosoft (@volosoftcompany) June 1, 2023

We would like to invite everyone to revisit some memorable moments from the Devnot Dotnet 2023 conference by exploring images:

We would like to once again express our sincere thanks to the entire Devnot Team for organizing such a great conference. Your dedication, attention to detail, and commitment to driving growth and innovation within the .NET community is truly commendable.

To all attendees, speakers and sponsors, thank you for making the Devnot Dotnet Conference 2023 a truly unforgettable experience. We are honored to be a part of this vibrant community and look forward to future events that will no doubt continue to push the boundaries of .NET development.

Until we meet again!

Abstract

Microservice architecture is a quite common approach to build highly scalable solutions with a large development team. While there are standard tools, like Kubernetes, to deploy, run and scale your microservices, the development side is not as mature as that. It is not easy to develop, run and test a single microservice that depends on other microservices and services. Running a copy of the entire system in the developer's machine is impractical.

In this article, I will introduce an efficient way of creating a development environment that is well integrated to Kubernetes. In this way, you can just run the microservice you are building and let Kubernetes run all your dependencies in your local machine or a remote server.

I will demonstrate the solution by introducing and using a brand new tool for ABP Developers: ABP Studio!

This article is based on my Kubernetes Integrated Microservice Development with ABP Studio talk performed in ABP Dotnet Conf'23. You can watch that talk if you would like watching rather than reading.

Topics

Let’s start by introducing the main topics I will cover in this article:

• I will begin by defining the problem: Why it is hard to prepare a development environment for a microservice development.
• I will mention and demonstrate how Microsoft’s Tye project tries to solve the problem and why it falls short.
• Then I will introduce the ABP Studio, a brand new product for .NET developers, which has an efficient solution for running multi-application solutions locally.
• Finally, I will offer an efficient way of developing such complex solutions locally by integrating Kubernetes into our development environment, and demonstrate how ABP Studio automates it for us.

Difficulties of a Microservice Development Environment

It is important to understand what is the essential problem when we try to set up a development environment for a microservice solution. To understand the main difficulty, let’s see what a microservice solution looks like:

A typical microservice solution consists of many components communicating to each other. In this example;

• We have two applications for users. One for back-office admin users and one for the end-users of the system, a public website.
• These applications use dedicated API Gateways since we are using the Backend For Frontend pattern here.
• There is a separate authentication service application to login and manage user accounts.
• Behind the API gateways, we typically have many API applications, called microservices. Here, I show only three microservices, but there will be tens of microservices even in a medium-size system. Each of these microservices may have their own databases.
• The microservices typically interact with each other using REST API calls or asynchronous messaging through an event bus service, like RabbitMQ here.

There will be much more supporting services, like Redis, Elasticsearch and so on. As you see, we have a lot of independent services and applications interacting with each other in a typical microservice solution.

How to run a single service locally?

Generally, your responsibility is developing one or a few of these microservices or applications, not all of them. For example, you may be responsible for developing or testing the Product microservice:

All you want to do is to write your code, then run and test your service if it is correctly working. However, to be able to develop, run, test or debug the product microservice, all of the service and infrastructure dependencies need to be running and communicating to each other.

Okay, maybe not all, but most of them are needed. Otherwise, you can not open the application UI, login to the system, add products to basket and place an order to see if it is working properly, or you can not live debug your service code in case of trouble.

So, how to make the whole system up and running easily to be able to focus on developing, testing and debugging the Product microservice?

The Project Tye

You are not the only one getting trouble to develop, run, test and debug a microservice solution. Microsoft also thought of it and introduced a tool called the Project Tye. With its own words in their GitHub repository:

Tye is a tool that makes developing, testing, and deploying microservices and distributed applications easier.

Tye can simplify microservices development by making it easy to run many services with one command, use dependencies in containers, discover addresses of other services using simple conventions. It can also deploy .NET applications to Kubernetes by automatically creating containers for .NET applications and generating Kubernetes manifests with minimal knowledge or configuration.

The deployment part is not mature and they have to do a lot of work. However, the solution runner part works very well.

Tye project consists of three major components:

• A YAML file to configure your services
• A CLI tool to run and deploy the solution
• And a dashboard to visualize the running services.

The tye.yaml file

Tye uses a YAML file to configure your solution. It typically contains many service definitions. There are three type of services can be defined in this YAML file:

• You can add a .NET Project, so Tye runs it locally with dotnet run
• You can add a container definition, and Tye runs it using Docker
• And an arbitrary executable application that can be run using a terminal command

Here, an example content of a tye.yaml file:

The Tye CLI

Once you define your YAML file, Tye can run all the services with a single terminal command: tye run. It builds all .NET applications before running them. If you specify the watch parameter, it watches the changes in your .NET projects, re-builds and runs them when a change happens. There are also other commands to build and deploy your solution.

The Tye Dashboard

The final major component is the Tye Dashboard. With this dashboard, you can see the list of the services with their statuses. You can also view their logs and open their UI with a single click.

A screenshot from the Tye Dashboard:

The Example Microservice Solution

I’ve prepared a microservice solution for demos in this article and I will use the same solution in all demos. Here, an overall diagram of the example solution:

We have two web applications, two API Gateways, 5 microservices. 3 of them are shown here: Product, Ordering and Identity microservices. Every microservice has its independent SQL Server database. They communicate through REST API calls and distributed events via RabbitMQ.

The Project Tye Demo

You can watch my 6-minutes demo to see the Project Tye in action:

Click here to watch the demo on YouTube

Tye: Shortcomings

The demo shows how the Tye project is useful. However, there are many missing points and problems with the current project state. Let’s talk about them;

• The first problem is that it starts very slow, because every time you run it, it builds all the services. It takes more than 1 minute for a solution with only ten services.
• It currently can run everything in your local computer. Even if you want to develop a single service, running tens of services locally consumes your system resources. You need a lot of RAM and CPU if you want to work a large solution locally.
• The UI part is currently very simple. For example, if you want to debug one of your services by running it in Visual Studio, you need to stop all the services, change the YAML file to exclude that service from Tye, then run all the services again. Only after that you can run your service in Visual Studio to debug it as integrated to other services. Obviously this process is not easy and comfortable.
• We can only see the application logs in the UI. More insights about the internals of services would be very helpful.
• Tye currently has some partial documents in its GitHub repository. However, the documentation is far away from being complete.
• Finally, and most importantly, there is no active development on the Tye project on GitHub. It was already an experimental project with its early state, as declared in its GitHub repository.

So, basically, it seems Microsoft has no further interest in this project and you can expect it will be retired in the near future.

ABP Studio

Okay, now we came to the ABP Studio part. At Volosoft, we were silently working on the ABP Studio project for more than one year.

ABP Studio is a cross-platform desktop application for ABP developers. It is well integrated to the ABP Framework and aims to provide a comfortable development environment for you by automating things, providing insights about your solution, making develop, run and deploy your solutions much easier.

We are planning to release a beta version in Q3 of 2023. You can expect the following features shipping with the initial release:

• You can create new ABP solutions and modules easily with a lot of options.
• You can easily install or uninstall modules to your solution.
• You can explore the fundamental structures of your solution or used modules, like entities, repositories, application services, UI pages, HTTP APIs, database tables and much more.
• You can build multi-module monolith applications or distributed microservice solutions by easily adding modules and services into your solution.
• You can easily run multiple applications and services with a single click, just like I demonstrated with the Project Tye. However, it has much more features.
• You can run your service by integrating it into a Kubernetes cluster, so you don’t need to run all your dependencies and all other services in your local development environment. This is the essential topic of this talk and I will later demonstrate how it works.

ABP Studio Solution Runner

I've prepared a demo of the ABP Studio Solution Runner, but first I want to mention the main features of the solution runner:

• First of all, it can run one, multiple or all services with a single click. In this way, it is very easy to stop a service, run it in Visual Studio to test or debug.
• All the services are connected to ABP Studio and send their internal data to visualize on the ABP Studio UI.
• In the overall view, you can see a list of services, view real-time HTTP Request and exception counts for each service.
• You can see all details of all HTTP requests coming to any service.
• You can see exception details as real-time in any service, easily filter and search.
• Just like Tye, you can see the application logs. But as more, you can filter logs by log level or search in the log texts.
• Last but not least, ABP Studio has an integrated Chrome browser inside it. You can browse the UI of your application without leaving the solution runner.

ABP Studio Solution Runner Demo

You can watch my 9-minutes demo to see ABP Studio Solution Runner in action:

Click here to watch the demo on YouTube

ABP Studio Kubernetes Tunnel

Finally, we came to the essential topic I want to talk about. Until that point, we had a good understanding of the problem and possible solutions. In this part, we will make a final touch to the solution to have a great development environment for a microservice solution.

ABP Studio Kubernetes Tunnel System allows you to connect your local development environment to a local or remote Kubernetes cluster, where that cluster already runs your microservice solution. In this way, you can access any service in Kubernetes with their service name as DNS, just like they are running in your local computer. This is established with a secure VPN connection.

Secondly, you can intercept any service in that cluster, so all the traffic to the intercepted service is automatically redirected to your service that is running in your local machine. When your service needs to use any service in Kubernetes, the traffic is redirected back to the cluster, just like your local service is running inside the Kubernetes. In this way, you don’t need to care about how all other services are configured and running. You just focus on the service you are responsible for developing, testing or debugging. You can use your favorite IDE since you are running your service in your local machine as you always do.

The solution runner is a great way of running multiple services locally. However, if your solution consists of hundreds of services, running all them in your local machine will consume your system resources and slow down your development speed. The best news is that: You can use the Kubernetes Tunnelling combined with all the solution runner features to have a perfect local microservice development environment.

How ABP Studio Kubernetes Tunnel works

I am sure that you want to see it in action, but before that, let me explain how the solution works.

• Kubernetes cluster is shown on the right side and your local development machine is shown on the left side.
• As you know, when a user requests a web page from your web application, the request is accepted by an Ingress Controller inside your Kubernetes cluster.
• The Ingress controller forwards the request to your web application, which then uses an API gateway to consume your microservices.
• Assume that we have the Product, Ordering and Identity microservices.
• These microservices have their own SQL Server database and they are also using RabbitMQ, Redis and some other infrastructure services.
• On the other hand, we want to develop, run or test our Product microservice in our own laptop using our favorite IDE, let’s say using Visual Studio.
• If we don’t make anything special, the product microservice in the Kubernetes cluster will be used by the users, as you can expect. Even if you can somehow run the product microservice in your local computer, the Kubernetes system won’t have any knowledge about it. They are in different systems.
• At this point, ABP Studio comes into play. When you connect to the Kubernetes cluster with ABP Studio, it first installs a VPN server into your cluster and a VPN client into your local machine.
• Then it establishes a secure VPN tunnel between your computer and the target Kubernetes cluster. In this way, you can access all services in Kubernetes with their internal cluster IP addresses.
• ABP Studio also installs the ABP Studio Client Proxy Server pod into the Kubernetes cluster, and the ABP Studio Proxy Client into the developer machine. It is used to collect data from the services and show them in the ABP Studio UI, like HTTP Requests, exceptions, or logs as we’ve seen in the solution runner before.
• Finally, ABP Studio also adds DNS records to your hosts file, so you can access to internal Kubernetes services directly with their service names, in addition to their IP addresses.

All of these happen when you click the Connect button on the ABP Studio. Now, your computer can use the internals of the Kubernetes cluster. But, how the HTTP Requests coming to the Product service in the Kubernetes cluster are redirected to your local machine?

• When you want to run and test a service locally, you intercept the matched service in the Kubernetes cluster. When you Intercept a service, ABP Studio makes some more changes in your local computer and in your Kubernetes cluster.
• As first, it installs a pod and a service into the Kubernetes cluster to intercept the requests coming to the Product microservice and proxies the requests to a client application in your local computer.
• The local client application then forwards requests to the Product microservice instance you are running in your local machine. In this way, whenever the Product service is used in Kubernetes, your local product service is executed. You can easily run, test or debug your service as you normally do with your standard IDE, for example with Visual Studio.
• What happens when your local product service needs to access the SQL Server database or RabbitMQ, or another microservice in the Kubernetes cluster? It can directly use them just like local services, through the VPN tunnel we have already created.
• ABP Studio makes a final change in your local product microservice project: It overrides all the environment variables with the ones obtained from the product service in the Kubernetes pod. In this way, your local product service instance feels itself in the Kubernetes cluster. Database connection strings and all other settings will be the same with the Kubernetes environment.

Don’t worry, ABP Studio doesn’t change your local environment variables. The change only affects the live product service instance, and it is reverted when you disable the interception in ABP Studio. Also, when you click the Disconnect button in ABP Studio, all the changes made to your cluster and your local computer will be cleared. It won’t leave any sign in your systems.

ABP Studio Kubernetes Tunnel Demo

So, now we have a fully Kubernetes integrated development environment. Let’s see how it is used in ABP Studio in the following 9-minutes demo:

Click here to watch the demo on YouTube

ABP Studio Roadmap

In the next months, the team will be working on the following items:

• Our first goal is to finalize and stabilize the current features. We will also document how to use them. Only after that, we will open it to customers as a beta version.
• We’ve focused on the development part until now. We also want to add some deployment capabilities to ABP Studio in the future.
• Another goal is to make module customizations much easier than current by the help of ABP Studio. With ABP Studio, we have completely re-though how to discover and install modules. Based on that, we will also work on a common place to publish and consume application modules for the ABP Framework.

We have other great plans for that product. However, I can not declare them yet as they are secrets for now :) We’ve planned to release the first beta version in Q3 of 2023.

I want to notice that ABP Studio is not a new version or replacement of ABP Suite. We built the ABP Studio from scratch. Both products will be developed and shipped in parallel. ABP Suite will continue to focus on code generation. ABP Studio doesn’t have any code generation capabilities yet. So, you will use both of them together.

Summary

Okay let’s summarize what I’ve explained in this article:

• First, I explained why it is hard to set up a microservice development environment. We’ve talked about the hardness of developing, running and testing a single microservice that depends on infrastructure services and other microservices.
• I’ve introduced Project Tye, a project developed by Microsoft to allow you to easily run multi-application solutions. We made a demo, then discussed its missing points.
• Then I introduced ABP Studio, a new product by Volosoft for ABP developers. As the first important feature, I explained the ABP Studio Solution Runner and demonstrated how it works and how you can develop and debug your services.
• Finally, I introduced ABP Studio’s Kubernetes Tunneling feature. First, I explained how it works with a complicated diagram. Then I made a short demo to see it in action.

With that final part, we had a great and easy to use microservice development environment. It is great, because we can focus on only a single service, while we don’t care about all other parts of the solution. Also, we can save our local development machine system resources by delegating running the dependencies to a remote Kubernetes server.

See Also

• ABP Dotnet Conf'23 Talk on YouTube: Kubernetes Integrated Microservice Development with ABP Studio

Dapper is a simple and lightweight object mapper for .NET. A key feature of Dapper is its high performance compared to other ORMs. In this article, I will show how to use it in your ABP projects. But, we'll see when to use it first.

Source Code

You can find the full source code of the demo application here.

When to Use Dapper?

In the ABP Framework, we suggest to use Dapper in combination with Entity Framework Core (EF Core) for the following reasons:

• EF Core is much easier to use (you don't need to manually write SQL queries and work with low level database objects).
• EF Core abstracts different DBMS dialects, so it will be easier to change your DBMS later.
• The EF Core's change tracking system automatically updates the changes in the database.
• EF Core is better compatible with Object Oriented Programming (OOP) practices and is more type safe to work with. So, the EF Core code is more understandable and maintainable.

In most of your use cases, you typically work with one or a few entities and a maintainable codebase can be chosen instead of a slight performance difference. However, there may be certain places in your application where it matters:

• You may work with a lot of entities, so you'd like to query faster (Indeed, EF Core's AsNoTracking() extension can help in most cases).
• You may be performing too many database operations in a single request.
• EF Core may not create an optimized SQL query and you may want to manually write it for better performance.

For such cases, Dapper can be a good choice. You can easily write SQL queries and bind the result to your objects.

Creating a new ABP Solution

To demonstrate the useage of Dapper, I've created an ABP solution. You can find the full source code of the demo application here. If you want to create the same solution from scratch, follow the steps below:

Install the ABP CLI if you haven't installed it before:

dotnet tool install -g Volo.Abp.Cli

Create a new solution with the ABP Framework's non-layered startup template with MVC UI and EF Core database:

abp new DapperDemo -t app-nolayers

The startup template and UI selection don't matter for this article. I selected these options to keep the demo solution simple.

After creating the solution, run the following command to migrate the database (run the command in the folder of the .csproj file:

dotnet run --migrate-database

If you've created a layered solution, then run the DbMigrator application inside the solution. If you have trouble by creating the solution, please refer to the Quick Start document.

Setting Up the Entity Framework Core Part

We will use EF Core with Dapper, so we need to configure EF Core first. I will use the following Book entity as an example:

public class Book : AuditedAggregateRoot<Guid>
{
    public string Name { get; set; }
    public DateTime PublishDate { get; set; }
    public float Price { get; set; }
}

If you are using a layered solution, entities are located in the Domain project. For my demo solution, I just placed it in the Entities folder of the single-layer project:

Once I created the Book entity, I should add it to my DbContext class:

public class DapperDemoDbContext : AbpDbContext<DapperDemoDbContext>
{
    // 1: ADD A DBSET PROPERTY
    public DbSet<Book> Books { get; set; }

    public DapperDemoDbContext(DbContextOptions<DapperDemoDbContext> options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        //...other code parts
        
        // 2: MAP YOUR ENTITY TO A DATABASE TABLE
        builder.Entity<Book>(b =>
        {
            b.ToTable("Books");
            b.Property(x => x.Name).IsRequired().HasMaxLength(128);
        });
    }
}

Now, we can add a new database migration:

dotnet ef migrations add Added_Book

And apply the changes to the database:

dotnet ef database update

At this point, you should be able to see the Books table if you check your database:

As you see, the Books table contains more fields than the Book entity's property count. Other properties are inherited from the AuditedAggregateRoot table. You could inherit from the BasicAggregateRoot class if you don't want these properties.

Seeding the Database

ABP's data seeding system is a great way to add some test data to the database. The following class inserts two books to the Books table when I migrate the database:

public class DapperDemoDataSeederContributor : IDataSeedContributor, ITransientDependency
{
    private readonly IRepository<Book, Guid> _bookRepository;

    public DapperDemoDataSeederContributor(IRepository<Book, Guid> bookRepository)
    {
        _bookRepository = bookRepository;
    }

    public async Task SeedAsync(DataSeedContext context)
    {
        if (await _bookRepository.GetCountAsync() > 0)
        {
            return;
        }

        await _bookRepository.InsertAsync(
            new Book
            {
                Name = "1984",
                PublishDate = new DateTime(1949, 6, 8),
                Price = 19.84f
            }
        );

        await _bookRepository.InsertAsync(
            new Book
            {
                Name = "The Hitchhiker's Guide to the Galaxy",
                PublishDate = new DateTime(1995, 9, 27),
                Price = 42.0f
            }
        );
    }
}

After creating the DapperDemoDataSeederContributor class, I can re-run the following command:

dotnet run --migrate-database

Now, I can see the records in the database:

Now, everything is ready to try querying from the Books table with Dapper.

Using Dapper Without the Integration Package

ABP provides an integration package for Dapper. However, I first want to demonstrate using Dapper without the integration package.

Installing the Dapper Package

First, install the Dapper package to your project. You can use a command-line terminal, locate the root path of your project (.csproj file that you want to install it in) and run the following command:

dotnet add package Dapper

If your application is layered, then we suggest to add the Dapper package to your EntityFrameworkCore integration project in your solution.

Executing a Dapper Query

I will query from the Books table, but I don't want to use the Book entity to map the result (because I don't need all the properties). So, I am creating a new class for the query result:

public class BookDataView
{
    public Guid Id { get; set; }    
    public string Name { get; set; }
    public float Price { get; set; }
}

Now, we can use Dapper's QueryAsync extension method as shown below:

public class DemoService : ITransientDependency
{
    private readonly IRepository<Book, Guid> _bookRepository;

    public DemoService(IRepository<Book, Guid> bookRepository)
    {
        _bookRepository = bookRepository;
    }
    
    [UnitOfWork]
    public virtual async Task<List<BookDataView>> GetListAsync()
    {
        var database = (await _bookRepository.GetDbContextAsync()).Database;
        var dbConnection = database.GetDbConnection();
        var dbTransaction = database.CurrentTransaction?.GetDbTransaction();
        
        var queryResult = await dbConnection.QueryAsync<BookDataView>(
            "SELECT Id, Name, Price FROM Books",
            transaction: dbTransaction
        );
        
        return queryResult.ToList();
    }
}

Let's examine this class:

• I've injected the ABP's standard generic repository service into the DemoService constructor.
• _bookRepository.GetDbContextAsync() returns the underlying DbContext object of EF Core. We need to have the Volo.Abp.EntityFrameworkCore package reference to be able to access that method. If you have created a single-layer solution, the reference will already have existed. If you have created a layered solution you may need to manually add this package to the project that contains the DemoService class. Because the layered solution isolates the EF Core dependency from the rest of the solution.
• Dapper needs a DbConnection and a DbTransaction object (as optional) to execute a query. We are getting them over the database object obtained from the DbContext. We suggest to always pass the current DbTransaction object while working with Dapper. Because, if there is a database transaction on the same database connection that you execute queries on, and you don't pass the transaction object, you'll get an exception.
• Finally, we can use Dapper's QueryAsync extension method to execute the database query.
• Notice that the GetListAsync method is made as virtual and marked with the UnitOfWork attribute to enable the Unit Of Work for that method. It ensures the database connection is available in the body of the GetListAsync method.

That's all. You can execute any Dapper operation using the DbConnection and DbTransaction objects obtained from the _bookRepository object. Please refer to Dapper's documentation for other operations.

We've obtained the DbContext object from a repository. However, a repository is not required to obtain a DbContext. Instead, you could inject the IDbContextProvider<T> service (IDbContextProvider<DapperDemoDbContext> for this demo) and call its GetDbContextAsync method.

Using the Volo.Abp.Dapper Package

In the previous section, you saw that you don't need an ABP integration package to be able to use Dapper in your ABP applications. However, there is an integration package here: Volo.Abp.Dapper. In fact, that package doesn't contain much services. It just provides a convenient base class to create Dapper based repository classes.

Installing the Volo.Abp.Dapper Package

You can use the ABP CLI to easily install ABP packages to your projects. Execute the following command in the folder of the .csproj file that you want to install the package on:

abp add-package Volo.Abp.Dapper

You can check the ABP Dapper document for alternative installation options.

Creating a Repository Class

In the DemoService example, we used database objects out of a repository class. If you want to implement layering to your solution and abstracting database operations, it can be better to create a repository class to execute the Dapper operations.

Here's a repository class that executes the same database query:

public class BookRepository : DapperRepository<DapperDemoDbContext>, ITransientDependency
{
    public BookRepository(IDbContextProvider<DapperDemoDbContext> dbContextProvider) 
        : base(dbContextProvider)
    {
    }
    
    public virtual async Task<List<BookDataView>> GetListAsync()
    {
        var connection = await GetDbConnectionAsync();
        var queryResult = await connection.QueryAsync<BookDataView>(
            "SELECT Id, Name, Price FROM Books",
            transaction: await GetDbTransactionAsync()
        );
        return queryResult.ToList();
    }
}

Let's examine this class:

• It inherits from the DapperRepository class, which provides useful methods and properties for database operations. It also implements the IUnitOfWorkEnabled interface, so ABP makes the database connection (and transaction if requested) available in the method body by implementing dynamic proxies (a.k.a. interception).
• The GetListAsync method's been made virtual. That's needed to make the interception process working. It wouldn't be needed if we introduce IBookRepository to that class and always use it by injecting the BookRepository class (in this case, it will use interface proxying - however, this is too much details for the purpose of this article).
• We've used the GetDbConnectionAsync and GetDbTransactionAsync methods to obtain the current database connection and transaction (that is managed by ABP's unit of work system).

You can then inject the BookRepository class when you want to get a list of BookDataView whenever it is needed. In the demo project, I used it inside the IndexModel.cshtml.cs to show a list of books on the page:

Conclusion

In this article, I've explained ABP's Dapper integration and demonstrated how you can execute Dapper operations in your applications. I suggest to use Dapper when it is really needed and adds any significant value (generally a performance gain) to your application. Otherwise, EF Core is much more convenient for most of the database operations and you will have a more maintainable codebase using EF Core.

Source Code

You can find the full source code of the demo application here.

See Also

• ABP Dapper documentation

What's New With Version 7.1?

All the new features were already explained in detail in the 7.1 RC Announcement Post, so no need to go over them again. Check it out for more details.

Getting Started with 7.1

Creating New Solutions

You can create a new solution with the ABP Framework version 7.1 by either using the abp new command or generating the CLI command on the get started page.

See the getting started document for more.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade it to the latest version.

If you haven't installed it yet:

dotnet tool install -g Volo.Abp.Cli

To update the existing CLI:

dotnet tool update -g Volo.Abp.Cli

Upgrading Existing Solutions with the ABP Update Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

Run this command in the root folder of your solution.

Migration Guides

This version includes a very minor breaking change and it doesn't affect most of the applications. Check the migration guide for the details.

Community News

ABP Community Talks 2023.2

The next ABP Community Talks will take place on March 30, at 18:00 (UTC).

In this episode, core ABP Framework developers will discuss the benefits of using the ABP Framework as a .NET developer instead of creating your own solution from scratch. They will answer most of the common doubts about using ABP and application frameworks in general. You will better understand how ABP makes a developer’s life easier and more enjoyable while cutting production costs. We will also have a question - answer session after the talk, as always. I think this talk will be useful for every .NET developer whether they use ABP or not.

CLICK HERE to register for the event and join us.

Introducing the first ABP .NET Conference!

As the ABP team, we've executed more than 10 online events and gained a good experience of software talks. In May, we are organizing a full-featured software conference, named ABP Dotnet Conference 2023!

We are still organizing the speakers, talks and schedule. There will be 12 sessions about software development and .NET. These will also include a few ABP-related talks. You can follow https://abp.io/conference website and buy early bird tickets from now.

New ABP Community Posts

There are exciting articles contributed by the ABP community as always. I will highlight some of them here:

• Creating Dockerfile for ABP Applications by Anto Subash

• IdentityUser Relationship and Extending it by Onur Pıçakçı

• Streamline Localization in Your ABP Project by Salih Özkara

• .Net Microservice template with ABP by Anto Subash

Thanks to the ABP Community for all the content they have published. You can also post your ABP related (text or video) content to the ABP Community.

About the Next Version

The next feature version will be 7.2. You can follow the release planning here. Please submit an issue if you have any problems with this version.

In November 2022, exciting things happened in the .NET world.

.NET Conf 2022

Microsoft has organized the .NET Conf 2022 between November 08 and 10 as an online event. There were many speakers talked in that conference from all around the World. If you've missed, you can watch all the sessions on YouTube.

Halil İbrahim Kalkan (co-founder of Volosoft) has also talked in the .NET Conf 2022 about "Authorization in a Distributed / Microservice System".

You can watch Halil's talk here.

What's new with ASP.NET & Entity Framework Core 7.0

Microsoft has released the .NET 7.0 in the .NET Conf 2022, with ASP.NET Core 7.0 and Entity Framework Core 7.0.

Our team has closely followed the ASP.NET Core and Entity Framework Core 7.0 releases, read Microsoft's guides and documentation and adapt the changes to our ABP.IO Platform. We are proud to say that we've shipped the ABP 7.0 RC.1 based on .NET 7.0 just after Microsoft's .NET 7.0 release.

In addition to the ABP's .NET 7.0 upgrade, the team has created 13 great articles to highlight the important features coming with ASP.NET Core 7.0 and Entity Framework Core 7.0. Here, a list of all the articles:

ASP.NET Core 7.0

• What's new with .NET 7.0 by Engincan Veske
• gRPC JSON Transcoding with ASP.NET Core 7.0 by Engincan Veske
• gRPC Health Checks with ASP.NET Core 7.0 by Muhammet Ali Özkaya
• Signalr Client Results in ASP.NET Core 7.0 by Liang Shiwei
• Rate Limiting with ASP.NET Core 7.0 by Berkan Şaşmaz
• ASP.NET Core Output Caching Middleware by Malik Masis

Entity Framework 7.0

• Injecting Service Dependencies to Entities with Entity Framework Core 7.0 by Halil İbrahim Kalkan
• The new EF Core interceptors in Entity Framework Core 7.0 by Liming Ma
• Inheritance Strategies in Entity Framework Core 7 by Alper Ebiçoğlu
• JSON Columns in Entity Framework Core 7 by Salih Özkara
• Model building conventions in Entity Framework Core 7.0 by İsmail Çağdaş
• Value generation for DDD guarded types with Entity Framework Core 7.0 by Galip Erdem
• Bulk Operations with Entity Framework Core 7.0 by Enis Necipoğlu

We enjoyed while writing these, we hope you also enjoy and like while reading. Happy coding!

-- The Volosoft Team

Dependency injection is a widely-used pattern of obtaining references to other services from our classes. It is a built-in feature when you develop ASP.NET Core applications. In this article, I will explain why we may need to have references to other services in an entity class and how we can implement Entity Framework Core's new IMaterializationInterceptor interface to provide these services to the entities using the standard dependency injection system.

You can find the source code of the example application here.

The Problem

While developing applications based on Domain-Driven Design (DDD) patterns, we typically write our business code inside application services, domain services and entities. Since the application and domain service instances are created by the dependency injection system, they can inject services into their constructors.

Here, an example domain service that injects a repository into its constructor:

public class ProductManager : DomainService
{
    private readonly IRepository<Product, Guid> _productRepository;

    public ProductManager(IRepository<Product, Guid> productRepository)
    {
        _productRepository = productRepository;
    }

    //...
}

ProductManager can then use the _productRepository object in its methods to perform its business logic. In the following example, ChangeCodeAsync method is used to change a product's code (the ProductCode property) by ensuring uniqueness of product codes in the system:

public class ProductManager : DomainService
{
    private readonly IRepository<Product, Guid> _productRepository;

    public ProductManager(IRepository<Product, Guid> productRepository)
    {
        _productRepository = productRepository;
    }

    public async Task ChangeCodeAsync(Product product, string newProductCode)
    {
        Check.NotNull(product, nameof(product));
        Check.NotNullOrWhiteSpace(newProductCode, nameof(newProductCode));

        if (product.ProductCode == newProductCode)
        {
            return;
        }
        
        if (await _productRepository.AnyAsync(x => x.ProductCode == newProductCode))
        {
            throw new ApplicationException(
                "Product code is already used: " + newProductCode);
        }

        product.ProductCode = newProductCode;
    }
}

Here, the ProductManager forces the rule "product code must be unique". Let's see the Product entity class too:

public class Product : AuditedAggregateRoot<Guid>
{
    public string ProductCode { get; internal set; }
    
    public string Name { get; private set; }
    
    private Product()
    {
        /* This constructor is used by EF Core while
           getting the Product from database */
    }
    
    /* Primary constructor that should be used in the application code */
    public Product(string productCode, string name)
    {
        ProductCode = Check.NotNullOrWhiteSpace(productCode, nameof(productCode));
        Name = Check.NotNullOrWhiteSpace(name, nameof(name));
    }
}

You see that the ProductCode property's setter is internal, which makes possible to set it from the ProductManager class as shown before.

This design has a problem: We had to make the ProductCode setter internal. Now, any developer may forget to use the ProductManager.ChangeCodeAsync method, and can directly set the ProductCode on the entity. So, we can't completely force the "product code must be unique" rule.

It would be better to move the ChangeCodeAsync method into the Product class and make the ProductCode property's setter private:

public class Product : AuditedAggregateRoot<Guid>
{
    public string ProductCode { get; private set; }
    
    public string Name { get; private set; }
    
    // ...
    
    public async Task ChangeCodeAsync(string newProductCode)
    {
        Check.NotNullOrWhiteSpace(newProductCode, nameof(newProductCode));

        if (newProductCode == ProductCode)
        {
            return;
        }
        
        /* ??? HOW TO INJECT THE PRODUCT REPOSITORY HERE ??? */        
        if (await _productRepository.AnyAsync(x => x.ProductCode == newProductCode))
        {
            throw new ApplicationException("Product code is already used: " + newProductCode);
        }
        
        ProductCode = newProductCode;
    }
}

With that design, there is no way to set the ProductCode without applying the rule "product code must be unique". Great! But we have a problem: An entity class can not inject dependencies into its constructor, because an entity is not created using the dependency injection system. There are two common points of creating an entity:

• We can create an entity in our application code, using the standard new keyword, like var product = new Product(...);.
• Entity Framework (and any other ORM / database provider) creates entities after getting them from the database. They typically use the empty (default) constructor of the entity to create it, then sets the properties coming from the database query.

So, how we can use the product repository in the Product.ChangeCodeAsync method? If we forget the dependency injection system, we would think to add the repository as a parameter to the ChangeCodeAsync method and delegate the responsibility of obtaining the service reference to the caller of that method:

public async Task ChangeCodeAsync(
    IRepository<Product, Guid> productRepository, string newProductCode)
{
    Check.NotNull(productRepository, nameof(productRepository));
    Check.NotNullOrWhiteSpace(newProductCode, nameof(newProductCode));

    if (newProductCode == ProductCode)
    {
        return;
    }

    if (await productRepository.AnyAsync(x => x.ProductCode == newProductCode))
    {
        throw new ApplicationException(
            "Product code is already used: " + newProductCode);
    }
    
    ProductCode = newProductCode;
}

However, that design would make hard to use the ChangeCodeAsync method, and also exposes its internal dependencies to outside. If we need another dependency in the ChangeCodeAsync method later, we should add another parameter, which will effect all the application code that uses the ChangeCodeAsync method. I think that's not reasonable. The next section offers a better and a more generic solution to the problem.

The Solution

First of all, we can introduce an interface that should be implemented by the entity classes which needs to use services in their methods:

public interface IInjectServiceProvider
{
     ICachedServiceProvider ServiceProvider { get; set; }
}

ICachedServiceProvider is a service that is provided by the ABP Framework. It extends the standard IServiceProvider, but caches the resolved services. Basically, it internally resolves a service only a single time, even if you resolve the service from it multiple times. The ICachedServiceProvider service itself is a scoped service, means it is created only once in a scope. We can use it to optimize the service resolution, however, the standard IServiceProvider would work as expected.

Next, we can implement the IInjectServiceProvider for our Product entity:

public class Product : AuditedAggregateRoot<Guid>, IInjectServiceProvider
{
    public ICachedServiceProvider ServiceProvider { get; set; }

    //...
}

I will explain how to set the ServiceProvider property later, but first see how to use it in our Product.ChangeCodeAsync method. Here, the final Product class:

public class Product : AuditedAggregateRoot<Guid>, IInjectServiceProvider
{
    public string ProductCode { get; internal set; }
    
    public string Name { get; private set; }
    
    public ICachedServiceProvider ServiceProvider { get; set; }

    private Product()
    {
        /* This constructor is used by EF Core while
           getting the Product from database */
    }
    
    /* Primary constructor that should be used in the application code */
    public Product(string productCode, string name)
    {
        ProductCode = Check.NotNullOrWhiteSpace(productCode, nameof(productCode));
        Name = Check.NotNullOrWhiteSpace(name, nameof(name));
    }
    
    public async Task ChangeCodeAsync(string newProductCode)
    {
        Check.NotNullOrWhiteSpace(newProductCode, nameof(newProductCode));

        if (newProductCode == ProductCode)
        {
            return;
        }

        var productRepository = ServiceProvider
            .GetRequiredService<IRepository<Product, Guid>>();
        
        if (await productRepository.AnyAsync(x => x.ProductCode == newProductCode))
        {
            throw new ApplicationException("Product code is already used: " + newProductCode);
        }
        
        ProductCode = newProductCode;
    }
}

The ChangeCodeAsync method gets the product repository from the ServiceProvider and uses it to check if there is another product with the given newProductCode value.

Now, let's explain how to set the ServiceProvider value...

Entity Framework Core Configuration

Entity Framework 7.0 introduces the IMaterializationInterceptor interceptor that allows us to manipulate an entity object just after the entity object is created as a result of database query.

We can write the following interceptor that sets the ServiceProvider property of an entity, if it implements the IInjectServiceProvider interface:

public class ServiceProviderInterceptor : IMaterializationInterceptor
{
    public object InitializedInstance(
        MaterializationInterceptionData materializationData, 
        object instance)
    {
        if (instance is IInjectServiceProvider entity)
        {
            entity.ServiceProvider = materializationData
                .Context
                .GetService<ICachedServiceProvider>();
        }

        return instance;
    }
}

Lifetime of the resolved services are tied to the lifetime of the related DbContext instance. So, you don't need to care if the resolved dependencies are disposed. ABP's unit of work system already disposes the DbContext instance when the unit of work is completed.

Once we defined such an interceptor, we should configure our DbContext class to use it. You can do it by overriding the OnConfiguring method in your DbContext class:

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    base.OnConfiguring(optionsBuilder);
    optionsBuilder.AddInterceptors(new ServiceProviderInterceptor());
}

Finally, you should ignore the ServiceProvider property in your entity mapping configuration in your DbContext (because we don't want to map it to a database table field):

protected override void OnModelCreating(ModelBuilder builder)
{
    base.OnModelCreating(builder);
    // ...
    builder.Entity<Product>(b =>
    {
        // ...
        /* We should ignore the ServiceProvider on mapping! */
        b.Ignore(x => x.ServiceProvider);
    });
}

That's all. From now, EF Core will set the ServiceProvider property for you.

Manually Creating Entities

While EF Core seamlessly set the ServiceProvider property while getting entities from database, you should still set it manually while creating new entities yourself.

Example: Set ServiceProvider property while creating a new Product entity:

public async Task CreateAsync(CreateProductDto input)
{
    var product = new Product(input.ProductCode, input.Name)
    {
        ServiceProvider = _cachedServiceProvider
    };
    
    await _productRepository.InsertAsync(product);
}

Here, you may think that it is not necessary to set the ServiceProvider, because we haven't used the ChangeCodeAsync method. You are definitely right; It is not needed in this example, because it is clear to see the entity object is not used between the entity creation and saving it to the database. However, if you call a method of the entity, or pass it to another service before inserting into the database, you may not know if the ServiceProvider will be needed. So, you should carefully use it.

Basically, I've introduced the problem and the solution. In the next section, I will explain some limitations of that design and some of my other thoughts.

Discussions

In this section, I will first discuss a slightly different way of obtaining services. Then I will explain limitations and problems of injecting services into entities.

Why injected a service provider, but not the services?

As an obvious question, you may ask why we've property-injected a service provider object, then resolved the services manually. Can't we directly property-inject our dependencies?

Example: Property-inject the IRepository<Product, Guid> service:

public class Product : AuditedAggregateRoot<Guid>
{
    // ...
    
    public IRepository<Product, Guid> ProductRepository { get; set; }
    
    public async Task ChangeCodeAsync(string newProductCode)
    {
        Check.NotNullOrWhiteSpace(newProductCode, nameof(newProductCode));

        if (newProductCode == ProductCode)
        {
            return;
        }

        if (await ProductRepository.AnyAsync(x => x.ProductCode == newProductCode))
        {
            throw new ApplicationException("Product code is already used: " + newProductCode);
        }
        
        ProductCode = newProductCode;
    }
}

Now, we don't need to implement the IInjectServiceProvider interface and manually resolve the IRepository<Product, Guid> object from the ServiceProvider. You see that the ChangeCodeAsync method is much simpler now.

So, how to set ProductRepository? For the EF Core interceptor part, you can somehow get all public properties of the entity via reflection. Then, for each property, check if such a service does exist, and set it from the dependency injection system if available. Surely, that will be less performant, but will work if you can truly implement. On the other hand, it would be extra hard to set all the dependencies of the entity while manually creating it using the new keyword. So, personally I wouldn't recommend that approach.

Limitations

One important limitation is that you can not use the services inside your entity's constructor code. Ideally, the constructor of the Product class should check if the product code is already used before. See the following constructor:

public Product(string productCode, string name)
{
    ProductCode = Check.NotNullOrWhiteSpace(productCode, nameof(productCode));
    Name = Check.NotNullOrWhiteSpace(name, nameof(name));
    
    /* Can not check if product code is already used by another product? */
}

It is not possible to use the product repository here, because;

1. The services are property-injected. That means they will be set after the object creation has completed.
2. Even if the service is available, it won't be truly possible to call async code in a constructor. You know constructors can not be async in C#, but the repository and other service methods are generally designed as async.

So, if you want to force the "product code must be unique" rule, you should create an async domain service method (like ProductManager.CreateAsync(...)) and always use it to create products (you can make the Product class constructor internal to not allow to use it in the application layer).

Design Problems

Beside the technical limitations, coupling your entities to external services is generally considered as a bad design. It makes your entities over-complicated, hard to test, and generally leads to take too much responsibility over the time.

Conclusion

In this article, I tried to investigate all aspects of injecting services into entity classes. I explained how to use Entity Framework 7.0 IMaterializationInterceptor to implement property-injection pattern while getting entities from database.

Injecting services into entities seems a certain way of forcing some business rules in your entities. However, because of the current technical limitations, design issues and usage difficulties, I don't suggest to depend on services in your entities. Instead, create domain services when you need to implement a business rule that depends on external services and entities.

The Source Code

• You can find the full source code of the example application here.
• You can see this pull request for the changes I've done after creating the application.

See Also

• What's new in EF Core 7.0
• ABP Framework: Dependency Injection
• ABP Framework: Domain Driven Design

WARNING: I've demonstrated Using gRPC with the ABP Framework in my latest post. If you haven't seen it, you should read it before this article, since this is a continuation of that article.

In this second part, I will show how to consume the gRPC service from the Blazor WebAssembly application, using the gRPC-Web technology.

This will be a short article, based on Microsoft's gRPC-Web in ASP.NET Core gRPC apps and Code-first gRPC services and clients with .NET documents. For more information, I suggest to check these documents. Let's get started...

Configuring the Server Side

First of all, the server-side should support gRPC-Web. Follow the steps below to enable it:

Add Grpc.AspNetCore.Web Package

Add Grpc.AspNetCore.Web NuGet package to the ProductManagement.HttpApi.Host project.

Add GrpcWeb Middleware

Add the following line just before the app.UseConfiguredEndpoints(...) line to add the GrpcWeb middleware to your ASP.NET Core request pipeline:

app.UseGrpcWeb(new GrpcWebOptions { DefaultEnabled = true });

Configure Cors

ABP's startup template already configures Cors when you create a new solution. However, we need to allow some extra headers in our Cors configuration.

Add the following line just after the .WithAbpExposedHeaders() line in the OnApplicationInitialization method of the ProductManagementHttpApiHostModule class:

.WithExposedHeaders("Grpc-Status", "Grpc-Message", "Grpc-Encoding", "Grpc-Accept-Encoding")

Finally, call RequireCors extension method just after the MapGrpcService calls:

app.UseConfiguredEndpoints(endpoints =>
{
    endpoints
        .MapGrpcService<IProductAppService>()
        .RequireCors("__DefaultCorsPolicy"); // Configure Cors for the product service
});

__DefaultCorsPolicy may seem a magic string here. Let me explain it: ABP startup template configures the default Cors policy with the context.Services.AddCors(...) method (you can see it in the source code). If we define a named policy, we should use the same name here. However, when we don't specify, ASP.NET Core uses __DefaultCorsPolicy as the policy name by default. If you don't want to use the magic string, you can resolve the IOptions<CorsOptions> service and get the DefaultPolicyName from the CorsOption object.

Anyway, that's all on the server-side. We can work on he client now.

Configuring the Client Side

ProductManagement.Blazor is the Blazor WebAssembly application in the solution I'd created in the first article. We will configure that project to be able to consume the server-side gRPC services from our Blazor application.

Add Client-side Nuget Packages

Add Grpc.Net.Client, Grpc.Net.Client.Web and protobuf-net.Grpc NuGet packages to the ProductManagement.Blazor project. We are ready to consume the gRPC services.

Consume the Product Service

Change the Pages/Index.razor.cs file's content with the following code block:

using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;
using Grpc.Net.Client.Web;
using ProductManagement.Products;
using ProtoBuf.Grpc.Client;

namespace ProductManagement.Blazor.Pages;

public partial class Index
{
    private List<ProductDto> Products { get; set; } = new();

    protected override async Task OnInitializedAsync()
    {
        var channel = GrpcChannel.ForAddress("https://localhost:10042", new GrpcChannelOptions
        {
            HttpHandler = new GrpcWebHandler(new HttpClientHandler())
        });

        var productAppService = channel.CreateGrpcService<IProductAppService>();
        Products = await productAppService.GetListAsync();
    }
}

• We've created a gRPC channel for the server-side endpoint (surely, you get the address from a configuration) with channel options by specifying that we will use the GrpcWebHandler.
• We've created a service proxy object using the CreateGrpcService extension method that is defined by the protobuf-net.Grpc NuGet package.
• We've used the service proxy object, productAppService, to consume remote endpoint just like a local service.

That's all. If we want to show the products on the page, we can add the following markup into the Pages/Index.razor view:

<h2>A list of products:</h2>

<ul class="list-group">
    @foreach(var product in Products)
    {
        <li class="list-group-item">
            @product.Name <br/>
            <small>@product.Id.ToString()</small>
        </li>
    }
</ul>

Run the applications (first run the ProductManagement.HttpApi.Host project, then run the ProductManagement.Blazor project in the solution) to see it in action:

Conclusion

In the first part of this article, I'd demonstrated how to implement a gRPC service and consume it in a client application, using the code-first approach. In this article, I've demonstrated how to consume the same gRPC service from a Blazor WebAssembly application, using the gRPC-Web technology. As you see in these two articles, using gRPC with the ABP Framework is straightforward.

The Source Code

• You can find the completed source code here: https://github.com/abpframework/abp-samples/tree/master/GrpcDemo2
• You can also see all the changes I've done in this article here: https://github.com/abpframework/abp-samples/pull/201/files

gRPC defines itself as an open source, language agnostic, universal, high-performance Remote Procedure Call (RPC) framework.

In this article, I will show you how to create a gRPC service and consume it from a console application with the ABP Framework. While the client application is console in this article, it can easily be a service consuming another service in a microservice system.

This article will be a step by step tutorial. I wrote the article based on Microsoft's Code-first gRPC services and clients with .NET document. You can read that document for more details about gRPC and the code-first approach.

Creating the Application

Install the ABP CLI if you haven't installed it yet:

dotnet tool install -g Volo.Abp.Cli

or update to the latest version if you've already installed an old version:

dotnet tool update Volo.Abp.Cli -g

Create an empty folder, open a command-line terminal and type the following command in the terminal window to create a new ABP solution using the ABP CLI:

abp new ProductManagement -u blazor -t app --preview

I've created an application with the Blazor UI, but the UI is not important for this tutorial, you can select your favorite UI option.

Open the Solution

Open the solution in your favorite IDE. I like Rider, but Visual Studio, VS Code or any other IDE perfectly works. The following figure shows the solution structure in Rider:

Run the ProductManagement.DbMigrator project (a console application) to create the database and seed the initial data.

Defining the Service Contract

We are starting by defining the service contract and DTO classes that will be shared between the server and the client applications.

Create a Products folder in the ProductManagement.Application.Contracts project and add a new interface named IProductAppService:

using System.Collections.Generic;
using System.ServiceModel;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;

namespace ProductManagement.Products;

[ServiceContract]
public interface IProductAppService : IApplicationService
{
    Task<List<ProductDto>> GetListAsync();
}

Your IDE will complain about the [ServiceContract] attribute, but it is necessary for the contract-first gRPC library we will be using later. So, add the System.ServiceModel.Primitives NuGet package to the ProductManagement.Application.Contracts project, and it should be fixed. You can simply edit the ProductManagement.Application.Contracts.csproj file and add the following line in an ItemGroup tag:

<PackageReference Include="System.ServiceModel.Primitives" Version="4.7.0" />

Or you can use your IDE to find and add that NuGet package, it is up to you.

I've also used the ProductDto class, but haven't defined it yet. Create a new class in the same folder with the IProductAppService file:

using System;
using System.Runtime.Serialization;

namespace ProductManagement.Products;

[DataContract]
public class ProductDto
{
    [DataMember(Order = 1)]
    public Guid Id { get; set; }

    [DataMember(Order = 2)]
    public string Name { get; set; }
}

The [DataContract] and [DataMember] properties are needed for serialization. In gRPC, property serialization orders are important, because property names are not transferred to the target application, to keep the serialized data small.

After adding these classes, the ProductManagement.Application.Contracts project should look as in the following figure:

The contracts part is over. We actually didn't have any dependency to gRPC at that point. Our service and DTOs are pretty plain classes, except a few standard attributes, which are already defined in the .NET Core framework. Now, we can implement the IProductAppService.

Implementing the Service

We are implementing the application services in the ProductManagement.Application project. So, add a new Products folder to that project and define a ProductAppService class inside it:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ProductManagement.Products;

public class ProductAppService : ProductManagementAppService, IProductAppService
{
    public async Task<List<ProductDto>> GetListAsync()
    {
        return new List<ProductDto>
        {
            new ProductDto { Id = Guid.NewGuid(), Name = "Product 1" },
            new ProductDto { Id = Guid.NewGuid(), Name = "Product 2" },
        };
    }
}

This is a pretty standard, plain application service class. All the ABP application service features (validation, audit logging, unit of work, etc.) are available. You can inject repositories and perform database queries. To keep this article simple, I am returning hard-coded data from here.

ProductManagementAppService is a base class coming in the ABP startup template. While you don't have to inherit from it, it provides useful base properties and methods you typically need in an application service.

The application service part is over. Again, we didn't write any gRPC specific code. Don't worry, we will write in the next section.

Configuring the gRPC Server

In this solution, ProductManagement.HttpApi.Host is the project that configures and runs the server-side application. So, we will make changes in that project.

First, add the protobuf-net.Grpc.AspNetCore NuGet package to the ProductManagement.HttpApi.Host project:

<PackageReference Include="protobuf-net.Grpc.AspNetCore" Version="1.0.177" />

Then open the ProductManagementHttpApiHostModule.cs file, find the ConfigureServices method and add the following line into this method:

context.Services.AddCodeFirstGrpc();

This will register code-first gRPC services to the dependency injection system. Then find the app.UseConfiguredEndpoints() line in the OnApplicationInitialization method and change it as shown below:

app.UseConfiguredEndpoints(endpoints =>
{
    endpoints.MapGrpcService<IProductAppService>();
});

We've configured the IProductAppService to handle gRPC requests to that service. The following figure shows the whole change done in the ProductManagementHttpApiHostModule class:

gRPC handles requests with the HTTP/2 protocol and should listen an endpoint other than the default HTTP endpoint used by the application. We can easily configure the Kestrel server to listen two endpoints, one for our HTTP APIs, the other one for gRPC services. Add the following configuration inside the appsettings.json file of the ProductManagement.HttpApi.Host project:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://localhost:44388",
      "Protocols": "Http1AndHttp2"
    },
    "gRPC": {
      "Url": "https://localhost:10042",
      "Protocols": "Http2"
    }
  }
}

Note that https://localhost:44388 may be different for your case, since ABP CLI assignes a random port while you're creating a new solution. You can check your port by running the ProductManagement.HttpApi.Host project and looking at the address bar on your browser.

The server-side configuration is done. It is ready to receive gRPC requests. Now, we can change the client to consume the gRPC service we've created.

Implementing the Client Side

The ABP startup solution template comes with a console application to test consuming your HTTP APIs. For this example, the project is named as ProductManagement.HttpApi.Client.ConsoleTestApp and located under the test folder in the solution.

First, add the Grpc.Net.Client and the protobuf-net.Grpc NuGet packages to the ProductManagement.HttpApi.Client.ConsoleTestApp project.

<PackageReference Include="Grpc.Net.Client" Version="2.49.0-pre1" />
<PackageReference Include="protobuf-net.Grpc" Version="1.0.177" />

Now, open the ClientDemoService.cs file under the ProductManagement.HttpApi.Client.ConsoleTestApp project and change its contents with the following code block:

using System;
using System.Threading.Tasks;
using Grpc.Net.Client;
using ProductManagement.Products;
using ProtoBuf.Grpc.Client;
using Volo.Abp.DependencyInjection;

namespace ProductManagement.HttpApi.Client.ConsoleTestApp;

public class ClientDemoService : ITransientDependency
{
    public async Task RunAsync()
    {
        using (var channel = GrpcChannel.ForAddress("https://localhost:10042"))
        {
            var productAppService = channel.CreateGrpcService<IProductAppService>();
            var productDtos = await productAppService.GetListAsync();

            foreach (var productDto in productDtos)
            {
                Console.WriteLine($"[Product] Id = {productDto.Id}, Name = {productDto.Name}");
            }
        }
    }
}

We are simply creating a gRPC channel, then creating a client proxy for the IProductAppService service. Then we can call its method just like local method calls. You can run the applications to test it.

Run the Applications

First run the ProductManagement.HttpApi.Host application. It should show a Swagger UI as shown below:

If you see that page, it means your server-side is up and running. Now, you can run the ProductManagement.HttpApi.Client.ConsoleTestApp console application to call the gRPC service defined on the server.

The test console application should produce an output as shown below:

As you see, products are returned from the server. That's all, you've done it!

Conclusion

In this article, I've used the code-first approach to implement a gRPC server and consume it in a client application. Code-first approach is very practical if both of your client and server applications are built with .NET. By the help of ABP's layered solution structure, we even didn't add any gRPC dependency into our server-side and contracts. We've just configured gRPC in the hosting side, with a small amount of code.

gRPC on .NET has different approaches, features, configurations and more details. I suggest you to read Microsoft's documentation to learn more about it. All the approaches can work with the ABP Framework. Enjoy coding!

The Source Code

• You can find the completed source code here: https://github.com/abpframework/abp-samples/tree/master/GrpcDemo2

• You can also see all the changes I've done in this article here: https://github.com/abpframework/abp-samples/pull/200/files

See Also

• Consuming gRPC Services from Blazor WebAssembly Application Using gRPC-Web

ASP.NET Core provides a built-in dependency injection system to register your services to the dependency injection container and inject/resolve them whenever you need. ABP's dependency injection infrastructure is built on ASP.NET Core's DI system, automates service registration by conventions and provides some additional features.

In this tutorial, I will explain how you can register multiple implementations of the same service interface and inject/resolve all these implementations when you need them.

Defining Services

Assume that you have an IExternalLogger interface with two implementations:

public interface IExternalLogger
{
    Task LogAsync(string logText);
}

public class ElasticsearchExternalLogger : IExternalLogger
{
    public async Task LogAsync(string logText)
    {
        // TODO...
    }
}

public class AzureExternalLogger : IExternalLogger
{
    public async Task LogAsync(string logText)
    {
        // TODO...
    }
}

An example service injecting the IExternalLogger interface:

public class MyService : ITransientDependency
{
    private readonly IExternalLogger _externalLogger;

    public MyService(IExternalLogger externalLogger)
    {
        _externalLogger = externalLogger;
    }

    public async Task DemoAsync()
    {
        await _externalLogger.LogAsync("Example log message...");
    }
}

In this example, we haven't registered any of the implementation classes to the dependency injection system yet. So, if we try to use the MyService class, we get an error indicating that no implementation found for the IExternalLogger service. We should register at least one implementation for the IExternalLogger interface.

Registering Services

If we register both of the ElasticsearchExternalLogger and AzureExternalLogger services for the IExternalLogger interface, and then try to inject the IExternalLogger interface, the last registered implementation will be used. However, how to determine the last registered implementation?

If we implement one of the dependency interfaces (e.g. ITransientDependency), then the registration order will be uncertain (it may depend on the namespaces of the classes). The last registered implementation can be different than you expect. So, it is not suggested to use the dependency interfaces to register multiple implementations.

You can register your services in the ConfigureServices method of your module:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    context.Services.AddTransient<IExternalLogger, ElasticsearchExternalLogger>();
    context.Services.AddTransient<IExternalLogger, AzureExternalLogger>();
}

In this case, you get an AzureExternalLogger instance when you inject the IExternalLogger interface, because the last registered implementation is the AzureExternalLogger class.

Injecting Multiple Implementations

When you have multiple implementation of an interface, you may want to work with all these implementations. For this example, you may want to write log to all the external loggers. We can change the MyService implementation as the following:

public class MyService : ITransientDependency
{
    private readonly IEnumerable<IExternalLogger> _externalLoggers;

    public MyService(IEnumerable<IExternalLogger> externalLoggers)
    {
        _externalLoggers = externalLoggers;
    }

    public async Task DemoAsync()
    {
        foreach (var externalLogger in _externalLoggers)
        {
            await externalLogger.LogAsync("Example log message...");
        }
    }
}

In this example, we are injecting IEnumerable<IExternalLogger> instead of IExternalLogger, so we have a collection of the IExternalLogger implementations. Then we are using a foreach loop to write the same log text to all the IExternalLogger implementations.

If you are using IServiceProvider to resolve dependencies, then use its GetServices method to obtain a collection of the service implementations:

IEnumerable<IExternalLogger> services = _serviceProvider.GetServices<IExternalLogger>();

Further Reading

In this small tutorial, I explained how you can register multiple implementations of the same interface to the dependency injection system and inject/resolve all of them when you need.

If you want to get more information about ABP's and ASP.NET Core's dependency injection systems, you can read the following documents:

• ABP's Dependency Injection documentation
• ASP.NET Core Dependency Injection best practices, tips & tricks
• ASP.NET Core's Dependency Injection documentation

What's New With 5.2?

Since all the new features are already explained in details with the 5.2 RC Announcement Post, I will not repeat all the details again. See the RC Blog Post for all the features and enhancements.

Creating New Solutions

You can create a new solution with the ABP Framework version 5.2 by either using the abp new command or using the direct download tab on the get started page.

See the getting started document for more.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

Run this command in the root folder of your solution.

Migration Guide

Check the migration guide for the applications with the version 5.x upgrading to the version 5.2.

About the Next Version

The next feature version will be 5.3. It is planned to release the 5.3 RC (Release Candidate) on May 03 and the final version on May 31, 2022. You can follow the release planning here.

Please submit an issue if you have any problem with this version.

The planned release date for the 5.2.0 Stable version is April 05, 2022.

Please try this version and provide feedback for a more stable ABP version 5.2! Thank you all.

Get Started with the 5.2 RC

Follow the steps below to try the version 5.2.0 RC today:

1. Upgrade the ABP CLI to version 5.2.0-rc.1 using a command line terminal:

dotnet tool update Volo.Abp.Cli -g --version 5.2.0-rc.1

​ or install it if you haven't before:

dotnet tool install Volo.Abp.Cli -g --version 5.2.0-rc.1

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

You can use any IDE that supports .NET 6.x, like Visual Studio 2022.

Migration Guides

Please see the migration guides if you are upgrading from 5.x versions:

• ABP Framework 5.x to 5.2 migration guide
• ABP Commercial 5.x to 5.2 migration guide

What's New with ABP Framework 5.2?

In this section, I will introduce some major features released with this version. Here, a brief list of titles explained in the next sections:

• Single-layer Solution Template
• API Versioning
• libs Folder Has been Removed from Source Control
• Hiding the Default ABP Endpoints from Swagger UI
• Custom Global CSS and JavaScript for the CMS Kit module
• Other news

Let's begin with the first item.

Single-layer Solution Template

ABP's application startup template is a well-organized and layered solution to create maintainable business applications. However, some developers find it a little bit complex for simple and short-term applications. For such applications, we've created a new startup template that has no layering and built as simple as possible. It has the same functionality, features and modules on runtime, but the development model is minimal and everything is in the single project (csproj), as shown in the following figure:

Use the app-nolayers as the template name while creating your solution:

abp new BookStore -t app-nolayers --preview

ABP Commercial developers can use the app-nolayers-pro as the startup template:

abp new BookStore -t app-nolayers-pro --preview

There is a bug for the app-nolayers-pro related to the licensing system, which will be fixed with 5.2.0-rc.2: appsettings.secrets.json is missing in the project folder (should be near to appsettings.json and contains the license code normally). As a workaround, create a new solution with the layered startup template, find and copy that file to the single-layer solution.

One note about the single-layer project is it doesn't have Blazor WebAssembly UI, because it requires 3 projects at least (one server-side, one UI and one shared library project between these two). We will consider to add Blazor UI support based on your feedback. You can continue to develop Blazor WASM projects using the standard layered solution template.

Database Migrations for EF Core

After creating your solution, you need to create the database before running the application. We've added a parameter to the application that can be specified to migrate the database and seed the initial data. Open the project's directory (that contains the csproj file) in a command-line terminal and type the following command:

dotnet run --migrate-database

It will run, migrate the database and exit. You can then run the application as normal.

You could use the standard dotnet ef database update command (or Update-Database command in Visual Studio's Package Manager Console). It can successfully create the database tables. However, it doesn't seed the initial data that is necessary to run the application.

To keep the solution simple, we haven't added an external application (like the DbMigrator in the layered application startup template) to migrate the database.

Using the same application to migrate the database is simple and useful for development environment, and it can also be used in production environment. However, there are other ways of migrating a database. Please read more on Microsoft's documentation.

Other UI and Database Options

The new single-layer solution template also supports Angular and Blazor UI, and MongoDB for the database side. For the UI, you can use mvc (default), angular or blazor-server with the -u (or --ui) parameter. For the database provider, you can use ef (default) or mongodb with the -d (or --database-provider) parameter. Example:

abp new BookStore -t app-nolayers -u angular -d mongodb --preview

This will create a single layer template with Angular as the UI framework and MongoDB as the database provider.

Single-Layer Tutorial

Hamza Albreem has created a video tutorial to explain how to develop a simple application with this startup template.

You can watch it here.

API Versioning

API versioning has always been possible with the ABP Framework, but we haven't had a documentation for it. With version 5.2, we've created a document to explain how to implement API versioning for your applications and add versioning support to your standard application service classes. See the documentation here.

libs Folder Has been Removed from Source Control

NOTICE: This can be a breaking change for your development environment and CI/CD pipelines. So, please read it carefully and take the necessary actions.

When you create solutions with MVC (Razor Pages) or Blazor Server UI, your application will have a wwwroot/libs folder in the UI project as shown below:

The libs folder contains all the client-side (mostly JavaScript and CSS) library dependencies. For example, in the figure above, the bootstap folder contains the necessary files for the Bootstrap library. The folder's content is copied from the node_modules folder (it only copies the minimum files to make the library work, not the whole folder) with ABP CLI's abp install-libs command.

Before version 5.2, the libs folder was coming with the startup template and committed into your source control system (e.g. Git). With version 5.2, this folder is excluded from the source control by default, so every developer getting the solution must run abp install-libs in the UI project's root directory to install these libraries. This approach saves a huge amount of size of the solution. For example, the initial size of an MVC UI application reduces from 9.83MB to 0.23MB (you read it right!).

When you create a new solution with ABP CLI, abp install-libs command is automatically executed, so your application directly works. However, if your teammates (or CI/CD system) get the solution from the source control, they should run the abp install-libs before running the solution. If you don't want that, you can simply remove the **/wwwroot/libs/* line from the .gitignore file in the root folder of your solution, then the libs folder is added to your source control again (if you are using a source control system other than Git, you should apply your system's rules to include/exclude that folder).

Hiding the Default ABP Endpoints from Swagger UI

Engincan Veske had written an article to explain how to hide ABP's default endpoints from Swagger UI. Then We thought that could be a good built-in option in the ABP Framework and added a HideAbpEndpoints method to the AddAbpSwaggerGen method, which can be used as in the following code example:

services.AddAbpSwaggerGen(
    options => 
    {
        //... other options
        
        //Hides ABP Related endpoints on Swagger UI
        options.HideAbpEndpoints();
    }
)

After that, ABP's default endpoints will still be functional, but will be hidden in Swagger UI.

Custom Global CSS and JavaScript for the CMS Kit module

We are improving the CMS Kit module and adding new features constantly. A new feature with version 5.2 is a global resources system, where you can write custom JavaScript or CSS code on the application's UI (added a new page for it), which will be immediately available in all your application pages:

In this way, you can customize your application's look and behavior on runtime. See the documentation for more information.

Note that the pages feature already have a page-basis script/style editor. But this new feature allows you to write script/style that is applied to all pages of your application.

Other news

• Upgraded the Blazorise library to v1.0 for Blazor UI. After the upgrade, ensure that all Blazorise-related packages are using v1.0 in your application.

If you want to see more details, you can check the release on GitHub, that contains a list of all issues and pull requests closed with this version.

What's New with ABP Commercial 5.2?

We've also made many enhancements for ABP Commercial, and also made the necessary changes and improvements to align with the v5.2 release of the ABP Framework. For example, the single-layer solution template is also available for ABP Commercial as explained above.

Many to Many Relations on Code Generation

One exciting new feature with ABP Commercial v5.2 is supporting many-to-many entity relations while generating CRUD code with ABP Suite.

When you open ABP Suite v5.2, you will see an "Add navigation collection" button in the Navigation tab. Here, you can click that button, select the target entity and other options:

With this new feature, you can automatically generate advanced user interfaces without touching the code, then customize the generated code to implement your business logic.

Community News

We organized the 3rd live ABP Community Talks event on February 23rd. ABP community has a good interest in these events and we will continue to organize such a live event in every month. March's event will be announced in a few days. Follow us on twitter.

ABP Community website is being a huge resource of articles and video tutorials on the ABP Framework and .NET. There have been 93 articles/tutorials submitted so far. Here's a list of a few contents posted in the last weeks:

• Ahmet Urel submitted a series of articles to demonstrate the usage of MudBlazor library with the ABP Framework Blazor UI: Part 1, Part 2 and Part 3.
• Enis Necipoğlu has created two articles for ABP & .NET MAUI integration: See Part 1 and Part 2. Bart Van Hoey also created an article for .NET MAUI and the ABP Framework.
• Enis Necipoğlu has also created an article to demonstrate how to use his own open source AutoFilterer library with the ABP Framework.
• Jonathan Potts has created his first ABP Community article that shows how to use Bootswatch themes with the ABP Framework. See it here.

Thanks to all the contributors. It is appreciated if you want to submit your post and share your knowledge with the ABP community: https://community.abp.io/posts/create

Conclusion

This version was mostly about minor features and enhancements for existing features, and getting the framework, architecture and solution structure more mature. Currently, we are working on middle and long term features, changes and goals. You can find most of them on the road map here.

The planned release date for the 5.2.0 Stable version is April 05, 2022. Please try the ABP v5.2 RC and provide feedback to have a more stable release.

Get Started with 5.1

Follow the steps below to try the 5.1 version today:

1. Upgrade the ABP CLI to the latest version using a command line terminal:

dotnet tool update Volo.Abp.Cli -g

or install if you haven't installed it before:

dotnet tool install Volo.Abp.Cli -g

2. Create a new application:

abp new BookStore

Check out the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page.

You can use any IDE that supports .NET 6.x development (e.g. Visual Studio 2022).

Migration Notes & Breaking Changes

This is a minor feature release, mostly with enhancements and improvements based on version 5.0. There aren't any breaking changes except for the Angular UI upgrade. ABP 5.1 startup templates use Angular 13.

Angular UI

If you want to upgrade the ABP Framework but want to continue with Angular 12, add the following section to the package.json file of the Angular project:

"resolutions": {
    "ng-zorro-antd": "^12.1.1",
    "@ng-bootstrap/ng-bootstrap": "11.0.0-beta.2"
  }

What's New with the ABP Framework 5.1?

In this section, I will introduce some major features released with this version.

The New Hosting Model

The ABP startup application template now uses the new ASP.NET Core hosting APIs (check out the Microsoft's minimal APIs document) on application startup (check out the exact place in the ABP startup template). So, the Startup.cs file has been removed.

Old-style hosting logic will continue to work as long as ASP.NET Core supports it. It is recommended to switch to the new model if it's possible for your solution. Check out this guide if you need to know how to do that.

Asynchronous Startup Lifecycle Methods

The new hosting model allows us to execute asynchronous code on application initialization in the ABP module classes. If you are using the new hosting model (which is default with 5.1 startup templates), you can override the Async versions of the module lifecycle methods.

For example, you can now override the ConfigureServicesAsync (instead of ConfigureServices) or OnApplicationInitializationAsync (instead of OnApplicationInitialization) as shown in the following code block:

public class MyModule : AbpModule
{
    public override async Task ConfigureServicesAsync(ServiceConfigurationContext context)
    {
        /* You can use await here and safely execute other async methods */
    }

    public override async Task OnApplicationInitializationAsync(ApplicationInitializationContext context)
    {
        /* You can use await here and safely execute other async methods */
    }
}

If you override both the asynchronous and synchronous versions of the same method, only the asynchronous one will be executed. So, override only one of them based on your needs.

eShopOnABP Is Getting More Stable

Our team is working to finalize the eShopOnAbp example solution, which is a reference microservice solution built with the ABP Framework. They will explain the project status and show what's done in the next ABP Community Talks meeting (Check out the ABP Community Talks 2021.1 section at the bottom of this post).

The New ABP.IO Design!

We've been working on a new design for the abp.io websites for a while. We are adding the final touches; the new design will be live very soon. Here's a screenshot from the design work:

The ABP Commercial and ABP Community websites will also have new designs as part of this update.

Other Changes

Here are some other notable changes that come with this release:

• Support markdown in CMS-Kit comments feature (#10792)
• Used file scoped namespaces for all the ABP Framework source code :) (#10552)

All issues & PRs in 5.1 milesone.

About ABP Commercial

The core team is also working on ABP Commercial (which provides pre-built modules, themes, tooling and support on top of the ABP Framework). We've done a lot of minor improvements and fixes to the modules and tooling.

There's some exciting news about the LeptonX theme; We are working on making it available in the MVC (Razor Pages) and Blazor UI options too (in addition to Angular UI). We are also adding more components, layout options, demo pages, etc... We are planning to release a beta version in the next weeks. Here's an animated GIF from the dashboard we've prepared as a demonstration:

If you are wondering what is the LeptonX project, please check out this blog post.

As another visible functionality, we've added a new feature to the CMS Kit Pro module that is used to forward a URL to another URL. This is a screenshot from the management UI:

This feature can be used to create short URLs in your application (like URL shortening services providers) or forward old pages to their new URLs.

In addition to the new features shipped in every minor version, we are working on long-term projects for ABP.IO Platform and ABP Commercial (a little secret for now :). We will have announcements once these projects get more stable.

Community News

ABP Community Talks 2021.1

This is the second episode of the ABP Community Talks and we are talking about microservice development with the ABP Framework, based on the eShopOnAbp reference solution. We will also briefly talk about the changes that come with ABP version 5.1. This live meeting will be on January 20, 2022, 17:00 (UTC) on YouTube.

Join this event on the Kommunity platform: https://kommunity.com/volosoft/events/abp-community-talks-20221-microservice-development-acd0f44b

You can also subscribe to Volosoft YouTube channel for reminders of further ABP events and videos.

New ABP Community Posts

Here are some of the recent posts added to the ABP community:

• Minimal API development with the ABP Framework by @antosubash (three parts, video tutorial).
• Integrating the Syncfusion MVC Components to the ABP MVC UI by @EngincanV.
• Add Tailwind CSS to your ABP Blazor UI by @antosubash (video tutorial).
• Import external users into the users Table from an ABP Framework application by @bartvanhoey.

Thanks to the ABP Community for all the contents they have published. You can also post your ABP and .NET related (text or video) contents to the ABP Community.

Conclusion

In this blog post, I summarized the news about the new version and the ABP Community. Please try it and provide feedback by opening issues on the GitHub repository. Thank you all!

What's new with 5.0?

Since all the new features are already explained in details with the 5.0 RC.1 Announcement Post, I will not repeat all the details again. See the RC Blog Post for all the features and enhancements.

Getting started with 5.0

Creating new solutions

You can create a new solution with the ABP Framework version 5.0 by either using the abp new command or using the direct download tab on the get started page.

Type the following command in a command-line terminal to install the ABP CLI version 5.0:

dotnet tool install -g Volo.Abp.Cli --version 5.0.0

To upgrade your existing ABP CLI installation:

dotnet tool update -g Volo.Abp.Cli --version 5.0.0

Then you can create a new solution using the abp new command:

abp new Acme.BookStore

See the getting started document for details.

Upgrading existing solutions

Check the migration guide for the applications with the version 4.x upgrading to the version 5.0. Also see the upgrading guide to understand how to update existing solutions.

ABP Community Talks 2021.12

As the core ABP development team, we've decided to organize monthly live meetings with the ABP community. The first live meeting will be at December 16, 2021, 17:00 (UTC) on YouTube. ABP core team members will present some of the new features coming with ABP 5.0.

Join this event on the Kommunity platform: https://kommunity.com/volosoft/events/abp-community-talks-4afca9c9

See you in the event!

The planned release date for the 5.0.0 Stable version is December 14, 2021.

Please try this version and provide feedback for a more stable ABP version 5.0! Thank you all.

Get Started with the 5.0 RC

follow the steps below to try the version 5.0.0 RC today;

1. Upgrade the ABP CLI to the version 5.0.0-rc.1 using a command line terminal:

dotnet tool update Volo.Abp.Cli -g --version 5.0.0-rc.1

or install if you haven't installed before:

dotnet tool install Volo.Abp.Cli -g --version 5.0.0-rc.1

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

You can use any IDE that supports .NET 6.0, like Visual Studio 2022.

Migration Notes & Breaking Changes

This is a major version and there are some breaking changes and upgrade steps. Here, a list of important breaking changes in this version:

• Upgraded to .NET 6.0, so you need to move your solution to .NET 6.0 if you want to use the ABP 5.0.
• Upgraded to Bootstrap 5. This is the most important breaking change in ABP 5.0 and you should take care of it.
• IRepository doesn't inherit from IQueryable anymore. It was already made obsolete in 4.2.
• Removed NGXS and states from the Angular UI.
• Removed gulp dependency from the MVC / Razor Pages UI in favor of abp install-libs command of the ABP CLI.
• Deprecated EntityCreatingEventData, EntityUpdatingEventData, EntityDeletingEventData and EntityChangingEventData classes. See #9897.

Please see the migration document for all the details. You can also see all the closed issues and pull requests.

What's new with 5.0?

In this section, I will introduce some major features released with this version.

Static (Generated) Client Proxies for C# and JavaScript

Dynamic C# (see) and JavaScript (see) client proxy system is one of the most loved features of the ABP Framework. It generates the proxy code on runtime and makes client-to-server calls a breeze. With ABP 5.0, we are providing an alternative approach: You can generate the client proxy code on development-time.

Development-time client proxy generation has a performance advantage since it doesn't need to obtain the HTTP API definition on runtime. It also makes it easier to consume a (micro)service behind an API Gateway. With dynamic proxies, we should return a combined HTTP API definition from the API Gateway and need to add HTTP API layers of the microservices to the gateway. Static proxies removes this requirement. One disadvantage is that you should re-generate the client proxy code whenever you change your API endpoint definition. Yes, software development always has tradeoffs :)

Working with static client proxy generation is simple with the ABP CLI. You first need to run the server application, open a command-line terminal, locate to the root folder of your client application, then run the generate-proxy command of the ABP CLI.

Creating C# client proxies

C# client proxies are useful to consume APIs from Blazor WebAssembly applications. It is also useful for microservice to microservice HTTP API calls. Notice that the client application need to have a reference to the application service contracts (typically, the .Application.Contracts project in your solution) in order to consume the services.

Example usage:

abp generate-proxy -t csharp -u https://localhost:44305

-t indicates the client type, C# here. -u is the URL of the server application. It creates the proxies for the application (the app module) by default. You can specify the module name as -m <module-name> if you are building a modular system. The following figure shows the generated files:

The next step is to enable the static proxy system for your application (or module) using the AddStaticHttpClientProxies extension method:

context.Services.AddStaticHttpClientProxies(
    typeof(MyApplicationContractsModule).Assembly
);

You can then inject and use the application service interfaces of these proxies. The usage is same of the dynamic C# client proxies.

When you use static proxies for a module / application, you don't need to dynamic proxies. Find and remove the context.Services.AddHttpClientProxies(...) in your solution (typically in the *.HttpApi.Client project).

Creating JavaScript client proxies

JavaScript proxies are useful to consume APIs from MVC / Razor Pages UI. It works on JQuery AJAX API, just like the dynamic JavaScript proxies.

Example usage:

abp generate-proxy -t js -u https://localhost:44305

The following figure shows the generated file:

Then you can consume the server-side APIs from your JavaScript code just like the dynamic JavaScript proxies.

Creating Angular client proxies

Angular developers knows that the generate-proxy command was already available in ABP's previous versions to create client-side proxy services in the Angular UI. The same functionality continues to be available and already documented here.

Example usage:

abp generate-proxy -t ng -u https://localhost:44305

Transactional Outbox & Inbox for the Distributed Event Bus

This was one of the most awaited features by distributed software developers.

The transactional outbox pattern is used to publishing distributed events within the same transaction that manipulates the application database. Distributed events are saved into the database inside the same transaction with your data changes, then sent to the message broker (like RabbitMQ or Kafka) by a separate background worker with a re-try system. In this way, it ensures the consistency between your database state and the published events.

The transactional inbox pattern, on the other hand, saves incoming events into database first, then executes the event handler in a transactional manner and removes the event from the inbox queue in the same transaction. It also ensures that the event is only executed one time by keeping the processed messages for a while and discarding the duplicate events received from the message broker.

Enabling the inbox and outbox patterns requires a few manual steps for your application. We've created a simple console application example, but I will also explain all the steps here.

Pre-requirements

First of all, you need to have EF Core or MongoDB installed into your solution. It should be already installed if you'd created a solution from the ABP startup template.

Install the packages

For the outbox & inbox functionality, ABP depends on DistributedLock.Core library which provides a distributed locking system for concurrency control in a distributed environment. There are many distributed lock providers, including Redis, SqlServer and ZooKeeper. You can use the one you like. Here, I will show the Redis provider.

Add DistributedLock.Redis NuGet package to your project, then add the following code into the ConfigureService method of your ABP module class:

context.Services.AddSingleton<IDistributedLockProvider>(sp =>
{
    var connection = ConnectionMultiplexer.Connect(configuration["Redis:Configuration"]);
    return new RedisDistributedSynchronizationProvider(connection.GetDatabase());
});

We are getting the Redis configuration from the appsettings.json file, so add the following lines to your appsettings.json file:

"Redis": {
    "Configuration": "127.0.0.1"
}

You can change the IP or customize the configuration based on your environment.

Configure the DbContext

Open your DbContext class, implement the IHasEventInbox and the IHasEventOutbox interfaces. You should end up by adding two DbSet properties into your DbContext class:

public DbSet<IncomingEventRecord> IncomingEvents { get; set; }
public DbSet<OutgoingEventRecord> OutgoingEvents { get; set; }

Add the following lines inside the OnModelCreating method of your DbContext class:

builder.ConfigureEventInbox();
builder.ConfigureEventOutbox();

It is similar for MongoDB; implement the IHasEventInbox and the IHasEventOutbox interfaces. There is no Configure... method for MongoDB.

Now, we've added inbox/outbox related tables to our database schema. Now, for EF Core, use the standard Add-Migration and Update-Database commands to apply changes into your database (you can skip this step for MongoDB). If you want to use the command-line terminal, run the following commands in the root directory of the database integration project:

dotnet ef migrations add "Added_Event_Boxes"
dotnet ef database update

Configure the distributed event bus options

As the last step, write the following configuration code inside the ConfigureServices method of your module class:

Configure<AbpDistributedEventBusOptions>(options =>
{
    options.Outboxes.Configure(config =>
    {
        config.UseDbContext<YourDbContext>();
    });
    
    options.Inboxes.Configure(config =>
    {
        config.UseDbContext<YourDbContext>();
    });
});

Replace YourDbContext with your DbContext class.

That's all. You can continue to publishing and consuming events just as before. See the distributed event bus documentation if you don't know how to use it.

Publishing events in transaction

The previous feature (outbox & inbox) solves the transactional event publishing problem for distributed systems. This feature, publishing events in transaction, solves the problem of executing event handlers in the same transaction that the events are published in for non-distributed applications. With 5.0, all events (local or distributed) are handled in the same transaction. If any handler fails, the transaction is rolled back. If you don't want that, you should use try/catch and ignore the exception inside your event handler.

Remember that if you don't install a real distributed event provider (like RabbitMQ or Kafka), the distributed events are actually executed in-process, just like the local events. So, with this development, all the events become transactional, even if your system is distributed or not.

No action needed to take. It will just work by default. There is a deprecation note related to this change (some pre-defined events will be removed in the next major version since they are not needed anymore)

Inactivating a user

The Identity module has a new feature to make a user active or inactive. Inactive users can not login to the system. In this way, you can disable a user account without deleting it. An Active checkbox is added to the user create/edit dialog to control it on the UI:

EF Core developers should add a new database migration since this brings a new field to the AbpUsers table.

Overriding email settings per tenant

If you're building a multi-tenant application, it is now possible to override email sending settings per tenant. To make this possible, you should first enable that feature to the tenant you want, by clicking the Actions -> Features for the tenant.

Enable the feature using the checkbox as shown in the following modal:

Then the tenant admin can open the email settings page under the Administration -> Settings menu (on development environment, logout, switch to the tenant and re-login with the tenant admin):

Hangfire dashboard permission

ABP allows to use Hangfire as the background job manager when you install the integration package as documented. Hangfire's dashboard is used to monitor and control the background job queues. Here, a screenshot from the dashboard:

Hangfire's dashboard is not authorized by default, so any user can navigate to the /hangfire URL and see/control the jobs. With the ABP version 5.0, we've added a built-in authorization implementation for the Hangfire dashboard. Instead of app.UseHangfireDashboard();, you can use the following middleware configuration:

app.UseHangfireDashboard("/hangfire", new DashboardOptions
{
    AsyncAuthorization = new[] { new AbpHangfireAuthorizationFilter() }
});

In this way, only the authenticated users can see the dashboard. However, we suggest to set a permission name, so only the users with that permission can see the dashboard:

app.UseHangfireDashboard("/hangfire", new DashboardOptions
{
    AsyncAuthorization = new[] {
        new AbpHangfireAuthorizationFilter("MyPermissionName")
    }
});     

You can define the permission (MyPermissionName in this example) using the standard permission system.

Introducing AbpControllerBase

ABP provides an AbpController class that you can inherit your MVC controllers from. It provides some pre-injected services to simplify your controllers. With v5.0, we are adding a second base controller class, AbpControllerBase, which is more proper to create API controllers (without view features). It is suggested to inherit from the AbpControllerBase class to create API controllers, instead of the AbpController class.

Example:

[Route("api/products")]
public class ProductController : AbpControllerBase
{
    // TODO: ...
}

Automatically setting the TenantId for new entities

Beginning from the version 5.0, ABP automatically sets the TenantId for you when you create a new entity object (that implements the IMultiTenant interface). It is done in the constructor of the base Entity class (all other base entity and aggregate root classes are derived from the Entity class). The TenantId is set from the current value of the ICurrentTenant.Id property.

Previously, it was a responsibility of the developer to set TenantId for new entities. Now, ABP takes care of it. You only may need to set it if you want to set id of a tenant other than the current tenant.

This can be a breaking change in rare cases (for example, if you create host side entities from a tenant context and do not explicitly set host entity's TenantId to null).

Community News

ABP Community Talks 2021.12

As the core ABP development team, we've decided to organize monthly live meetings with the ABP community. The first live meeting will be at December 16, 2021, 17:00 (UTC) on YouTube. ABP core team members will present some of the new features coming with ABP 5.0.

Join this event on the Kommunity platform: https://kommunity.com/volosoft/events/abp-community-talks-4afca9c9

You can also subscribe to the Volosoft channel for reminders for further ABP events and videos.

ASP.NET Community Startup!

It was great for us to be invited to Microsoft's ASP.NET Community Weekly Standup show, at September 28. There was a very high attention and that made us very happy. Thanks to the ABP Community and all the watchers :) If you've missed the talk, you can watch it here.

Upcoming ABP Book!

I am currently authoring the first official book for the ABP Framework and it is on pre-sale on Amazon now.

This books is a complete guide to start working with the ABP Framework, explore the ABP features and concepts. It also contains chapters for DDD, modular application development and multi-tenancy to learn and practically work with the ABP architecture to build maintainable software solutions and create SaaS applications. The book will be based on ABP 5.0 and published in the beginning of 2022. You can pre-order now!

New ABP Community posts

Here, some of the latest posts added to the ABP community:

• Many to many relationship with ABP and EF Core
• Add a new module to your ABP application
• Changing UI Theme for ABP MVC / Razor Pages UI
• Create a Windows Service with the ABP Framework
• Deploy ABP Framework .NET Core tiered application to docker swarm
• Centralized logging for .NET Core ABP microservices application using Seq

Thanks to the ABP Community for all the contents they have published. You can also post your ABP and .NET related (text or video) contents to the ABP Community.

Conclusion

The ABP version 5.0 is coming with important changes (like .NET 6 and Bootstrap 5) and features. In this blog post, I summarized the news about that new version. Please try it and provide feedback by opening issues on the GitHub repository. Thank you all!

What's New With 4.4?

Since all the new features are already explained in details with the 4.4 RC announcement posts, I will not repeat all the details again. See the related blog post for all the features and enhancements.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

Run this command in the root folder of your solution.

The Road Map

The next feature version will be 5.0. It is planned to release the 5.0 RC (Release Candidate) in November 2021. See the updated road maps;

• ABP Framework Road Map
• ABP Commercial Road Map

The planned release date for the 4.4.0 final version is July 27, 2021.

Get Started with the 4.4 RC

If you want to try the version 4.4.0 today, follow the steps below;

1. Upgrade the ABP CLI to the version 4.4.0-rc.2 using a command line terminal:

dotnet tool update Volo.Abp.Cli -g --version 4.4.0-rc.2

or install if you haven't installed before:

dotnet tool install Volo.Abp.Cli -g --version 4.4.0-rc.2

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

Migration Notes

There is no breaking change with this version. However, if you are using Entity Framework Core, you will need to run the Add-Migration command to add a new database migration since some changes done in the module database mappings.

What's new with the ABP Framework 4.4

Removed EntityFrameworkCore.DbMigrations Project

With this version, we are doing an important change in the application startup solution template. The startup solution was containing an EntityFrameworkCore.DbMigrations project that contains a separate DbContext class which was responsible to unify the module database mappings and maintain the code-first database migrations. With the v4.4, we've removed that project from the solution. In the new structure, the EntityFrameworkCore integration project will be used for database migrations as well as on runtime.

We'd published a community article about that change. Please see the article to understand the motivation behind the change.

Beside the DbContext unification, we've also used the new ReplaceDbContext attribute and replaced the IIdentityDbContext and ITenantManagementDbContext interfaces to make it possible to perform join queries over repositories for these modules easily. In the next days, we will publish another community article to explain the problem and the solution. However, most of times, you don't need to know these details.

Dynamic Menu Management for the CMS Kit Module

CMS Kit is a set of reusable Content Management System features packaged as an ABP application module. We had published the first usable version with the previous release. With this release, we are adding another feature to the CMS Kit module: You can now dynamically arrange the main menu on the UI, which is an essential feature for any kind of content management system. In this way, you can add pages or any kind of arbitrary URLs to the main menu from the UI.

A screenshot from the menu management page (from the CMS Kit admin side):

And the items rendered in a public website:

Note that this feature is also available with the open source CMS Kit module (while the screenshots have been taken from the ABP Commercial).

Razor Engine Support for Text Templating

Text Templating is a system to generate content on runtime by using a model (data) and a template. It was running on the Scriban templating engine. Beginning from this version, we have a second option: We can use the familiar razor syntax to build and render the templates. See the text templating razor integration document to get started with the new engine!

New Customization Points for DbContext/Entities

Two new extension methods are added to ObjectExtensionManager.Instance to override EF Core mappings of pre-built application modules.

Example: Change mappings for the IdentityDbContext to override mappings for the IdentityUser entity

ObjectExtensionManager.Instance.MapEfCoreDbContext<IdentityDbContext>(modelBuilder =>
{
    modelBuilder.Entity<IdentityUser>(b =>
    {
        b.ToTable("MyUsers");
        b.Property(x => x.Email).HasMaxLength(300);
    });
});

The startup template contains a class, like YourProjectNameEfCoreEntityExtensionMappings, that can be used to place that code.

New ABP CLI Commands

There are new ABP CLI commands introduced with the v4.4:

• abp install-libs command is used for MVC / Razor Pages and Blazor Server applications to restore the wwwroot/libs folder. Previously we were running the yarn and gulp commands to restore that folder. While the install-libs command still uses yarn (if available), it is no longer needed to use gulp.
• abp prompt command can be used to open a prompt for the ABP CLI and run multiple commands without needing to specify the abp command every time. For example, if you run abp prompt, then you can directly run install-libs instead of abp install-libs. Use exit to quit from the ABP prompt.
• abp batch command can be used to run multiple ABP commands with one command. Prepare a text file, write each command as a line (without the abp command prefix), then execute abp batch <batch-file> (ex: abp batch your_commands.txt) command to execute all the commands in that file.

appsettings.secrets.json

Added appsettings.secrets.json to the startup template that can be used to set your sensitive/secret configuration values. You can ignore this file from source control (by adding to .gitignore if you're using git) and keep it only in developer/production machines.

Other ABP Framework Improvements

• #9350 Extracted IRemoteServiceConfigurationProvider to get remote service configurations. You can replace this service to get the configuration from any source.
• #8829 Implemented error handler and retry for distributed event bus.
• #9288 Use default CORS policy instead of a named one in the startup template. It is suggested to update your own solutions to make it simpler.
• Translated the framework and module localization strings to Hindi, Italian (thanks to Emanuele Filardo), Finnish, French and Slovak (thanks to Michal Čadecký) languages.

Beside these, there are a lot of enhancements and bug fixes. See the 4.4-preview milestone for all issues and pull requests closed with this version.

What's new with the ABP Commercial 4.4

New Features for the SaaS Module

We've implemented some important features to the SaaS module:

• Integrated to the Payment module and implemented subscription system for the SaaS module.
• Allow to make a tenant active/passive. In this way, you can take a tenant to passive to prevent the users of that tenant from using the system. In addition, you can set a date to automatically make a tenant passive when the date comes.
• Allow to limit user count for a tenant.
• Allow to set different connection strings for a tenant for each database/module, which makes possible to create different databases for a tenant for each microservice in a microservice solution.

New ABP Suite Code Generation Features

There are many improvements done for for ABP Suite, including CRUD page generation for the microservice solution template.

Angular UI: Two Factor Authentication for the Resource Owner Password Flow

In the previous version, we had implemented the resource owner password authentication flow for the Angular UI, which makes the login process easier for simpler applications. With this release, we've implemented two-factor authentication for that flow. Authorization code flow already supports 2FA.

Other ABP Commercial Improvements

• Added web layers to microservices in the microservice solution. You can use them to create modular UI or override existing pages/components of pre-built modules (e.g. Identity and SaaS).
• ABP Commercial license code has been moved to appsettings.secrets.json in the new startup templates.

Beside these, there are many minor improvements and fixes done in the modules and themes.

Other News

In this section, I will share some news that you may be interested in.

New Article: Using Elsa Workflow with ABP Framework

We have been frequently asked how to use Elsa Workflows with the ABP Framework. Finally, we have created an article to demonstrate it.

You can check it to see how to integrate Elsa into an ABP based solution easily.

Free E-Book: Implementing Domain Driven Design

We've published a free e-book for the ABP Community in the beginning of June. This is a practical guide for implementing Domain Driven Design (DDD). While the implementation details are based on the ABP Framework infrastructure, the basic concepts, principles and models can be applied to any solution, even if it is not a .NET solution.

Thousands of copies are already downloaded. If you haven't seen it yet, click here to get a free copy of that e-book.

The LeptonX Theme

We have been working on a new ABP theme, named the LeptonX, for a long time. The theme will be available for ABP Framework (free - lite version) and ABP Commercial (pro version). It is being finalized in the next weeks and we will release the first version in a short time.

See this blog post to learn more about that project.

Volosoft & .NET Foundation

Volosoft, the company leads the ABP Framework project, has been a corporate sponsor of the .NET Foundation. We are happy by taking our place among other great sponsors!

We will continue to contribute to and support open source! See this blog post for the announcement.

Looking for Developer Advocate(s)

We are actively looking for professional developer advocates for the ABP.IO platform. If you want to create content and touch to the ABP community, please check our job post.

About the Next Version

The next version will be a major version: 5.0, which will be based on .NET 6.0. We are planning to release it in the end of 2021, short time after the .NET 6.0 release. We will release multiple preview/beta versions before the RC version. See the road map for details of the planned works for the version 5.0.

This article shows how to remove the EntityFrameworkCore.DbMigrations project from your solution to have a single DbContext for your database mappings and code first migrations.

Source Code

You can find source of the example solution used in this article here.

Motivation

If you create a new solution with Entity Framework Core as the database provider, you see two projects related to EF Core:

• EntityFrameworkCore project contains the actual DbContext of your application. It includes all the database mappings and your repository implementations.
• EntityFrameworkCore.DbMigrations project, on the other hand, contains another DbContext class that is only used to create and apply the database migrations. It contains the database mappings for all the modules you are using, so have a single, unified database schema.

There were two main reasons we'd created such a separation;

1. Your actual DbContext remains simple and focused. It only contains your own entities and doesn't contain anything related to the modules that are used by the application.
2. You can create your own classes that map to the tables of depending modules. For example, the AppUser entity (that is included in the downloaded solution) is mapped to AbpUsers table in the database, which is actually mapped to the IdentityUser entity of the Identity Module. That means they share the same database table. AppUser includes less properties compared to IdentityServer. You only add the properties you need, not more. This also allows you to add new standard (type-safe) properties to the AppUser for your custom requirements as long as you carefully manage the database mappings.

We've documented the structure in details. However, it has always been a problem for the developers since that structure makes your database mappings complicated when you re-use tables of the depended modules. Many developers are misunderstanding or making mistakes while mapping such classes, especially when they try to use these entities in relations to other entities.

So, we've decided to cancel that separation and remove the EntityFrameworkCore.DbMigrations project in the version 4.4. New startup solutions will come with a single EntityFrameworkCore project and single DbContext class.

If you want to make it in your solution with today, follow the steps in this article.

Warnings

There is one drawback with the new design (everything in software development is a trade-off). We need to remove the AppUser entity, because EF Core can't map two classes to single table without an inheritance relation. I will cover this later in this article and provide suggestions to deal with it.

If you are using ABP Commercial, ABP Suite code generation won't work correctly before the version 4.4. Please upgrade to v4.4 if you are using a previous version.

The Steps

Our goal to enable database migrations in the EntityFrameworkCore project, remove the EntityFrameworkCore.DbMigrations project and revisit the code depending on that package.

I've created a new solution with v4.3, then made all the changes in a pull request, so you can see all the changes line by line. While this article will cover all, you may want to check the changes done in this PR if you have problems with the implementation.

1) Add Microsoft.EntityFrameworkCore.Tools package to the EntityFrameworkCore project

Add the following code into the EntityFrameworkCore.csproj file:

<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="5.0.*">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    <PrivateAssets>compile; contentFiles; build; buildMultitargeting; buildTransitive; analyzers; native</PrivateAssets>
  </PackageReference>
</ItemGroup>

2) Create design time DbContext factory

Create a class implementing IDesignTimeDbContextFactory<T> inside the EntityFrameworkCore project:

using System.IO;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;
using Microsoft.Extensions.Configuration;

namespace UnifiedContextsDemo.EntityFrameworkCore
{
    public class UnifiedContextsDemoDbContextFactory : IDesignTimeDbContextFactory<UnifiedContextsDemoDbContext>
    {
        public UnifiedContextsDemoDbContext CreateDbContext(string[] args)
        {
            UnifiedContextsDemoEfCoreEntityExtensionMappings.Configure();

            var configuration = BuildConfiguration();

            var builder = new DbContextOptionsBuilder<UnifiedContextsDemoDbContext>()
                .UseSqlServer(configuration.GetConnectionString("Default"));

            return new UnifiedContextsDemoDbContext(builder.Options);
        }

        private static IConfigurationRoot BuildConfiguration()
        {
            var builder = new ConfigurationBuilder()
                .SetBasePath(Path.Combine(Directory.GetCurrentDirectory(), "../UnifiedContextsDemo.DbMigrator/"))
                .AddJsonFile("appsettings.json", optional: false);

            return builder.Build();
        }
    }
}

I basically copied from the EntityFrameworkCore.DbMigrations project, renamed and uses the actual DbContext of the application.

3) Create DB schema migrator

Copy EntityFrameworkCore...DbSchemaMigrator (... standard for your project name) class to the EntityFrameworkCore project and change the code in the MigrateAsync method to use the actual DbContext of the application. In my case, the final class is shown below:

using System;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using UnifiedContextsDemo.Data;
using Volo.Abp.DependencyInjection;

namespace UnifiedContextsDemo.EntityFrameworkCore
{
    public class EntityFrameworkCoreUnifiedContextsDemoDbSchemaMigrator
        : IUnifiedContextsDemoDbSchemaMigrator, ITransientDependency
    {
        private readonly IServiceProvider _serviceProvider;

        public EntityFrameworkCoreUnifiedContextsDemoDbSchemaMigrator(
            IServiceProvider serviceProvider)
        {
            _serviceProvider = serviceProvider;
        }

        public async Task MigrateAsync()
        {
            /* We intentionally resolving the UnifiedContextsDemoMigrationsDbContext
             * from IServiceProvider (instead of directly injecting it)
             * to properly get the connection string of the current tenant in the
             * current scope.
             */

            await _serviceProvider
                .GetRequiredService<UnifiedContextsDemoDbContext>()
                .Database
                .MigrateAsync();
        }
    }
}

4) Move module configurations

The migrations DbContext typically contains code lines like builder.ConfigureXXX() for each module you are using. We can move these lines to our actual DbContext in the EntityFrameworkCore project. Also, remove the database mappings for the AppUser (we will remove this entity). Optionally, you may move the database mappings code for your own entities from ...DbContextModelCreatingExtensions class in the OnModelCreating method of the actual DbContext, and remove the static extension class.

For the example solution, the final DbContext class is shown below:

using Microsoft.EntityFrameworkCore;
using UnifiedContextsDemo.Users;
using Volo.Abp.AuditLogging.EntityFrameworkCore;
using Volo.Abp.BackgroundJobs.EntityFrameworkCore;
using Volo.Abp.Data;
using Volo.Abp.EntityFrameworkCore;
using Volo.Abp.FeatureManagement.EntityFrameworkCore;
using Volo.Abp.Identity.EntityFrameworkCore;
using Volo.Abp.IdentityServer.EntityFrameworkCore;
using Volo.Abp.PermissionManagement.EntityFrameworkCore;
using Volo.Abp.SettingManagement.EntityFrameworkCore;
using Volo.Abp.TenantManagement.EntityFrameworkCore;

namespace UnifiedContextsDemo.EntityFrameworkCore
{
    [ConnectionStringName("Default")]
    public class UnifiedContextsDemoDbContext
        : AbpDbContext<UnifiedContextsDemoDbContext>
    {
        public DbSet<AppUser> Users { get; set; }

        /* Add DbSet properties for your Aggregate Roots / Entities here.
         * Also map them inside UnifiedContextsDemoDbContextModelCreatingExtensions.ConfigureUnifiedContextsDemo
         */

        public UnifiedContextsDemoDbContext(
            DbContextOptions<UnifiedContextsDemoDbContext> options)
            : base(options)
        {

        }

        protected override void OnModelCreating(ModelBuilder builder)
        {
            base.OnModelCreating(builder);

            builder.ConfigurePermissionManagement();
            builder.ConfigureSettingManagement();
            builder.ConfigureBackgroundJobs();
            builder.ConfigureAuditLogging();
            builder.ConfigureIdentity();
            builder.ConfigureIdentityServer();
            builder.ConfigureFeatureManagement();
            builder.ConfigureTenantManagement();

            /* Configure your own tables/entities inside here */

            //builder.Entity<YourEntity>(b =>
            //{
            //    b.ToTable(UnifiedContextsDemoConsts.DbTablePrefix + "YourEntities", UnifiedContextsDemoConsts.DbSchema);
            //    b.ConfigureByConvention(); //auto configure for the base class props
            //    //...
            //});
        }
    }
}

5) Remove EntityFrameworkCore.DbMigrations project from the solution

Remove the EntityFrameworkCore.DbMigrations project from the solution and replace references given to that project by the EntityFrameworkCore project reference.

Also, change usages of ...EntityFrameworkCoreDbMigrationsModule to ...EntityFrameworkCoreModule (... stands for your project name).

In this example, I had to change references and usages in the DbMigrator, Web and EntityFrameworkCore.Tests projects.

6) Remove AppUser Entity

We need to remove the AppUser entity, because EF Core can't map two classes to single table without an inheritance relation. So, remove this class and all the usages. You can replace the usages with IdentityUser if you need to query users in your application code. See The AppUser Entity & Custom Properties section for more info.

7) Create or move the migrations

We've removed the EntityFrameworkCore.DbMigrations project. What about the migrations created and applied into the database until now? If you want to keep your migrations history, copy all the migrations from the EntityFrameworkCore.DbMigrations project to the EntityFrameworkCore project and manually change the DbContext type in the designer classes.

If you want to clear the migrations history, but continue with the migrations already applied to the database, create a new database migration in the EntityFrameworkCore project, executing the following command in a command-line terminal in the directory of that project:

dotnet ef migrations add InitialUnified

You can specify a different migration name, surely. This will create a migration class that contains all the database tables you already have in the database. Keep calm and delete all the content in the Up and Down methods. Then you can apply the migration to the database:

dotnet ef database update

Your database won't have any change, because the migration is just empty and does nothing. From now, you can create new migrations as you change your entities, just like you normally do.

All the changes are done. The next section explains how to add custom properties to entities of depending modules with this design.

The AppUser Entity & Custom Properties

The database mapping logic, solution structure and migrations become much simpler and easier to manage with that new setup.

As a drawback, we had to remove the AppUser entity, which was sharing the AbpUsers table with the IdentityUser entity of the Identity Module. Fortunately, ABP provides a flexible system to extend existing entities in case of you need to define some custom properties. In this section, I will show how to add a custom property to the IdentityUser entity and use it in your application code and database queries.

I've done all the changes in this part as a single PR, so you may want to check the changes done in this PR if you have problems with the implementation.

Defining a Custom Property

The application startup template provides a point to configure the custom properties for existing entities, which is located under Domain.Shared project, in the ...ModuleExtensionConfigurator.cs (... standard for your project name) class. Open that class and add the following code into the ConfigureExtraProperties method:

ObjectExtensionManager.Instance.Modules()
    .ConfigureIdentity(identity =>
    {
        identity.ConfigureUser(user =>
        {
            user.AddOrUpdateProperty<string>( //property type: string
                "SocialSecurityNumber", //property name
                property =>
                {
                    //validation rules
                    property.Attributes.Add(new RequiredAttribute());
                    property.Attributes.Add(new StringLengthAttribute(64));
                }
            );
        });
    });

After that setup, just run the application to see the new property on the Users table:

The new SocialSecurityNumber property will also be available on the create and edit modals with the validation rules.

See the Module Entity Extensions document to understand and control the new custom property with all the details.

Mapping to the Database Table

By default, ABP saves all custom properties inside the ExtraProperties field as a single JSON object. If you prefer to create a table field for a custom property, you can configure it in the ...EfCoreEntityExtensionMappings.cs (... standard for your project name) class in the EntityFrameworkCore project. You can write the following code inside this class (in the OneTimeRunner.Run):

ObjectExtensionManager.Instance
    .MapEfCoreProperty<IdentityUser, string>(
        "SocialSecurityNumber",
        (entityBuilder, propertyBuilder) =>
        {
            propertyBuilder.HasMaxLength(64).IsRequired().HasDefaultValue("");
        }
    );

After that, you can just run the following command in a command-line terminal to add a new database migration (in the directory of the EntityFrameworkCore project):

dotnet ef migrations add Added_SocialSecurityNumber_To_IdentityUser

This will add a new migration class to your project. You can then run the following command (or run the .DbMigrator application) to apply changes to the database:

dotnet ef database update

This will add a SocialSecurityNumber field to the AbpUsers table in the database.

Using Custom Properties in the Application Code

Now, we can use GetProperty and SetProperty methods on the IdentityUser entity to work with the new property. The following code demonstrates to get/set the custom property:

public class MyUserService : ITransientDependency
{
    private readonly IRepository<IdentityUser, Guid> _userRepository;

    public MyUserService(IRepository<IdentityUser, Guid> userRepository)
    {
        _userRepository = userRepository;
    }

    public async Task SetSocialSecurityNumberDemoAsync(string userName, string number)
    {
        var user = await _userRepository.GetAsync(u => u.UserName == userName);
        user.SetProperty("SocialSecurityNumber", number);
        await _userRepository.UpdateAsync(user);
    }

    public async Task<string> GetSocialSecurityNumberDemoAsync(string userName)
    {
        var user = await _userRepository.GetAsync(u => u.UserName == userName);
        return user.GetProperty<string>("SocialSecurityNumber");
    }
}

Tip: Using SetProperty and GetProperty with a string property name everywhere could be tedious and error-prone. I suggest you to create the following extension methods:

public static class MyUserExtensions
{
    public const string SocialSecurityNumber = "SocialSecurityNumber";

    public static void SetSocialSecurityNumber(this IdentityUser user, string number)
    {
        user.SetProperty(SocialSecurityNumber, number);
    }
    
    public static string GetSocialSecurityNumber(this IdentityUser user)
    {
        return user.GetProperty<string>(SocialSecurityNumber);
    }
}

Then we can change the previous demo method as shown below:

public async Task SetSocialSecurityNumberDemoAsync(string userName, string number)
{
    var user = await _userRepository.GetAsync(u => u.UserName == userName);
    user.SetSocialSecurityNumber(number); //Using the new extension property
    await _userRepository.UpdateAsync(user);
}

public async Task<string> GetSocialSecurityNumberDemoAsync(string userName)
{
    var user = await _userRepository.GetAsync(u => u.UserName == userName);
    return user.GetSocialSecurityNumber(); //Using the new extension property
}

Querying Based on a Custom Property

You may want to query users based on SocialSecurityNumber. We will use Entity Framework's API to accomplish that. You have two options to use EF Core API in your application code:

1. Reference to the Microsoft.EntityFrameworkCore NuGet package from your project (domain or application layer, depending on where you want to use the EF Core API).
2. Create a repository interface in the domain layer and implement it in your EntityFrameworkCore project.

I will prefer the second approach, so I am defining a new repository interface in the Domain project:

using System;
using System.Threading.Tasks;
using Volo.Abp.Domain.Repositories;
using Volo.Abp.Identity;

namespace UnifiedContextsDemo.Users
{
    public interface IMyUserRepository : IRepository<IdentityUser, Guid>
    {
        Task<IdentityUser> FindBySocialSecurityNumber(string number);
    }
}

Then implementing it in the EntityFrameworkCore project:

using System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;
using UnifiedContextsDemo.EntityFrameworkCore;
using Volo.Abp.Domain.Repositories.EntityFrameworkCore;
using Volo.Abp.EntityFrameworkCore;
using Volo.Abp.Identity;

namespace UnifiedContextsDemo.Users
{
    public class MyUserRepository 
        : EfCoreRepository<UnifiedContextsDemoDbContext, IdentityUser, Guid>, 
          IMyUserRepository
    {
        public MyUserRepository(
            IDbContextProvider<UnifiedContextsDemoDbContext> dbContextProvider) 
            : base(dbContextProvider)
        {
        }

        public async Task<IdentityUser> FindBySocialSecurityNumber(string number)
        {
            var dbContext = await GetDbContextAsync();
            return await dbContext.Set<IdentityUser>()
                .Where(u => EF.Property<string>(u, "SocialSecurityNumber") == number)
                .FirstOrDefaultAsync();
        }
    }
}

Tip: Use the constant instead of SocialSecurityNumber as a magic string.

Now, I can use that repository method in my service by injecting the IMyUserRepository:

public class MyUserService : ITransientDependency
{
    private readonly IMyUserRepository _userRepository;

    public MyUserService(IMyUserRepository userRepository)
    {
        _userRepository = userRepository;
    }

    //...other methods

    public async Task<IdentityUser> FindBySocialSecurityNumberDemoAsync(string number)
    {
        return await _userRepository.FindBySocialSecurityNumber(number);
    }
}

I changed IRepository<IdentityUser, Guid> dependency to IMyUserRepository.

Conclusion

With this article, I wanted to show you how to remove the EntityFrameworkCore.DbMigrations project from your solution to simplify your database mappings, database migrations and your application code. In the next version (4.4), this will be the default approach.

Source Code

You can find source of the example solution used in this article here.

What's New With 4.3?

Since all the new features are already explained in details with the 4.3 RC announcement posts, I will not repeat all the details again. See the related blog posts for all the features and enhancements;

• What's New with the ABP Framework 4.3
• What's new with the ABP Commercial 4.3

The Quick Start Tutorial

With this version, we've created a minimalist quick start tutorial for developers who are new to the ABP Framework.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

Run this command in the root folder of your solution.

Migration Guides

Check the migration guides (for ABP Framework & for ABP Commercial) for the applications with the version 4.2.x upgrading to the version 4.3.0.

The Road Map

The next feature version will be 4.4. It is planned to release the 4.4 RC (Release Candidate) at the end of Quarter 2, 2021. See the updated road maps;

• ABP Framework Road Map
• ABP Commercial Road Map

• The microservice starter template is getting more mature. We've also added a service template to add new microservices to the solution.
• New option for the application starter template to have a separate database schema for tenant databases.
• New Forms module to create surveys
• Enable/disable modules per edition/tenant.
• Lepton theme and Account module's source codes are available with the Team License.

Here, some other features already covered in the ABP Framework announcement, but worth mentioning here since they are also implemented for the ABP Commercial;

• Blazor UI server-side support
• Email setting management UI
• Module extensibility system is now available for the Blazor UI too.

This post doesn't cover the features and changes done on the ABP Framework side. Please also see the ABP Framework 4.3. RC blog post.

The Migration Guide

This upgrade requires some manual work documented in the migration guide. Please read the guide carefully. Even if your application doesn't break on upgrade, you should apply the changes to avoid future release problems.

Known Issues

If you upgrade the ABP CLI to 4.3.0-rc.1 and try to create a new solution using the stable (4.2.x) version, it won't compile because of some missing packages. Use ABP CLI to create solutions with --preview option and downgrade to 4.2.2 to create 4.2.2 solutions. This will be fixed in 4.3.0-rc.2.

What's New With The ABP Commercial 4.3

The Microservice Starter Template

We'd introduced an initial version of the microservice starter template in the previous version. It is getting more mature with this release. We've made a lot of improvements and changes, including;

• New "service" template to add new microservices for the solution. It still requires some manual work to integrate to other services and gateways; however, it makes progress very easy and straightforward.
• Added Tye configuration to develop and test the solution easier.
• Added Prometheus, Grafana integrations for monitoring the solution.
• Automatic database migrations. Every microservice automatically checks and migrates/seeds its database on startup (concurrency issues are resolved for multiple instances). For multi-tenant systems, tenant databases are also upgraded by the queue.
• For multi-tenant systems, databases are being created on the fly for new tenants with separate connection strings.
• Created separate solution (.sln) file for each microservice, gateway, and application. In this way, you can focus on what you are working on. The main (roof) solution file only includes the executable projects in these solutions.
• All microservices are converted to the standard layered module structure, making it easier to align with ABP application development practices.

After this release, we will be preparing microservice development guides based on this startup solution.

Separate Tenant Schema

ABP's multi-tenancy system allows to the creation of dedicated databases for tenants. However, the application startup solution comes with a single database migration path; hence it has a single database schema. As a result, tenant databases have some host-related tables. These tables are not used for tenants, and they are always empty. However, their existence may disturb us as a clean developer.

With this release, the application startup template provides an option to address this problem. So, if you want, you can have a separate migration path for tenant databases. Of course, this has a cost; You will have two DbContexts for migration purposes, bringing additional complexity to your solution. We've done our best to reduce this complexity and added a README file into the migration assembly. If you prefer this approach, please check that README file.

You can specify the new --separate-tenant-schema parameter while you are creating a new solution using the ABP CLI:

abp new Acme.BookStore --separate-tenant-schema

If you prefer the ABP Suite to create solutions, you can check the Separated tenant schema option.

Creating Tenant Databases On The Fly

With this release, the separate tenant database feature becomes more mature. When you create a new tenant with specifying a connection string, the new database is automatically created with all the tables and the initial seed data if available. So, tenants can immediately start to use the new database. With this change, tenant connection string textboxes come in the tenant creation modal:

Besides, we've added an "Apply database migrations" action to the tenant management UI to manually trigger the database creation & migration in case you have a problem with automatic migration:

Automatic migration only tries one time. If it fails, it writes the exception log and discards this request. For example, this can happen if the connection string is wrong or the database server is not available. In this case, you can manually retry with this action.

Note that this feature requires to make changes in your solution, if you upgrade from an older version. Because the tenant database creation and migration code are located in the application startup template. See the version 4.3 migration guide for details.

New Module: CMS Kit

CMS Kit module initial version has been released with this version. As stated in the ABP Framework 4.3 announcement post, it should be considered premature for now.

For ABP Commercial application startup template, we are providing an option to include the CMS Kit into the solution while creating new solutions:

It is available only if you select the Public web site option. Once you include CMS Kit, a Cms item is shown on the menu:

Each CMS Kit feature can be individually enabled/disabled, using the global feature system. Once you disable a feature, it becomes completely invisible; even the related tables are not included in your database.

CMS Kit features are separated into two categories: Open source (free) features and pro (commercial) features. For now, only newsletter and contact form features are commercial. By the time, we will add more free and commercial features.

We will create a separate blog post for the CMS Kit module, so I keep it short.

New Module: Forms

Forms is a new module that is being introduced with this version. It looks like the Google Forms application; You dynamically create forms on the UI and send them to people to answer. Then you can get statistics/report and export answers to a CSV file.

Forms module currently supports the following question types;

• Free text
• Selecting a single option from a dropdown list or a radio button list
• Multiple choice: Selecting multiple options from a checkbox list

Screenshot: editing form and questions - view responses

Screenshot: answering to the form

Team License Source Code for Modules

Team License users can't access the source code of modules and themes as a license restriction. You have to buy a Business or Enterprise license to download any module/theme's full source code. However, we got a lot of feedback from the Team License owners on the source code of the account module and the lepton theme. We see that customization of these two modules is highly necessary for most of our customers.

With this version, we decided to allow Team License holders to download the source code of the Account Module and the Lepton Theme to freely customize them based on their requirements.

You can Replace these modules with their source code using the ABP Suite:

Remember that; when you include the source code in your solution, it is your responsibility to upgrade them when we release new versions (while you don't have to upgrade them).

Lepton Theme Public Website Layout

We'd added a public website application in the application starter template in the previous versions. It was using the public website layout of the Lepton Theme. We realized that the layout of this application is customized or completely changed in most of the solutions. So, with this version, the layout is included inside the application in the downloaded solution. You can freely change it. Before, you had to download it separately and include it in your solution manually.

Enable/Disable Modules

With this release, all modules can be enabled/disabled per edition/tenant. You can allow/disallow modules when you click Features action for an edition or tenant:

Other Features/Changes

• ABP Suite now supports defining required navigation properties on code generation.
• Blazor server-side (with tiered option) is added for the application and microservice starter templates.
• An "Email" tab has been added to the Settings page to configure the email settings.

Feedback

Please check out the ABP Commercial 4.3 RC to help us to release a more stable version. The planned release date for the 4.3.0 final version is April 21, 2021.

Notice that the version 4.3.0 stable has already been released. We've updated the version usages in this post.

We are super excited to announce the ABP Framework 4.3 RC (Release Candidate). Here, a list of highlights of this release;

• CMS Kit module initial release.
• Blazor UI server-side support.
• Module extensibility system for the Blazor UI.
• Angular UI resource owner password flow comes back.
• Volo.Abp.EntityFrameworkCore.Oracle package is now compatible with .NET 5.
• CLI support to easily add the Basic Theme into the solution.
• New IInitLogger service to write logs before dependency injection phase completed.

Besides the new features above, we've done many performance improvements, enhancements and bug fixes on the current features. See the 4.3 milestone on GitHub for all changes made on this version.

This version was a big development journey for us; ~160 issues resolved, ~300 PRs merged and ~1,700 commits done only in the main framework repository. Thanks to the ABP Framework team and all the contributors.

ABP Commercial 4.3 RC has also been published. We will write a separate blog post for it.

The Migration Guide

We normally don't make breaking changes in feature versions. However, this version has some small breaking changes mostly related to Blazor UI WebAssembly & Server separation. Please check the migration guide while upgrading to version 4.3.

Known Issues

Some minor issues will be fixed in the stable release. You can see the known issues here.

Get Started With The 4.3

If you want to try version 4.3 today, follow the steps below;

1. Upgrade the ABP CLI to the version 4.3.0 using a command-line terminal:

dotnet tool update Volo.Abp.Cli -g --version 4.3.0

or install if you haven't installed before:

dotnet tool install Volo.Abp.Cli -g --version 4.3.0

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

Quick Start Tutorial

If you are new to ABP Framework, we've prepared a new quick start tutorial that can be pretty helpful to warm up to the ABP Framework.

What's New With The ABP Framework 4.3

CMS Kit

CMS (Content Management System) Kit was a module we worked on for the last couple of months. It is usable now, and we are releasing the initial version with this release. We are considering this module as pre-mature. It will be improved in the next versions. The goal to provide a flexible and extensible CMS infrastructure to .NET community. It currently has the following features;

• Pages: Used to create UI pages with a Markdown + WYSIWYG editor. Once you create a page, it becomes available via URL like /pages/my-page-url.
• Blog: A built-in blog system that supports multiple blogs with blog posts.
• Comments: Allows users to write comments under contents. It is used for blog posts.
• Tags: To add tag feature to any content/entity. It is used for blog posts.
• Reactions: Allows users to react to content via emojis, like a smile, upvote, downvote, etc.
• Rating: This component is used to rate content by users.

All features are separately usable. For example, you can create an image gallery and reuse the Comments and Tags features for the images. You can enable/disable features individually using the Global Features System.

We will create a separate blog post for the CMS Kit module, so I keep it short.

Blazor Server Side

We'd implemented Blazor WebAssembly before. With version 4.3, we have the Blazor Server-Side option too. All the current functionalities are available to the Blazor Server.

You can select Blazor Server as the UI type while creating a new solution.

Example:

abp new Acme.BookStore -u blazor-server

If you write blazor as the UI type, it will create Blazor WebAssembly just as before.

You can also select the Blazor Server on the get started page.

Blazor Server applications are mixed applications; You can mix the server-side MVC / Razor Pages with the Blazor SPA. This brings an interesting opportunity: MVC / Razor Pages modules can work seamlessly in the Blazor Server applications. For example, the CMS Kit module has no Blazor UI yet, but you can use its MVC UI inside your Blazor Server application.

Blazor Server UI has a --tiered option just like the MVC / Razor Pages UI. This can be used to separate the HTTP API server from the UI server (UI application doesn't directly connect to the database).

Blazor UI Module Extensibility

Module Entity Extensions and some other extensibility features was not supported by the Blazor UI. With this version, we've implemented that system for Blazor UI.

For anyone wondering what the module entity extensions is, please check the document or this community video.

Email Setting Management UI

With this release, a new item is added to the main menu to navigate to the setting management page. This page contains the email setting management UI, as shown below:

The setting page is provided by the setting management module, and it is extensible; You can add your tabs to this page for your application settings.

Angular UI Resource Owner Password Flow

The login page was removed from the Angular UI in previous versions because Authorization Code flow is the recommended approach for SPAs. However, it requires redirecting the user to the authentication server, logging there, and returning to the application. We got a lot of feedback because this brings overhead for simple applications.

With version 4.3, Angular UI can use its login page with resource owner password flow. Please refer to the documentation to learn how to make it work.

Volo.Abp.EntityFrameworkCore.Oracle Package

We couldn't update the Oracle.EntityFrameworkCore package on .NET 5.0 upgrade since it was not supporting .NET 5.0 at that time. Now, it supports .NET 5.0 and we've upgraded the package.

See the documentation to learn how to switch to this package for the Oracle database.

Add Basic Theme Into Your Solution

ABP Framework provides a strong theming system. However, the default theme, named the Basic Theme, has a non-styled, base Bootstrap UI. It is expected that you override the styles and UI components of that theme in a serious application.

There are some articles (see for mvc & blazor) to explain how to include the Basic Theme's source code into your solution to modify it fully. However, it still requires some manual work.

With this version, ABP CLI providing a command to add the Basic Theme's source code into your solution. Run the following command in a command-line terminal inside the root directory of your solution:

MVC UI

abp add-package Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic --with-source-code --add-to-solution-file

Blazor Web Assembly UI

abp add-package Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme --with-source-code --add-to-solution-file
abp add-package Volo.Abp.AspNetCore.Components.Web.BasicTheme --with-source-code --add-to-solution-file

Blazor Server UI

abp add-package Volo.Abp.AspNetCore.Components.Server.BasicTheme --with-source-code --add-to-solution-file
abp add-package Volo.Abp.AspNetCore.Components.Web.BasicTheme --with-source-code --add-to-solution-file

As you see, Blazor UI developers should add two packages. The Basic Theme consists of two packages for the Blazor UI: one for wasm/server and one shared.

Angular UI

Execute the following command in a terminal inside the angular folder of your solution:

abp add-package @abp/ng.theme.basic --with-source-code

IInitLogger

In ASP.NET Core, logging is not possible before the dependency injection phase is completed. For example, you can't write log in ConfigureServices method. However, we sometimes need to write logs in this stage.

We are introducing the IInitLogger service, which allows writing logs inside the ConfigureServices method.

Example:

public class MyModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        var logger = context.Services.GetInitLogger<MyModule>();
        logger.LogInformation("Some log...");
    }
}

Logs are written once the service registration phase is completed. It stores the written logs in memory and then writes logs to the actual ILogger when ready.

Notice: Startup templates come with Serilog pre-installed. So, you can write logs everywhere by directly using its static API (ex: Log.Information("...");). The InitLogger is a way to write pre-initialization logs without depending on a particular logging library. So, it makes it very handy to write logs inside reusable modules.

Other Features/Changes

• #7423 MongoDB repository base aggregation API.
• #8163 Ignoring given files on minification for MVC UI.
• #7799 Added RequiredPermissionName to ApplicationMenuItem for MVC & Blazor UI to easily show/hide menu items based on user permissions. Also added RequiredPermissionName to ToolbarItem for the MVC UI for the same purpose.
• #7523 Add more bundle methods to the distributed cache.
• #8013 Handle JsonProperty attribute on Angular proxy generation.

See the 4.3 milestone on GitHub for all changes made on this version.

Feedback

Please check out the ABP Framework 4.3 RC and provide feedback to help us release a more stable version. The planned release date for the 4.3.0 final version is April 21, 2021.

What's New With 4.2?

Since all the new features are already explained in details with the 4.2 RC Announcement Post, I will not repeat all the details again. See the RC Blog Post for all the features and enhancements.

Creating New Solutions

You can create a new solution with the ABP Framework version 4.2 by either using the abp new command or using the direct download tab on the get started page.

See the getting started document for details.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

Run this command in the root folder of your solution.

Migration Guide

Check the migration guide for the applications with the version 4.x upgrading to the version 4.2.

It is strongly recommended to check the migration guide for this version. Especially, the new IRepository.GetQueryableAsync() method is a core change should be considered after upgrading the solution.

About the Next Version

The next feature version will be 4.3. It is planned to release the 4.3 RC (Release Candidate) on March 11 and the final version on March 25, 2021.

We decided to slow down the feature development for the next milestone. We will continue to improve the existing features and introduce new ones, sure, but wanted to have more time for the planning, documentation, creating guides and improving the development experience.

The planned release date for the 4.2.0 final version is January 28, 2021.

Get Started with the 4.2 RC

If you want to try the version 4.2.0 today, follow the steps below;

1. Upgrade the ABP CLI to the version 4.2.0-rc.2 using a command line terminal:

dotnet tool update Volo.Abp.Cli -g --version 4.2.0-rc.2

or install if you haven't installed before:

dotnet tool install Volo.Abp.Cli -g --version 4.2.0-rc.2

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

Migration Guide

Check the migration guide for the applications with the version 4.x upgrading to the version 4.2.

What's new with the ABP Framework 4.2

IRepository.GetQueryableAsync()

This version comes with an important change about using IQueryable features over the repositories. It is suggested to read this section carefully and apply in your applications.

IRepository interface inherits IQueryable, so you can directly use the standard LINQ extension methods, like Where, OrderBy, First, Sum... etc.

Example: Using LINQ directly over the repository object

public class BookAppService : ApplicationService, IBookAppService
{
    private readonly IRepository<Book, Guid> _bookRepository;

    public BookAppService(IRepository<Book, Guid> bookRepository)
    {
        _bookRepository = bookRepository;
    }

    public async Task DoItInOldWayAsync()
    {
        //Apply any standard LINQ extension method
        var query = _bookRepository
            .Where(x => x.Price > 10)
            .OrderBy(x => x.Name);

        //Execute the query asynchronously
        var books = await AsyncExecuter.ToListAsync(query);
    }
}

See the documentation if you wonder what is the AsyncExecuter.

Beginning from the version 4.2, the recommended way is using IRepository.GetQueryableAsync() to obtain an IQueryable, then use the LINQ extension methods over it.

Example: Using the new GetQueryableAsync method

public async Task DoItInNewWayAsync()
{
    //Use GetQueryableAsync to obtain the IQueryable<Book> first
    var queryable = await _bookRepository.GetQueryableAsync();

    //Then apply any standard LINQ extension method
    var query = queryable
        .Where(x => x.Price > 10)
        .OrderBy(x => x.Name);

    //Finally, execute the query asynchronously
    var books = await AsyncExecuter.ToListAsync(query);
}

ABP may start a database transaction when you get an IQueryable (If current Unit Of Work is transactional). In this new way, it is possible to start the database transaction in an asynchronous way. Previously, we could not get the advantage of asynchronous while starting the transactions.

The new way has a significant performance and scalability gain. The old usage (directly using LINQ over the repositories) will be removed in the next major version. You have a lot of time for the change, but we recommend to immediately take the action since the old usage has a big scalability problem.

See the migration guide for the actions you may need to take while upgrading your applications.

About IRepository Async Extension Methods

Using IRepository Async Extension Methods has no such a problem. The examples below are pretty fine:

var countAll = await _personRepository
    .CountAsync();

var count = await _personRepository
    .CountAsync(x => x.Name.StartsWith("A"));

var book1984 = await _bookRepository
    .FirstOrDefaultAsync(x => x.Name == "John");   

See the repository documentation to understand the relation between IQueryable and asynchronous operations.

Repository Bulk Operations

This version adds the following methods to the repositories:

• InsertManyAsync
• UpdateManyAsync
• DeleteManyAsync

The purpose of these methods to insert, update or delete many entities in one call with a better performance.

Currently, MongoDB provider implements these methods as a single bulk operation since MongoDB API natively supports. But current Entity Framework Core implementation is not a real bulk operation. Instead, it does its best with the native API of the EF Core. If you want to implement in a more performant way, you can customize the bulk operations with your own implementation or by using a library. We could find a good open source library for EF Core 5.0 to implement it.

Selecting DBMS on Template Creation

ABP CLI now has an option to specify the DBMS when you use EF Core as the database provider.

Example: Select MySQL as the DBMS

abp new BookStore -dbms mysql --preview

Available options: SqlServer (default), MySQL, SQLite, Oracle-Devart, PostgreSQL. See the documentation to use any other DBMS or switch the DBMS later.

One change related to this feature is that: Now, the startup template doesn't come with an initial migration file. This is because the database migrations are different based on your DBMS preference and should be re-created. However, when you first run the .DbMigrator application, it will create the initial migration and create the database just like before.

See The Initial Migration section in the Getting Started document if you have problems on running the .DbMigrator application first time.

Swagger UI Login / Authorization

Testing the swagger UI was requiring some additional work, especially your authentication server is separated from the application that hosts the Swagger UI.

With the version 4.2, the startup templates come with the authorization pre-configured for you. An Authorize button is available when you open the Swagger UI:

When you click, it opens a modal to authorize:

When you click to the Authorize button here, you are redirected to the login page to login with your username and password (default username is admin and password is 1q2w3E*).

Remember to select the Scopes (typically select all) you want to use before clicking to the Authorize button.

Angular Unit Testing

We've improved the modules and the startup template to setup and write unit tests easier with the Angular UI. See the Angular Unit Testing document for details.

Other News

• Improved HTTP request-response performance by resolving dependencies in a deferred way in the action/page filters, interceptors and some other services.
• Removed MultipleActiveResultSets from connection strings for new templates for SQL Server, since the new EF Core gives a warning when using it. If you want to use it, you need to change the connection string yourself.
• Added HardDeleteAsync extension method that takes a predicate to delete multiple entities. This extension method is available if the entity Soft Delete.
• Implemented the Page Alerts for the Angular UI.
• Implemented Page Progress for the Blazor UI. It automatically shows an undetermined progress bar on top of the page while performing an AJAX request. It also proves an API to you if you need to show/hide the progress bar in your code.

What's new with the ABP Commercial 4.2

Microservice Startup Template

The new Microservice Startup Template is a generic solution to start a new microservice solution.

While we accept that every microservice solution will be different and every system has its own design requirements and trade-offs, we believe such a startup solution is a very useful starting point for most of the solutions, and a useful example for others.

Figure: A simplified overall diagram of the microservice solution.

You can follow the documentation to get started with this startup template. This template should be considered as an early release. We will improve it and write a lot of guides.

If you want to use the ABP Suite to create your solution, then you need to first upgrade it:

abp suite update --preview

If you want, you can directly create a new solution from the command line:

abp new Volosoft.MyMicroserviceSystem -t microservice-pro --preview

Company Name is optional. Solution name could be MyMicroserviceSystem for this example.

Public Website in the Startup Templates

As mentioned in the previous release post, we've added a Public Website application to the startup templates. It is configured to authenticate through the IdentityServer with a single sign-on system.

You can use this application to create a landing page for your actual application or a corporate website for your business. An example screenshot:

It uses the same Lepton Theme, so you can apply all the styles. The Public Website has a different layout and also has a different setting for the styling (that can be configured in the Settings / Lepton Theme page of the main web application).

Public Website is optional and you need to select the "Public Website" option while creating a new solution using the ABP Suite, or use the --with-public-website option while using the abp new CLI command.

Easy CRM Blazor UI

Easy CRM is an example application built with the ABP Commercial. MVC (Razor Pages) and Angular UI implementations were already provided. With the version 4.2, we are providing the Blazor UI implementation for this application.

Other News

• Implemented Iyzico as a payment gateway provider for the payment module in addition to Paypal, Stripe, 2Checkout and Payu providers.
• ABP Suite supports the new microservice template creation, public website and DBMS selection options.
• Swagger authorization and other features mentioned in the ABP Framework section are already implemented for the ABP Commercial too.

ABP Community News

Sharing Video Contents

community.abp.io is a place to share ABP related contents. It started with publishing articles. Now, it supports to publish video contents. See this example. All you need to do is to create a video and upload to YouTube. Then you can submit the YouTube link to the ABP Community website.

Multi-language support

We planned ABP Community to publish English-only contents. However, we see that people want to share contents in other languages too. Now, it is possible to submit a content in any language. Just select the Language option while submitting your content.

When you submit a non-English content, it is not visible to all the visitors by default. Visitors can see a non-English content only if their browser language or the selected language matches to the content language (there is a language selection at the end of the website).

External Contents

If you want to publish your content anywhere else, but want to post a link of your content, you can select External Content option while submitting the post. For example, this article is an external article and also written in Chinese language.

About the Next Release

The next feature version will be 4.3.0. It is planned to release the 4.3 RC (Release Candidate) on March 11 and the final version on March 25, 2021.

We decided to slow down the feature development for the next milestone. We will continue to improve the existing features and introduce new ones, sure, but wanted to have more time for the planning, documentation, creating guides and improving the development experience.

Feedback

Please check out the ABP Framework 4.2.0 RC and provide feedback to help us to release a more stable version. The planned release date for the 4.2.0 final version is January 28, 2021.

What's New With 4.1?

Since all the new features are already explained in details with the 4.1 RC Announcement Post, I will not repeat all the details again. See the RC Blog Post for all the features and enhancements.

Creating New Solutions

You can create a new solution with the ABP Framework version 4.1 by either using the abp new command or using the direct download tab on the get started page.

See the getting started document for details.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

Run this command in the root folder of your solution.

ABP Community

We started to get more contributions by the community for the ABP Community contents. Thank you all!

We will be adding Video Content sharing system in a short time. We are planning to create short video contents, especially to explore the new features in every release. Again, we will be waiting video contributions by the community :)

About the Next Versions

Planned preview date for the version 4.2 is January 14, 2021. See the Road Map document and GitHub Milestones to learn what's planned for the next versions. We are trying to be clear about the coming features and the next release dates.

Notice: 4.1.0 final version has been released at January 6, 2021.

Get Started with the 4.1 RC

If you want to try the version 4.1.0 today, follow the steps below;

1. Upgrade the ABP CLI to the version 4.1.0-rc.2 using a command line terminal:

dotnet tool update Volo.Abp.Cli -g --version 4.1.0-rc.2

or install if you haven't installed before:

dotnet tool install Volo.Abp.Cli -g --version 4.1.0-rc.2

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

Breaking Changes

This version has a minor breaking change if you'd injected a repository by class. This is not a problem for 99% of the applications. However, see #6677 for the solution if that's a breaking change for you.

What's new with the ABP Framework 4.1

Module Entity Extensions

Module Entity Extension system provides a simple way of adding new properties to an existing entity defined by a module that is used by your application. This feature is now available also for the open source modules (identity and tenant-management). The documentation has been moved into the ABP Framework's documentation.

Example: Add "SocialSecurityNumber" property to the IdentityUser entity

ObjectExtensionManager.Instance.Modules()
    .ConfigureIdentity(identity =>
    {
        identity.ConfigureUser(user =>
        {
            user.AddOrUpdateProperty<string>( //property type: string
                "SocialSecurityNumber", //property name
                property =>
                {
                    //validation rules
                    property.Attributes.Add(new RequiredAttribute());
                    property.Attributes.Add(
                        new StringLengthAttribute(64) {
                            MinimumLength = 4
                        }
                    );

                    //...other configurations for this property
                }
            );
        });
    });

The new property becomes available on the UI, API and the database. You can even define navigation properties. This provides an easy way to extend existing modules while using them as NuGet packages. See the document for details.

Blazor UI Improvements

Since the Blazor UI is relatively new in the ABP Framework, we continue to add features and make enhancements to fill the gap between other supported UI types.

Bundling & Minification

In the version 4.1, we had introduced the abp bundle command for the Blazor UI to add global script and style files of the depended modules into the index.html. It was a preparation for a real bundling & minification system. With the version 4.2, this command has been completed.

Whenever you add a new module to your Blazor application, just type the abp bundle command in a command line terminal;

• It finds all the global script/style files in your application and the modules your application directly or indirectly depends on, ordered by the module dependencies.
• Bundles all the scripts into a single file and minified the file (same for the styles).
• Add the single bundle file to the index.html file.

Added a configuration into the appsettings.json file in the Blazor application in the application startup template to control the bundling mode:

{
  "AbpCli": {
    "Bundle": {
      "Mode": "BundleAndMinify"
    }
  }
}

Possible values are;

• BundleAndMinify: Bundle all the files into a single file and minify the content.
• Bundle: Bundle all files into a single file, but not minify.
• None: Add files individually, do not bundle.

See the Global Scripts & Styles document for details.

SubmitButton

SubmitButton is a new component that simplifies to save a form:

<SubmitButton Clicked="UpdateEntityAsync" />

The main advantages of using this component instead of a standard Button with submit type is; It automatically blocks the submit button until the save operation has fully completed. This prevents multiple clicks by user. And it is shorter than doing all manually. See the document.

Other Blazor UI highlights

• Implemented some animations (like opening/closing modals and dropdowns).
• Automatically focus to the first input when you open a modal form.

Module extensibility system (mentioned above) for the Blazor UI is under development and not available yet.

What's new with the ABP Commercial 4.1

Blazor UI Improvements

We continue to complete missing modules and functionalities for the Blazor UI.

Organization Unit Management

Organization Management UI has been implemented for the Blazor UI. Example screenshot:

IdentityServer UI

IdentityServer Management UI is also available for the Blazor UI now:

Suite: Navigation Property Selection with Typeahead

We had introduced auto-complete select style navigation property selection. With this release, it is fully supported by all the UI options. So, when you create an CRUD page with ABP Suite for entity that has 1 to Many relation to another entity, you can simply select the target entity with a typeahead style select component. Example screenshot:

Spanish Language Translation

We continue to add new language supports for the UI. In this version, translated the UI to Spanish language.

Coming: Public Website with Integrated CMS Features

In the next version, the application startup template will come with a public website application option. CMS Kit module will be installed in the website by default, that means newsletter, contact form, comments and some other new features will be directly usable in your applications.

An early screenshot from the public website application home page:

Other News

ABP Community Contents

A lot of new contents have been published in the ABP Community Web Site in the last two weeks:

• How to Integrate the Telerik Blazor Components to the ABP Blazor UI by EngincanV
• Using DevExpress Blazor UI Components With the ABP Framework by @berkansasmaz
• Creating a new UI theme by copying the Basic Theme (for MVC UI) by @ebubekirdinc
• Using Angular Material Components With the ABP Framework by @muhammedaltug
• How to export Excel files from the ABP framework by bartvanhoey
• Creating an Event Organizer Application with the ABP Framework & Blazor UI by @hikalkan

Thanks to all of the contributors. We are waiting for your contributions too. If you want to create content for the ABP Community, please visit community.abp.io website and submit your article.

Be a Superhero on Day 1 with ABP.IO

Thanks to @lprichar prepared an awesome introduction video for the ABP.IO Platform: "Be a Superhero on Day 1 with ABP.IO".

New Sample Application: Event Organizer

This is a new example application developed using the ABP Framework and the Blazor UI. See this article for a step by step implementation guide.

Github Discussions

We enabled the GitHub Discussions for the abp repository as another place to discuss ideas or get help for the ABP Framework. The ABP core team is spending time participating in discussions and answering to questions as much as possible.

About the Next Release(s)

Beginning from the next version (4.2.0), we are starting to spend more effort on the CMS Kit module. The purpose of this module is to provide CMS primitives (e.g. comments, tags, reactions, contents...) and features (e.g. blog, pages, surveys) as pre-built and reusable components. Current blog module will be a part of the CMS Kit module.

We will continue to prepare documents, guides, tutorials and examples. And surely, we will continue to make enhancements and optimizations on the current features.

The planned preview release date for the version 4.2.0 is January 14, 2021 and the final (stable) version release date is January 28, 2021.

Follow the GitHub milestones for all the planned ABP Framework version release dates.

Feedback

Please check out the ABP Framework 4.1.0 RC and provide feedback to help us to release a more stable version. The planned release date for the 4.1.0 final version is January 4, 2021.

Introduction

In this article, we will create an example application that is a simple meeting/event organizer: People create events and other people registers to the event.

The application has been developed with Blazor as the UI framework and MongoDB as the database provider.

This tutorial is based on my notes that I'd created to implement this application in a workshop. It shows the necessary steps to build the application rather than detailed explanations.

Source Code

Source code of the completed application is available on GitHub.

Screenshots

Here, the pages of the final application.

Home Page - Event List

Creating a new Event

Event Detail Page

Requirements

The following tools are needed to be able to run the solution.

• .NET 5.0 SDK
• Visual Studio 2019 16.8.0+ or another compatible IDE
• MongoDB Server (with MongoDB Compass)

Development

Creating a new Application

• Use the following ABP CLI command:

abp new EventOrganizer -u blazor -d mongodb

Open & Run the Application

• Open the solution in Visual Studio (or your favorite IDE).
• Run the EventOrganizer.DbMigrator application to seed the initial data.
• Run the EventOrganizer.HttpApi.Host application that starts the server side.
• Run the EventOrganizer.Blazor application to start the UI.

Apply the Custom Styles

• Add styles to wwwroot/main.css:

body.abp-application-layout {
    background-color: #222 !important;
    font-size: 18px;
}
nav#main-navbar.bg-dark {
    background-color: #222 !important;
    box-shadow: none !important;
}
.event-pic {
    width: 100%;
    border-radius: 12px;
    box-shadow: 5px 5px 0px 0px rgba(0,0,0,.5);
    margin-bottom: 10px;
}
.event-link:hover, .event-link:hover *{
    text-decoration: none;
}
.event-link:hover .event-pic {
    box-shadow: 5px 5px 0px 0px #ffd800;
}
.event-form {
    background-color: #333 !important;
    box-shadow: 5px 5px 0px 0px rgba(0,0,0,.5);
    border-radius: 12px;
}
.table {
    background: #fff;
    border-radius: 12px;
    box-shadow: 5px 5px 0px 0px rgba(0,0,0,.5);
}
.table th{
    border: 0 !important;
}
.modal {
    color: #333;
}
.page-item:first-child .page-link {
    margin-left: 0;
    border-top-left-radius: 12px;
    border-bottom-left-radius: 12px;
}
.page-item:last-child .page-link {
    border-top-right-radius: 12px;
    border-bottom-right-radius: 12px;
}
.btn {
    border-radius: 8px;
}
.att-list {
    list-style: none;
    padding: 0;
}
.att-list li {
    padding: 4px 0 0 0;
}

• wwwroot/index.html: Remove bg-light class from the body tag and add bg-dark text-light.

Domain Layer

• Add the following Event aggregate (with EventAttendee) to the solution:

Event

using System;
using System.Collections.Generic;
using Volo.Abp.Domain.Entities.Auditing;

namespace EventOrganizer.Events
{
    public class Event : FullAuditedAggregateRoot<Guid>
    {
        public string Title { get; set; }

        public string Description { get; set; }

        public bool IsFree { get; set; }

        public DateTime StartTime { get; set; }

        public ICollection<EventAttendee> Attendees { get; set; }

        public Event()
        {
            Attendees = new List<EventAttendee>();
        }
    }
}

EventAttendee

using System;
using Volo.Abp.Auditing;

namespace EventOrganizer.Events
{
    public class EventAttendee : IHasCreationTime
    {
        public Guid UserId { get; set; }

        public DateTime CreationTime { get; set; }
    }
}

MongoDB Mapping

• Add the following property to the EventOrganizerMongoDbContext:

public IMongoCollection<Event> Events => Collection<Event>();

Clean Index.razor & Add the Header & "Create Event" button

• Clean the Index.razor file.
• Replace the content with the following code:

@page "/"
@inherits EventOrganizerComponentBase
<Row Class="mb-4">
    <Column Class="text-left">
        <h1>Upcoming Events</h1>
    </Column>
    <Column Class="text-right">
        @if (CurrentUser.IsAuthenticated)
        {
            <a class="btn btn-primary" href="/create-event">
                <i class="fa fa-plus"></i> @L["CreateEvent"]
            </a>
        }
    </Column>
</Row>

• Open Localization/EventOrganizer/en.json in the EventOrganizer.Domain.Shared project and add the following entry:

"CreateEvent": "Create a new event!"

The Result (run the EventOrganizer.Blazor application to see):

Event Creation

• Create the Initial IEventAppService with the CreateAsync method:

using System;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;

namespace EventOrganizer.Events
{
    public interface IEventAppService : IApplicationService
    {
        Task<Guid> CreateAsync(EventCreationDto input);
    }
}

• Add EventCreationDto class:

using System;
using System.ComponentModel.DataAnnotations;

namespace EventOrganizer.Events
{
    public class EventCreationDto
    {
        [Required]
        [StringLength(100)]
        public string Title { get; set; }

        [Required]
        [StringLength(2000)]
        public string Description { get; set; }

        public bool IsFree { get; set; }

        public DateTime StartTime { get; set; }
    }
}

• Implement the EventAppService:

using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authorization;
using Volo.Abp.Domain.Repositories;

namespace EventOrganizer.Events
{
    public class EventAppService : EventOrganizerAppService, IEventAppService
    {
        private readonly IRepository<Event, Guid> _eventRepository;

        public EventAppService(IRepository<Event, Guid> eventRepository)
        {
            _eventRepository = eventRepository;
        }

        [Authorize]
        public async Task<Guid> CreateAsync(EventCreationDto input)
        {
            var eventEntity = ObjectMapper.Map<EventCreationDto, Event>(input);
            await _eventRepository.InsertAsync(eventEntity);
            return eventEntity.Id;
        }
    }
}

• Add AutoMapper mapping to the EventOrganizerApplicationAutoMapperProfile class:

using AutoMapper;
using EventOrganizer.Events;

namespace EventOrganizer
{
    public class EventOrganizerApplicationAutoMapperProfile : Profile
    {
        public EventOrganizerApplicationAutoMapperProfile()
        {
            CreateMap<EventCreationDto, Event>();
        }
    }
}

This will automatically create the HTTP (REST) API for the application service (run the EventOrganizer.HttpApi.Host application to see it on the Swagger UI):

• Create the CreateEvent.razor file:

@page "/create-event"
@inherits EventOrganizerComponentBase
<Heading Size="HeadingSize.Is3" Margin="Margin.Is5.FromTop.Is4.FromBottom" Class="text-center">Create Event</Heading>
<Row>
    <Column ColumnSize="ColumnSize.Is6.Is3.WithOffset">
        <div class="p-lg-5 p-md-3 event-form">
            <EditForm Model="@Event" OnValidSubmit="Create">
                <Field>
                    <FieldLabel>@L["Title"]</FieldLabel>
                    <TextEdit @bind-Text="@Event.Title" />
                </Field>
                <Field>
                    <FieldLabel>@L["Description"]</FieldLabel>
                    <MemoEdit @bind-Text="@Event.Description" />
                </Field>
                <Field>
                    <Check TValue="bool" @bind-Checked="@Event.IsFree">@L["Free"]</Check>
                </Field>
                <Field>
                    <FieldLabel>@L["StartTime"]</FieldLabel>
                    <DateEdit TValue="DateTime" @bind-Date="@Event.StartTime" />
                </Field>
                <Button Type="@ButtonType.Submit" Block="true" Color="@Color.Primary" Size="Size.Large">@L["Save"]</Button>
            </EditForm>
        </div>
    </Column>
</Row>

• Create a partial CreateEvent class in the same folder, with the CreateEvent.razor.cs as the file name:

using System.Threading.Tasks;
using EventOrganizer.Events;
using Microsoft.AspNetCore.Components;

namespace EventOrganizer.Blazor.Pages
{
    public partial class CreateEvent
    {
        private EventCreationDto Event { get; set; } = new EventCreationDto();

        private readonly IEventAppService _eventAppService;
        private readonly NavigationManager _navigationManager;

        public CreateEvent(
            IEventAppService eventAppService,
            NavigationManager navigationManager)
        {
            _eventAppService = eventAppService;
            _navigationManager = navigationManager;
        }

        private async Task Create()
        {
            var eventId = await _eventAppService.CreateAsync(Event);
            _navigationManager.NavigateTo("/events/" + eventId);
        }
    }
}

The final UI is (run the EventOrganizer.Blazor application and click to the "Create Event" button):

Upcoming Events (Home Page)

• Open the IEventAppService and add a GetUpcomingAsync method to get the list of upcoming events:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;

namespace EventOrganizer.Events
{
    public interface IEventAppService : IApplicationService
    {
        Task<Guid> CreateAsync(EventCreationDto input);

        Task<List<EventDto>> GetUpcomingAsync();
    }
}

• Add a EventDto class:

using System;
using Volo.Abp.Application.Dtos;

namespace EventOrganizer.Events
{
    public class EventDto : EntityDto<Guid>
    {
        public string Title { get; set; }

        public string Description { get; set; }

        public bool IsFree { get; set; }

        public DateTime StartTime { get; set; }

        public int AttendeesCount { get; set; }
    }
}

• Implement the GetUpcomingAsync in the EventAppService class:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authorization;
using Volo.Abp.Domain.Repositories;

namespace EventOrganizer.Events
{
    public class EventAppService : EventOrganizerAppService, IEventAppService
    {
        private readonly IRepository<Event, Guid> _eventRepository;

        public EventAppService(IRepository<Event, Guid> eventRepository)
        {
            _eventRepository = eventRepository;
        }

        [Authorize]
        public async Task<Guid> CreateAsync(EventCreationDto input)
        {
            var eventEntity = ObjectMapper.Map<EventCreationDto, Event>(input);
            await _eventRepository.InsertAsync(eventEntity);
            return eventEntity.Id;
        }

        public async Task<List<EventDto>> GetUpcomingAsync()
        {
            var queryable = await _eventRepository.GetQueryableAsync();
            var query = queryable
                .Where(x => x.StartTime > Clock.Now)
                .OrderBy(x => x.StartTime);

            var events = await AsyncExecuter.ToListAsync(query);

            return ObjectMapper.Map<List<Event>, List<EventDto>>(events);
        }
    }
}

• Add the following line into the EventOrganizerApplicationAutoMapperProfile constructor:

CreateMap<Event, EventDto>();

Run the EventOrganizer.HttpApi.Host application to see the new upcoming endpoint on the Swagger UI:

• Change the Pages/Index.razor.cs content in the EventOrganizer.Blazor project as shown below:

using System.Collections.Generic;
using System.Threading.Tasks;
using EventOrganizer.Events;

namespace EventOrganizer.Blazor.Pages
{
    public partial class Index
    {
        private List<EventDto> UpcomingEvents { get; set; } = new List<EventDto>();

        private readonly IEventAppService _eventAppService;

        public Index(IEventAppService eventAppService)
        {
            _eventAppService = eventAppService;
        }

        protected override async Task OnInitializedAsync()
        {
            UpcomingEvents = await _eventAppService.GetUpcomingAsync();
        }
    }
}

• Change the Pages/Index.razor content in the EventOrganizer.Blazor project as shown below:

@page "/"
@inherits EventOrganizerComponentBase
<Row Class="mb-4">
    <Column Class="text-left">
        <h1>Upcoming Events</h1>
    </Column>
    <Column Class="text-right">
        @if (CurrentUser.IsAuthenticated)
        {
            <a class="btn btn-primary" href="/create-event">
                <i class="fa fa-plus"></i> @L["CreateEvent"]
            </a>
        }
    </Column>
</Row>
<Row>
    @foreach (var upcomingEvent in UpcomingEvents)
    {
        <Column Class="col-12 col-lg-4 col-md-6">
            <a class="mb-5 position-relative d-block event-link" href="/events/@upcomingEvent.Id">
                <div class="position-absolute text-right w-100 px-3 py-2" style="left: 0; top: 2px;">
                    @if (upcomingEvent.IsFree)
                    {
                        <Badge Color="Color.Success" Class="mr-1">FREE</Badge>
                    }
                    <span class="badge badge-warning font-weight-normal">
                        <i class="fas fa-user-friends"></i>
                        <span class="font-weight-bold">@upcomingEvent.AttendeesCount</span>
                    </span>
                </div>
                <img src="https://picsum.photos/seed/%40upcomingEvent.Id/400/300" class="event-pic"/>&nbsp;
                <div class="px-3 py-1">
                    <small class="font-weight-bold text-warning my-2 d-block text-uppercase">@upcomingEvent.StartTime.ToLongDateString()</small>
                    <p class="h4 text-light d-block mb-2">@upcomingEvent.Title</p>
                    <p class="text-light" style="opacity: .65;">@upcomingEvent.Description.TruncateWithPostfix(150)</p>
                </div>
            </a>
        </Column>
    }
</Row>

The new home page is shown below:

Event Detail Page

• Add GetAsync, RegisterAsync, UnregisterAsync and DeleteAsync methods to the IEventAppService:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;

namespace EventOrganizer.Events
{
    public interface IEventAppService : IApplicationService
    {
        Task<Guid> CreateAsync(EventCreationDto input);

        Task<List<EventDto>> GetUpcomingAsync();

        Task<EventDetailDto> GetAsync(Guid id);

        Task RegisterAsync(Guid id);

        Task UnregisterAsync(Guid id);

        Task DeleteAsync(Guid id);
    }
}

• Add EventDetailDto class:

using System;
using System.Collections.Generic;
using Volo.Abp.Application.Dtos;

namespace EventOrganizer.Events
{
    public class EventDetailDto : CreationAuditedEntityDto<Guid>
    {
        public string Title { get; set; }

        public string Description { get; set; }

        public bool IsFree { get; set; }

        public DateTime StartTime { get; set; }

        public List<EventAttendeeDto> Attendees { get; set; }
    }
}

• Add EventAttendeeDto class:

using System;

namespace EventOrganizer.Events
{
    public class EventAttendeeDto
    {
        public Guid UserId { get; set; }

        public string UserName { get; set; }

        public DateTime CreationTime { get; set; }
    }
}

• Implement the new methods in the EventAppService:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using EventOrganizer.Users;
using Microsoft.AspNetCore.Authorization;
using Volo.Abp;
using Volo.Abp.Domain.Repositories;
using Volo.Abp.Users;

namespace EventOrganizer.Events
{
    public class EventAppService : EventOrganizerAppService, IEventAppService
    {
        private readonly IRepository<Event, Guid> _eventRepository;
        private readonly IRepository<AppUser, Guid> _userRepository;

        public EventAppService(IRepository<Event, Guid> eventRepository, IRepository<AppUser, Guid> userRepository)
        {
            _eventRepository = eventRepository;
            _userRepository = userRepository;
        }

        [Authorize]
        public async Task<Guid> CreateAsync(EventCreationDto input)
        {
            var eventEntity = ObjectMapper.Map<EventCreationDto, Event>(input);
            await _eventRepository.InsertAsync(eventEntity);
            return eventEntity.Id;
        }

        public async Task<List<EventDto>> GetUpcomingAsync()
        {
            var queryable = await _eventRepository.GetQueryableAsync();
            var query = queryable
                .Where(x => x.StartTime > Clock.Now)
                .OrderBy(x => x.StartTime);

            var events = await AsyncExecuter.ToListAsync(query);

            return ObjectMapper.Map<List<Event>, List<EventDto>>(events);
        }

        public async Task<EventDetailDto> GetAsync(Guid id)
        {
            var @event = await _eventRepository.GetAsync(id);
            var attendeeIds = @event.Attendees.Select(a => a.UserId).ToList();

            var queryable = await _userRepository.GetQueryableAsync();
            var query = queryable
                .Where(u => attendeeIds.Contains(u.Id));

            var attendees = (await AsyncExecuter.ToListAsync(query))
                .ToDictionary(x => x.Id);

            var result = ObjectMapper.Map<Event, EventDetailDto>(@event);

            foreach (var attendeeDto in result.Attendees)
            {
                attendeeDto.UserName = attendees[attendeeDto.UserId].UserName;
            }

            return result;
        }

        [Authorize]
        public async Task RegisterAsync(Guid id)
        {
            var @event = await _eventRepository.GetAsync(id);
            if (@event.Attendees.Any(a => a.UserId == CurrentUser.Id))
            {
                return;
            }

            @event.Attendees.Add(new EventAttendee {UserId = CurrentUser.GetId(), CreationTime = Clock.Now});
            await _eventRepository.UpdateAsync(@event);
        }

        [Authorize]
        public async Task UnregisterAsync(Guid id)
        {
            var @event = await _eventRepository.GetAsync(id);
            var removedItems = @event.Attendees.RemoveAll(x => x.UserId == CurrentUser.Id);
            if (removedItems.Any())
            {
                await _eventRepository.UpdateAsync(@event);
            }
        }

        [Authorize]
        public async Task DeleteAsync(Guid id)
        {
            var @event = await _eventRepository.GetAsync(id);

            if (CurrentUser.Id != @event.CreatorId)
            {
                throw new UserFriendlyException("You don't have the necessary permission to delete this event!");
            }

            await _eventRepository.DeleteAsync(id);
        }
    }
}

• Add the following mappings into the EventOrganizerApplicationAutoMapperProfile:

CreateMap<Event, EventDetailDto>();
CreateMap<EventAttendee, EventAttendeeDto>();

Run the EventOrganizer.HttpApi.Host application to see the complete Event HTTP API in the Swagger UI:

• Create EventDetail.razor component with the following content:

@page "/events/{id}"
@inherits EventOrganizerComponentBase
@if (Event != null)
{
    <Row Class="mb-4">
        <Column Class="text-left">
            <h1>@Event.Title</h1>
        </Column>
        <Column Class="text-right pt-2">
            <a href="/" Class="btn btn-dark"><i class="fa fa-arrow-left"></i> Back</a>
            @if (CurrentUser.IsAuthenticated && CurrentUser.Id == Event.CreatorId)
            {
                <Button Color="Color.Danger" Clicked="Delete" Class="ml-1">Delete</Button>
            }
        </Column>
    </Row>
    <Row>
        <Column Class="col-12 col-md-8">
            <div class="position-relative">
                <div class="position-absolute text-right w-100 px-3 py-2" style="left: 0; top: 2px;">
                    @if (Event.IsFree)
                    {
                        <Badge Color="Color.Success" Class="mr-1">FREE</Badge>
                    }
                    <span class="badge badge-warning font-weight-normal">
                        <i class="fas fa-user-friends"></i>
                        <span class="font-weight-bold">@Event.Attendees.Count</span>
                    </span>
                </div>
                <img src="https://picsum.photos/seed/%40Event.Id/800/600" class="event-pic" />&nbsp;
                <small class="font-weight-bold text-warning my-2 d-block text-uppercase">Start time: @Event.StartTime.ToLongDateString()</small>
                <p style="opacity: .65;">@Event.Description</p>
            </div>
        </Column>
        <Column Class="col-12 col-md-4">
            <div class="p-4 event-form">
                @if (CurrentUser.IsAuthenticated)
                {
                    <div>
                        @if (!IsRegistered)
                        {
                            <Button Color="Color.Primary" Clicked="Register" Class="btn-block btn-lg">Register now!</Button>
                        }
                        else
                        {
                            <p>You are registered in this event</p>
                            <Button Color="Color.Secondary" Clicked="UnRegister" Class="btn-block">Cancel registration!</Button>
                        }
                    </div>
                }
                else
                {
                    <a class="btn btn-primary" href="/authentication/login">
                        <i class="fa fa-sign-in-alt"></i> Login to attend!
                    </a>
                }
            </div>
            <div class="mt-4 event-form p-4">
                <span class="font-weight-bold"><i class="fas fa-user-friends"></i> Attendees <span class="float-right font-weight-normal" style="opacity:.65;">(@Event.Attendees.Count)</span></span>
                <ul class="mt-1 mb-0 att-list">
                    @foreach (var attendee in Event.Attendees)
                    {
                        <li><i class="fa fa-check"></i> @attendee.UserName</li>
                    }
                </ul>
            </div>
        </Column>
    </Row>
}

• Create EventDetail.razor.cs file with the following content:

using System;
using System.Linq;
using System.Threading.Tasks;
using EventOrganizer.Events;
using Microsoft.AspNetCore.Components;

namespace EventOrganizer.Blazor.Pages
{
    public partial class EventDetail
    {
        [Parameter]
        public string Id { get; set; }

        private EventDetailDto Event { get; set; }
        private bool IsRegistered { get; set; }

        private readonly IEventAppService _eventAppService;
        private readonly NavigationManager _navigationManager;

        public EventDetail(
            IEventAppService eventAppService,
            NavigationManager navigationManager)
        {
            _eventAppService = eventAppService;
            _navigationManager = navigationManager;
        }

        protected override async Task OnInitializedAsync()
        {
            await GetEventAsync();
        }

        private async Task GetEventAsync()
        {
            Event = await _eventAppService.GetAsync(Guid.Parse(Id));
            if (CurrentUser.IsAuthenticated)
            {
                IsRegistered = Event.Attendees.Any(a => a.UserId == CurrentUser.Id);
            }
        }

        private async Task Register()
        {
            await _eventAppService.RegisterAsync(Guid.Parse(Id));
            await GetEventAsync();
        }

        private async Task UnRegister()
        {
            await _eventAppService.UnregisterAsync(Guid.Parse(Id));
            await GetEventAsync();
        }

        private async Task Delete()
        {
            if (!await Message.Confirm("This event will be deleted: " + Event.Title))
            {
                return;
            }

            await _eventAppService.DeleteAsync(Guid.Parse(Id));
            _navigationManager.NavigateTo("/");
        }
    }
}

The resulting page is shown below:

Integration Tests

Create an EventAppService_Tests class in the EventOrganizer.Application.Tests project:

using System;
using System.Threading.Tasks;
using Shouldly;
using Xunit;

namespace EventOrganizer.Events
{
    [Collection(EventOrganizerTestConsts.CollectionDefinitionName)]
    public class EventAppService_Tests : EventOrganizerApplicationTestBase
    {
        private readonly IEventAppService _eventAppService;

        public EventAppService_Tests()
        {
            _eventAppService = GetRequiredService<IEventAppService>();
        }

        [Fact]
        public async Task Should_Create_A_Valid_Event()
        {
            // Create an event

            var eventId = await _eventAppService.CreateAsync(
                new EventCreationDto
                {
                    Title = "My test event 1",
                    Description = "My test event description 1",
                    IsFree = true,
                    StartTime = DateTime.Now.AddDays(2)
                }
            );

            eventId.ShouldNotBe(Guid.Empty);

            // Get the event

            var @event = await _eventAppService.GetAsync(eventId);
            @event.Title.ShouldBe("My test event 1");

            // Get upcoming events

            var events = await _eventAppService.GetUpcomingAsync();
            events.ShouldContain(x => x.Title == "My test event 1");
        }
    }
}

Source Code

Source code of the completed application is available on GitHub.

4 Years of Work

As a nice coincidence, today is the 4th year since the first commit made in the abp repository! So, we can say "Happy Birthday ABP Framework!".

Some Statistics

ABP.IO Platform and the ABP Community is growing. Here, a summary of these 4 years.

From GitHub, only from the main abp repository;

• 15,297 commits done.
• 3,764 issues are closed.
• 2,133 pull requests are merged.
• 158 contributors.
• 88 releases published.
• 5.2K stars on GitHub.

From NuGet & NPM;

• 220 NuGet packages & 52 NPM packages.
• 1,000,000 downloads only for the core NuGet package.

From Website;

• 200,000 visitors.
• 1,000,000+ sessions.

What's New With 4.0?

Since all the new features are already explained in details with the 4.0 RC Announcement Post, I will not repeat all the details again. Please read the RC post for new feature and changes you may need to do for your solution while upgrading to the version 4.0.

Here, a brief list of major features and changes;

• Migrated to .NET 5.0.
• Stable Blazor UI.
• Moved to System.Text.Json.
• Upgraded to IdentityServer version 4.0.
• WPF startup template.

Creating New Solutions

You can create a new solution with the ABP Framework version 4.0 by either using the abp new command or using the direct download tab on the get started page.

See the getting started document for details.

How to Upgrade an Existing Solution

This is a major version and requires some manual work, especially related to .NET 5.0 and IdentityServer 4.0 upgrades.

• See the MIGRATION GUIDE that covers all the details about the upgrade progress.

• You can also see the upgrading document.

New Guides / Documents

We are constantly improving the documentation. Our purpose is not only document the ABP Framework, but also write architectural and practical guides for developers.

Implementing Domain Driven Design

Implementing Domain Driven Design is a practical guide for they want to implement the DDD principles in their solutions. While the implementation details rely on the ABP Framework infrastructure, core concepts, principles and patterns are applicable in any kind of solution, even if it is not a .NET solution.

Testing

The new Testing document discusses different kind of automated tests and explains how you can write tests for your ABP based solutions.

UI Documents

We've created a lot of documents for the MVC, Blazor and the Angular UI.

About the Next Version

The next versions 4.1 will mostly focus on;

• Improving current features.
• Complete module features for the Blazor UI.
• Improve developer experience and productivity.
• More documentation and examples.

Planned preview date for the version 4.1 is December 17, 2020. See the Road Map document and GitHub Milestones to learn what's planned for the next versions. We are trying to be clear about the coming features and the next release dates.

The planned release date for the 4.0.0 final version is December 3, 2020.

Get Started with the 4.0 RC

If you want to try the version 4.0.0 today, follow the steps below;

1. Upgrade the ABP CLI to the version 4.0.0-rc.5 using a command line terminal:

dotnet tool update Volo.Abp.Cli -g --version 4.0.0-rc.5

or install if you haven't installed before:

dotnet tool install Volo.Abp.Cli -g --version 4.0.0-rc.5

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

Migrating From 3.x to 4.0

The version 4.0 comes with some major changes including the migration from .NET Core 3.1 to .NET 5.0.

We've prepared a detailed migration document to explain all the changes and the actions you need to take while upgrading your existing solutions.

What's new with the ABP Framework 4.0

The Blazor UI

The Blazor UI is now stable and officially supported. The web application development tutorial has been updated based on the version 4.0.

abp bundle command

Introducing the abp bundle CLI command to manage static JavaScript & CSS file dependencies of a Blazor application. This command is currently used to add the dependencies to the index.html file in the dependency order by respecting to modularity. In the next version it will automatically unify & minify the files. The documentation is being prepared.

Removed the JQuery & Bootstrap JavaScript

Removed JQuery & Bootstrap JavaScript dependencies for the Blazor UI.

There are some other changes in the startup template and some public APIs. Follow the Migration Guide to apply changes for existing solutions that you're upgrading from the version 3.3. While we will continue to make improvements add new features, we no longer make breaking changes on the existing APIs until the version 5.0.

Others

A lot of minor and major improvements have been done for the Blazor UI. Some of them are listed below:

• Implemented IComponentActivator to resolve the component from the IServiceProvider. So, you can now inject dependencies into the constructor of your razor component.
• Introduced the AbpComponentBase base class that you derive your components from. It has useful base properties that you can use in your pages/components.
• Introduced IUiNotificationService service to show toast notifications on the UI.
• Improved the IUiMessageService to show message & confirmation dialogs.

System.Text.Json

ABP Framework 4.0 uses the System.Text.Json by default as the JSON serialization library. It, actually, using a hybrid approach: Continues to use the Newtonsoft.Json when it needs to use the features not supported by the System.Text.Json.

Follow the Migration Guide to learn how to configure to use the Newtonsoft.Json for some specific types or switch back to the Newtonsoft.Json as the default JSON serializer.

Identity Server 4 Upgrade

ABP Framework upgrades the IdentityServer4 library from 3.x to 4.1.1 with the ABP Framework version 4.0. IdentityServer 4.x has a lot of changes. Some of them are breaking changes in the data structure.

Follow the Migration Guide to upgrade existing solutions.

Creating a New Module Inside the Application

ABP CLI has now a command to create a new module and add it to an existing solution. In this way, you can create modular applications easier than before.

Example: Create a ProductManagement module into your solution.

abp add-module ProductManagement --new --add-to-solution-file

Execute this command in a terminal in the root folder of your solution. If you don't specify the --add-to-solution-file option, then the module projects will not be added to the main solution, but the project references still be added. In this case, you need to open the module's solution to develop the module.

See the CLI document for other options.

WPF Startup Template

Introducing the WPF startup template for the ABP Framework. Use the ABP CLI new command to create a new WPF application:

abp new MyWpfApp -t wpf

This is a minimalist, empty project template that is integrated to the ABP Framework.

New Languages

Thanks to the contributors from the ABP Community, the framework modules and the startup template have been localized to German language by Alexander Pilhar & Nico Lachmuth and to Spanish language by Jose Manuel Gonzalez and Washington Acero M..

Other Notes

• Upgraded to Angular 11.
• Since Mongo2Go library not supports transactions, you can use transactions in unit tests for MongoDB.

What's new with the ABP Commercial 4.0

The Blazor UI

The Blazor UI for the ABP Commercial is also becomes stable and feature rich with the version 4.0;

• ABP Suite now supports to generate CRUD pages for the Blazor UI.
• Completed the Lepton Theme for the Blazor UI.
• Implemented the File Management module for the Blazor UI.

The ABP Suite

While creating create/edit modals with a navigation property, we had two options: A dropdown to select the target entity and a modal to select the entity by searching with a data table.

Dropdown option now supports lazy load, search and auto-complete. In this way, selecting a navigation property becomes much easier and supports large data sets on the dropdown.

Example: Select an author while creating a new book

With the new version, you can disable backend code generation on CRUD page generation. This is especially useful if you want to regenerate the page with a different UI framework, but don't want to regenerate the server side code.

Identity Server Management UI Revised

Completely revised the Identity Server Management UI based on the IDS 4.x changes.

About the Next Release

The next feature version, 4.1.0, will mostly focus on completing the missing documents, fixing bugs, performance optimizations and improving the Blazor UI features. The planned preview release date for the version 4.1.0 is December 10 and the final (stable) version release date is December 24.

Follow the GitHub milestones for all the planned ABP Framework version release dates.

Feedback

Please check out the ABP Framework 4.0.0 RC and provide feedback to help us to release a more stable version. The planned release date for the 4.0.0 final version is November 26.

Since all the new features are already explained in details with the 3.3 RC Announcement Post, I will not repeat all the details again. Please read the RC post for new feature and changes you may need to do for your solution while upgrading to the version 3.3.

Creating New Solutions

You can create a new solution with the ABP Framework version 3.3 by either using the abp new command or using the direct download tab on the get started page.

See the getting started document for details.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

Run this command in the root folder of your solution. After the update command, check the RC blog post to learn if you need to make any changes in your solution.

You may want to see the new upgrading document.

About the Next Version: 4.0

The next version will be 4.0 and it will be mostly related to completing the Blazor UI features and upgrading the ABP Framework & ecosystem to the .NET 5.0.

The goal is to complete the version 4.0 with a stable Blazor UI with the fundamental features implemented and publish it just after the Microsoft lunches .NET 5 in this November. The planned 4.0 preview release date is November 11th.

Note that the blog post has been updated for the 3.3.0-rc.2 release.

We have released the ABP Framework (and the ABP Commercial) 3.3.0-rc.2 today. This blog post introduces the new features and important changes in the new version.

Get Started with the 3.3 RC.2

If you want to try the version 3.3.0-rc.2 today, follow the steps below;

1. Upgrade the ABP CLI to the version 3.3.0-rc.2 using a command line terminal:

dotnet tool update Volo.Abp.Cli -g --version 3.3.0-rc.2

or install if you haven't installed before:

dotnet tool install Volo.Abp.Cli -g --version 3.3.0-rc.2

2. Create a new application with the --preview option:

abp new BookStore --preview

See the ABP CLI documentation for all the available options.

You can also use the Direct Download tab on the Get Started page by selecting the Preview checkbox.

Entity Framework Core Migrations

This release includes changes in the database tables. If you are using EF Core, then you need to add a new migration (Add-Migration) and apply changes (Update-Database) to the database after upgrading your project.

What's new in the ABP Framework 3.3

The Blazor UI

We had released an experimental early preview version of the Blazor UI with the previous version. In this version, we've completed most of the fundamental infrastructure features and the application modules (like identity and tenant management).

It currently has almost the same functionalities as the other UI types (Angular & MVC / Razor Pages).

Example screenshot: User management page of the Blazor UI

We've adapted the Lepton Theme for the ABP Commercial, see the related section below.

We are still working on the fundamentals. So, the next version may introduce breaking changes of the Blazor UI. We will work hard to keep them with the minimal effect on your application code.

Blazor UI Tutorial

The Blazor UI tutorial has been updated for the version 3.3.0-rc.2. So, you can start the development today!

Breaking Changes on the Blazor UI

There are some breaking changes with the Blazor UI. If you've built an application and upgrade it, your application might not properly work. See the migration guide for the changes you need to do after upgrading your application.

Automatic Validation for AntiForgery Token for HTTP APIs

Starting with the version 3.3, all your HTTP API endpoints are automatically protected against CSRF attacks, unless you disable it for your application. So, no configuration needed, just upgrade the ABP Framework.

See the documentation to if you want to understand why you need it and how ABP Framework solves the problem.

Rebus Integration Package for the Distributed Event Bus

Rebus describes itself as "Simple and lean service bus implementation for .NET". There are a lot of integration packages like RabbitMQ and Azure Service Bus for the Rebus. The new Volo.Abp.EventBus.Rebus package allows you to use the Rebus as the distributed event bus for the ABP Framework.

See the documentation to learn how to use Rebus with the ABP Framework.

Async Repository LINQ Extension Methods

You have a problem when you want to use Async LINQ Extension Methods (e.g. FirstOrDefaultAsync(...)) in your domain and application layers. These async methods are not included in the standard LINQ extension methods. Those are defined by the Microsoft.EntityFrameworkCore NuGet package (see the code). To be able to use these async methods, you need to reference to the Microsoft.EntityFrameworkCore package.

If you don't want to depend on the EF Core in your business layer, then ABP Framework provides the IAsyncQueryableExecuter service to execute your queries asynchronously without depending on the EF Core package. You can see the documentation to get more information about this service.

ABP Framework version 3.3 takes this one step further and allows you to directly execute the async LINQ extension methods on the IRepository interface.

Example: Use CountAsync and FirstOrDefaultAsync methods on the repositories

using System;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;
using Volo.Abp.Domain.Repositories;

namespace MyCompanyName.MyProjectName
{
    public class BookAppService : ApplicationService, IBookAppService
    {
        private readonly IRepository<Book, Guid> _bookRepository;

        public BookAppService(IRepository<Book, Guid> bookRepository)
        {
            _bookRepository = bookRepository;
        }

        public async Task DemoAsync()
        {
            var countAll = await _bookRepository
                .CountAsync();

            var count = await _bookRepository
                .CountAsync(x => x.Name.Contains("A"));

            var book1984 = await _bookRepository
                .FirstOrDefaultAsync(x => x.Name == "1984");            
        }
    }
}

All the standard LINQ methods are supported: AllAsync, AnyAsync, AverageAsync, ContainsAsync, CountAsync, FirstAsync, FirstOrDefaultAsync, LastAsync, LastOrDefaultAsync, LongCountAsync, MaxAsync, MinAsync, SingleAsync, SingleOrDefaultAsync, SumAsync, ToArrayAsync, ToListAsync.

This approach still has a limitation. You need to execute the extension method directly on the repository object. For example, the below usage is not supported:

var count = await _bookRepository.Where(x => x.Name.Contains("A")).CountAsync();

This is because the object returned from the Where method is not a repository object, it is a standard IQueryable. In such cases, you can still use the IAsyncQueryableExecuter:

var count = await AsyncExecuter.CountAsync(
    _bookRepository.Where(x => x.Name.Contains("A"))
);

AsyncExecuter has all the standard extension methods, so you don't have any restriction here. See the repository documentation for all the options you have.

ABP Framework does its best to not depend on the EF Core and still be able to use the async LINQ extension methods. However, there is no problem to depend on the EF Core for your application, you can add the Microsoft.EntityFrameworkCore NuGet package and use the native methods.

Stream Support for the Application Service Methods

Application services are consumed by clients and the parameters and return values (typically Data Transfer Objects). In case of the client is a remote application, then these objects should be serialized & deserialized.

Until the version 3.3, we hadn't suggest to use the Stream in the application service contracts, since it is not serializable/deserializable. However, with the version 3.3, ABP Framework properly supports this scenario by introducing the new IRemoteStreamContent interface.

Example: An application service that can get or return streams

using System;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;
using Volo.Abp.Content;

namespace MyProject.Test
{
    public interface ITestAppService : IApplicationService
    {
        Task Upload(Guid id, IRemoteStreamContent streamContent);
        Task<IRemoteStreamContent> Download(Guid id);
    }
}

The implementation can be as shown below:

using System;
using System.IO;
using System.Threading.Tasks;
using Volo.Abp;
using Volo.Abp.Application.Services;
using Volo.Abp.Content;

namespace MyProject.Test
{
    public class TestAppService : ApplicationService, ITestAppService
    {
        public Task<IRemoteStreamContent> Download(Guid id)
        {
            var fs = new FileStream("C:\\Temp\\" + id + ".blob", FileMode.OpenOrCreate);
            return Task.FromResult(
                (IRemoteStreamContent) new RemoteStreamContent(fs) {
                    ContentType = "application/octet-stream" 
                }
            );
        }

        public async Task Upload(Guid id, IRemoteStreamContent streamContent)
        {
            using (var fs = new FileStream("C:\\Temp\\" + id + ".blob", FileMode.Create))
            {
                await streamContent.GetStream().CopyToAsync(fs);
                await fs.FlushAsync();
            }
        }
    }
}

This is just a demo code. Do it better in your production code :)

Thanks to @alexandru-bagu for the great contribution!

Other Changes

• Upgraded all the .NET Core / ASP.NET Core related packages to the version 3.1.8. If you have additional dependencies to the .NET Core / ASP.NET Core related packages, we suggest you to updates your packages to the version 3.1.8 to have the latest bug and security fixes published by Microsoft.
• The blogging module now uses the BLOB Storing system to store images & files of the blog posts. If you are using this module, then you need to manually migrate the local files to the BLOB Storing system after the upgrade.
• The Angular UI is now redirecting to the profile management page of the MVC UI instead of using its own UI, if you've configured the authorization code flow (which is default since the version 3.2.0).

What's new in the ABP Commercial 3.3

The Blazor UI

We have good news for the ABP Commercial Blazor UI too. We have implemented the Lepton Theme integration, so it is now available with the Blazor UI. Also, implemented most of the fundamental modules.

A screenshot from the ABP Commercial startup template with the Blazor UI

There are still missing features and modules. However, we are working on it to have a more complete version in the next release.

Breaking Changes on the Blazor UI

There are some breaking changes with the Blazor UI. If you've built an application and upgrade it, your application might not properly work. See the ABP Commercial Blazor UI v 3.3 Migration Guide for the changes you need to do after upgrading your application.

Known Issues

When you create a new project, profile management doesn't work, you get an exception because it can't find the /libs/cropperjs/css/cropper.min.css file. To fix the issue;

• Add "@volo/account": "^3.3.0-rc.2" to the package.json in the .Host project.
• Run yarn (or npm install), then gulp on a command line terminal in the root folder of the .Host project.

Multi-Tenant Social Logins

Account module now supports to manage the social/external logins in the UI. You can enable/disable and set options in the settings page. It also supports to use different credentials for the tenants and it is also configured on the runtime.

Linked Accounts

Linked user system allows you to link other accounts (including account in a different tenant) with your account, so you can switch between different accounts with a single-click. It is practical since you no longer need to logout and login again with entering the credentials of the target account.

To manage the linked accounts, go to the profile management page from the user menu;

Paypal & Stripe Integrations

The Payment Module was supporting PayU and 2Checkout providers until the version 3.3. It's now integrated to PayPal and Stripe. See the technical documentation to learn how to use it.

ABP Suite Improvements

We've done a lot of small improvements for the ABP Suite. Some of the enhancements are;

• Show the previously installed modules as installed on the module list.
• Switch between the latest stable, the latest preview and the latest nightly build versions of the ABP related packages.
• Moved the file that stores the previously created entities into the solution folder to allow you to store it in your source control system.

Others

• Added an option to the Account Module to show reCAPTCHA on the login & the registration forms.

Besides the new features introduced in this post, we've done a lot of small other enhancements and bug fixes to provide a better development experience and increase the developer productivity.

New Articles

The core ABP Framework team & the community continue to publish new articles on the ABP Community web site. The recently published articles are;

• Replacing Email Templates and Sending Emails (by @EngincanV)
• How to Add Custom Properties to the User Entity (by @berkansasmaz)
• Using the AdminLTE Theme with the ABP Framework MVC / Razor Pages UI (by @mucahiddanis)
• Using DevExtreme Angular Components With the ABP Framework (by @bunyamin)

It is appreciated if you want to submit an article related to the ABP Framework.

About the Next Release

The next version will be 4.0.0. We are releasing a major version, since we will move the ABP Framework to .NET 5.0. We see that for most of the applications this will not be a breaking change and we hope you easily upgrade to it.

The planned 4.0.0-rc.1 (Release Candidate) version date is November 11, just after the Microsoft releases the .NET 5.0 final. The planned 4.0.0 final release date is November 26.

Follow the GitHub milestones for all the planned ABP Framework version release dates.

Feedback

Please check out the ABP Framework 3.3.0 RC and provide feedback to help us to release a more stable version. The planned release date for the 3.3.0 final version is October 27th.

Since all the new features are already explained in detail with the 3.2 RC Announcement Post, I will not repeat all the details again. Please read the RC post for new features and changes you may need to do for your solution while upgrading to version 3.2.

Creating New Solutions

You can create a new solution with the ABP Framework version 3.2 by either using the abp new command or using the direct download tab on the get started page.

See the getting started document for details.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

After the update command, check the RC blog post to learn if you need to make any changes in your solution.

You may want to see the new upgrading document.

About the Next Versions

The next two versions (3.3 & 4.0) will be mostly related to completing the Blazor UI features and upgrading the ABP Framework & ecosystem to the .NET 5.0.

The ultimate goal is to complete the version 4.0 with a stable Blazor UI with the fundamental features implemented and publish it just after the Microsoft lunches .NET 5 in this November.

The Blazor UI

While the Blazor UI should be considered as experimental for now, it is possible to start to develop your application today.

Fundamental Services

Currently, implemented some important framework features;

• Authentication through the MVC backend using the OpenId Connect authorization code flow. So, all the current login options (login, register, forgot password, external/social logins...) are supported.
• Authorization, using the ABP Framework permissions as well as the standard authorization system.
• Localization just works like the MVC UI.
• Basic Theme with the top main menu.
• Dynamic C# HTTP API proxies, so you can directly consume your backend API by injecting the application service interfaces.
• Some other fundamental services like ISettingProvider, IFeatureChecker, ICurrentUser...

Also, the standard .net services are already available, like caching, logging, validation and much more. Since the ABP Framework has layered itself, all the non-MVC UI related features are already usable for the Blazor UI.

Pre-Built Modules

Some modules have been implemented;

• Identity module is pre-installed and provides user, role and permission management.
• Profile management page is implemented to allow to change the password and personal settings.

About the Blazorise Library

We've selected the Blazorise as a fundamental UI library for the Blazor UI. It already supports different HTML/CSS frameworks (like Bootstrap, Bulma, Ant Design...) and significantly increases the developer productivity.

We also have good news: Mladen Macanović, the creator of the Blazorise, is joining to the core ABP Framework team in the next weeks. We are excited to work with him to bring the power of these two successful projects together.

The Tutorial

We've updated the web application development tutorial for the Blazor UI. You can start to develop applications today! The source code of the BookStore application developed with this tutorial is here.

Get started with the Blazor UI

If you want to try the Blazor UI today, follow the instructions below.

Upgrade the ABP CLI

Install the latest ABP CLI preview version:

dotnet tool update Volo.Abp.Cli -g --version 3.2.0-rc.2

Create a new Solution

Then you can create a new solution using the abp new command:

abp new AbpBlazorDemo -u blazor --preview

Also, specify the -t app-pro parameter if you are an ABP Commercial user.

See the ABP CLI documentation for the additional options, like MongoDB database or separated authentication server.

Open the Solution

Open the generated solution using the latest Visual Studio 2019. You will see a solution structure like the picture below:

Run the Application

• Run the DbMigrator project to create the database and seed the initial data.
• Run the HttpApi.Host project for the server-side.
• Run the Blazor project to start the Blazor UI.

Use admin as the username and 1q2w3E* as the password to login to the application.

Here, a screenshot from the role management page of the Blazor UI:

What's New with the ABP Framework 3.2

Besides the Blazor UI, there are a lot of issues that have been closed with the milestone 3.2. I will highlight some of the major features and changes released with this version.

MongoDB ACID Transactions

MongoDB integration now supports multi-document transactions that comes with the MongoDB 4.x.

We've disabled transactions for solutions use the MongoDB, inside the YourProjectMongoDbModule.cs file in the MongoDB project. If your MongoDB server supports transactions, you should manually enable it in this class:

Configure<AbpUnitOfWorkDefaultOptions>(options =>
{
    options.TransactionBehavior = UnitOfWorkTransactionBehavior.Auto;
});

Or you can delete this code since this is already the default behavior.

Upgrade Notes

If you are upgrading an existing solution and your MongoDB server doesn't support transactions, please disable it:

Configure<AbpUnitOfWorkDefaultOptions>(options =>
{
    options.TransactionBehavior = UnitOfWorkTransactionBehavior.Disabled;
});

See the Unit Of Work document to learn more about UOW and transactions.

Also, add this file into your MongoDB project (remember to change MongoDbMyProjectNameDbSchemaMigrator and IMyProjectNameDbSchemaMigrator with your own project name).

Integration Tests

Transactions are also disabled for automated integration tests coming with the application startup template, since the Mongo2Go library (we use in the test projects) has a problem with the transactions. We've sent a Pull Request to fix it and will enable the transactions again when they merge & release it.

If you are upgrading an existing solution and using MongoDB, please disable transactions for the test projects just as described above.

Kafka Integration for the Distributed Event Bus

ABP Framework's distributed event system has been integrated to RabbitMQ before. By the version 3.2, it has a Kafka integration package, named Volo.Abp.EventBus.Kafka.

See the Kafka integration documentation to learn how to install and configure it.

Host Features

ABP Feature System allows you to define features in your application. Then you can enable/disable a feature dynamically on the runtime. It is generally used in a multi-tenant system to restrict features for tenants, so you can charge extra money for some features in a SaaS application.

In some cases, you may want to use the same features in the host side (host is you as you are managing the tenants). For this case, we've added a "Manage Host Features" button to the Tenant Management page so you can open a modal dialog to select the features for the host side.

AbpHttpClientBuilderOptions

ABP Framework provides a system to dynamically create C# proxies to consume HTTP APIs from your client applications. AbpHttpClientBuilderOptions is a new option class to configure the HttpClients used by the proxy system.

Example: Use the Polly library to retry up to 3 times for a failed HTTP request

public override void PreConfigureServices(ServiceConfigurationContext context)
{
    PreConfigure<AbpHttpClientBuilderOptions>(options =>
    {
        options.ProxyClientBuildActions.Add((remoteServiceName, clientBuilder) =>
        {
            clientBuilder.AddTransientHttpErrorPolicy(policyBuilder =>
                policyBuilder.WaitAndRetryAsync(
                    3,
                    i => TimeSpan.FromSeconds(Math.Pow(2, i))
                )
            );
        });
    });
}

See the issue #5304 for the details.

ABP Build Command

We are using mono repository approach and the abp repository has tens of solutions and hundreds of projects (the framework, modules, tooling, templates...) with all of them are referencing to each other.

It gets a significant time to build the whole repository for every Git push. To optimize this process, we've created the abp build command in the ABP CLI:

abp build

We will use this command to build the abp repository or a solution inside it. However, it is available to everyone in case of need.

Most of the people will not need it. If you need it, see the ABP CLI document to learn all the details and options.

Other Features, Improvements and Changes

• Introduced the DynamicRangeAttribute that can be used to determine the range values on runtime, just like the DynamicStringLengthAttribute was introduced before.
• Improved the feature management modal for multi-tenant applications to group features on the UI and show hierarchically.
• Added --skip-cli-version-check option to ABP CLI to improve the performance by bypassing the online version check.
• Angular UI now redirect to MVC UI (the authentication server-side) for profile management page, if the authorization code flow is used (which is the default).
• Account module profile management page is now extensible. You can implement the IProfileManagementPageContributor interface and register it using the ProfileManagementPageOptions class.
• Improvements and optimizations for the Angular service proxy generation.

And a lot of minor improvements and bug fixes. You can see the milestone 3.2 for all issues & PRs closed with this version.

What's New with the ABP Commercial 3.2

Breaking Changes

The new profile picture management feature uses the BLOB storing system, so it needs a Storage Provider. The new startup template comes with the Database BLOB Provider pre-installed. You can change it if you want to use another BLOB provider (like Azure, AWS or a simple file system).

Existing solutions must configure a BLOB provider after upgrading to the version 3.2. Follow the BLOB Storing document to configure the provider yourself.

The Blazor UI

The experimental Blazor UI is also available for the ABP Commercial. The Lepton Theme hasn't been implemented with this initial preview, however we are working on it with the highest priority.

You can use the ABP Suite or the following ABP CLI command to create a new solution with the Blazor UI:

abp new AbpBlazorDemo -u blazor -t app-pro --preview

Please try it and provide feedback to us. Thanks in advance.

See the instructions in the Get started with the Blazor UI section above to properly create and run your application.

File Management Angular UI

Angular UI for the File Management module is available with version 3.2. You can add it to your solution using the ABP Suite.

Profile Picture Management

We've added profile picture management for the account module, so a user can select one of the options below for her profile picture;

• Use the default placeholder as the avatar.
• Use Gravatar service to get the picture matching the email address of the user.
• Upload a file as the profile picture.

Two Factor Authentication Features

Created features and settings to disable, enable or force to use 2FA on login for the tenants and users.

Upgrading the ABP Suite

You can use the following command to upgrade the ABP Suite to the latest preview version:

abp suite update --preview

Other News

The ABP Community

ABP Community web site is constantly being improved and new articles are added. We will add "commenting" and "rating" features to the articles soon to increase the interactivity between the people.

If you have something to share with the ABP community or want to follow the project progress, please check the community.abp.io!

CMS Kit Project

We are silently working on a project, named CMS Kit, for a few months. CMS Kit is a set of reusable CMS (Content Management System) components based on the ABP Framework. Some of the components currently being developed:

• Comments; Allows users to comment under something (a blog post, a document, an image... etc).
• Reactions; Allows users to give reactions to something (a comment, a picture... etc.) using simple emoji icons.
• Rating; Allows users to rate some content from 1 to 5.
• Newsletter; Allows you to put a newsletter box to your web site to collect emails from users.
• Contact; Put a form to get a message from the web site visitors.

There are more planned components like articles, tags, votes, favorites, portfolios, image galleries, FAQs... etc. We will document and deploy these components when they get matured and ready to use. Some of them will be open source & free while some of them are paid (included in the ABP Commercial license).

Feedback

Please try the ABP Framework 3.2.0 RC and provide feedback to help us to release a more stable version. The planned release date for the 3.2.0 final version is October 01.

ABP Angular Service Proxy System generates TypeScript services and models to consume your backend HTTP APIs developed using the ABP Framework. So, you don't manually create models for your server side DTOs and perform raw HTTP calls to the server.

ABP Framework has introduced the new Angular Service Proxy Generation system with the version 3.1. While this feature was available since the v2.3, it was not well covering some scenarios, like inheritance and generic types and had some known problems. With the v3.1, we've re-written it using the Angular Schematics system. Now, it is much more stable and feature rich.

This post introduces the service proxy generation system and highlights some important features.

Installation

ABP CLI

You need to have the ABP CLI to use the system. So, install it if you haven't installed before:

dotnet tool install -g Volo.Abp.Cli

If you already have installed it before, you can update to the latest version:

dotnet tool update -g Volo.Abp.Cli

Project Configuration

If you've created your project with version 3.1 or later, you can skip this part since it will be already installed in your solution.

For a solution that was created before v3.1, follow the steps below to configure the angular application:

• Add @abp/ng.schematics package to the devDependencies of the Angular project. Run the following command in the root folder of the angular application:

npm install @abp/ng.schematics --save-dev

• Add rootNamespace entry into the apis/default section in the /src/environments/environment.ts, as shown below:

apis: {
  default: {
    ...
    rootNamespace: 'Acme.BookStore'
  },    
}

Acme.BookStore should be replaced by the root namespace of your .NET project. This ensures to not create unnecessary nested folders while creating the service proxy code. This value is AngularProxyDemo for the example solution explained below.

• Finally, add the following paths to the tsconfig.base.json to have a shortcut while importing proxies:

"paths": {
    "@proxy": ["src/app/proxy/index.ts"],
    "@proxy/*": ["src/app/proxy/*"]
}

Basic Usage

Project Creation

If you already have a solution, you can skip this section.

You need to create your solution with the Angular UI. You can use the ABP CLI to create a new solution:

abp new AngularProxyDemo -u angular

Run the Application

The backend application must be up and running to be able to use the service proxy code generation system.

See the getting started guide if you don't know details of creating and running the solution.

Backend

Assume that we have an IBookAppService interface:

using System.Collections.Generic;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;

namespace AngularProxyDemo.Books
{
    public interface IBookAppService : IApplicationService
    {
        public Task<List<BookDto>> GetListAsync();
    }
}

That uses a BookDto defined as shown:

using System;
using Volo.Abp.Application.Dtos;

namespace AngularProxyDemo.Books
{
    public class BookDto : EntityDto<Guid>
    {
        public string Name { get; set; }

        public DateTime PublishDate { get; set; }
    }
}

And implemented as the following:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;

namespace AngularProxyDemo.Books
{
    public class BookAppService : ApplicationService, IBookAppService
    {
        public async Task<List<BookDto>> GetListAsync()
        {
            //TODO: get books from a database...
        }
    }
}

It simply returns a list of books. You probably want to get the books from a database, but it doesn't matter for this article.

HTTP API

Thanks to the auto API controllers system of the ABP Framework, we don't have to develop API controllers manually. Just run the backend (HttpApi.Host) application that shows the Swagger UI by default. You will see the GET API for the books:

Service Proxy Generation

Open a command line in the root folder of the Angular application and execute the following command:

abp generate-proxy

It should produce an output like the following:

...
CREATE src/app/proxy/books/book.service.ts (446 bytes)
CREATE src/app/proxy/books/models.ts (148 bytes)
CREATE src/app/proxy/books/index.ts (57 bytes)
CREATE src/app/proxy/index.ts (33 bytes)

generate-proxy command can take some some optional parameters for advanced scenarios (like modular development). You can take a look at the documentation.

The Generated Code

src/app/proxy/books/book.service.ts: This is the service that can be injected and used to get the list of books;

import type { BookDto } from './models';
import { RestService } from '@abp/ng.core';
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root',
})
export class BookService {
  apiName = 'Default';

  getList = () =>
    this.restService.request<any, BookDto[]>({
      method: 'GET',
      url: `/api/app/book`,
    },
    { apiName: this.apiName });

  constructor(private restService: RestService) {}
}

src/app/proxy/books/models.ts: This file contains the modal classes corresponding to the DTOs defined in the server side;

import type { EntityDto } from '@abp/ng.core';

export interface BookDto extends EntityDto<string> {
  name: string;
  publishDate: string;
}

There are a few more files have been generated to help you import the types easier.

How to Import

You can now import the BookService into any Angular component and use the getList() method to get the list of books.

import { BookService, BookDto } from '../proxy/books';

You can also use the @proxy as a shortcut of the proxy folder:

import { BookService, BookDto } from '@proxy/books';

About the Generated Code

The generated code is;

• Simple: It is almost identical to the code if you've written it yourself.
• Splitted: Instead of a single, large file;
  • It creates a separate .ts file for every backend service. Model (DTO) classes are also grouped per service.
  • It understands the modularity, so creates the services for your own module (or the module you've specified).
• Object oriented;
  • Supports inheritance of server side DTOs and generates the code respecting to the inheritance structure.
  • Supports generic types.
  • Supports re-using type definitions across services and doesn't generate the same DTO multiple times.
• Well-aligned to the backend;
  • Service method signatures match exactly with the services on the backend services. This is achieved by a special endpoint exposed by the ABP Framework that well defines the backend contracts.
  • Namespaces are exactly matches to the backend services and DTOs.
• Well-aligned with the ABP Framework;
  • Recognizes the standard ABP Framework DTO types (like EntityDto, ListResultDto... etc) and doesn't repeat these classes in the application code, but uses from the @abp/ng.core package.
  • Uses the RestService defined by the @abp/ng.core package which simplifies the generated code, keeps it short and re-uses all the logics implemented by the RestService (including error handling, authorization token injection, using multiple server endpoints... etc).

These are the main motivations behind the decision of creating a service proxy generation system, instead of using a pre-built tool like NSWAG.

Other Examples

Let me show you a few more examples.

Updating an Entity

Assume that you added a new method to the server side application service, to update a book:

public Task<BookDto> UpdateAsync(Guid id, BookUpdateDto input);

BookUpdateDto is a simple class defined shown below:

using System;

namespace AngularProxyDemo.Books
{
    public class BookUpdateDto
    {
        public string Name { get; set; }

        public DateTime PublishDate { get; set; }
    }
}

Let's re-run the generate-proxy command:

abp generate-proxy

This command will re-generate the proxies by updating some files. Let's see some of the changes;

book.service.ts

import type { BookDto, BookUpdateDto } from './models';
import { RestService } from '@abp/ng.core';
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root',
})
export class BookService {
  apiName = 'Default';

  getList = () =>
    this.restService.request<any, BookDto[]>({
      method: 'GET',
      url: `/api/app/book`,
    },
    { apiName: this.apiName });

  update = (id: string, input: BookUpdateDto) =>
    this.restService.request<any, BookDto>({
      method: 'PUT',
      url: `/api/app/book/${id}`,
      body: input,
    },
    { apiName: this.apiName });

  constructor(private restService: RestService) {}
}

update function has been added to the BookService that gets an id and a BookUpdateDto as the parameters.

models.ts

import type { EntityDto } from '@abp/ng.core';

export interface BookDto extends EntityDto<string> {
  name: string;
  publishDate: string;
}

export interface BookUpdateDto {
  name: string;
  publishDate: string;
}

Added a new DTO class: BookUpdateDto.

Advanced Example

In this example, I want to show a DTO structure using inheritance, generics, arrays and dictionaries.

I've created an IOrderAppService as shown below:

using System.Threading.Tasks;
using Volo.Abp.Application.Services;

namespace AngularProxyDemo.Orders
{
    public interface IOrderAppService : IApplicationService
    {
        public Task CreateAsync(OrderCreateDto input);
    }
}

OrderCreateDto and the related DTOs are as the followings;

using System;
using System.Collections.Generic;
using Volo.Abp.Data;

namespace AngularProxyDemo.Orders
{
    public class OrderCreateDto : IHasExtraProperties
    {
        public Guid CustomerId { get; set; }

        public DateTime CreationTime { get; set; }

        //ARRAY of DTOs
        public OrderDetailDto[] Details { get; set; }

        //DICTIONARY
        public Dictionary<string, object> ExtraProperties { get; set; }
    }
    
    public class OrderDetailDto : GenericDetailDto<int> //INHERIT from GENERIC
    {
        public string Note { get; set; }
    }
    
    //GENERIC class
    public abstract class GenericDetailDto<TCount>
    {
        public Guid ProductId { get; set; }

        public TCount Count { get; set; }
    }
}

When I run the abp generate-proxy command again, I see there are some created and updated files. Let's see some important ones;

src/app/proxy/orders/order.service.ts

import type { OrderCreateDto } from './models';
import { RestService } from '@abp/ng.core';
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root',
})
export class OrderService {
  apiName = 'Default';

  create = (input: OrderCreateDto) =>
    this.restService.request<any, void>({
      method: 'POST',
      url: `/api/app/order`,
      body: input,
    },
    { apiName: this.apiName });

  constructor(private restService: RestService) {}
}

src/app/proxy/orders/models.ts

export interface GenericDetailDto<TCount> {
  productId: string;
  count: TCount;
}

export interface OrderCreateDto {
  customerId: string;
  creationTime: string;
  details: OrderDetailDto[];
  extraProperties: Record<string, object>;
}

export interface OrderDetailDto extends GenericDetailDto<number> {
  note: string;
}

Conclusion

abp generate-proxy is a very handy command that creates all the necessary code to consume your ABP based backend HTTP APIs. It generates a clean code that is well aligned to the backend services and benefits from the power of TypeScript (by using generics, inheritance...).

The Documentation

See the documentation for details of the Angular Service Proxy Generation.

It is exciting for us to announce that we've released the ABP Framework & ABP Commercial 3.1 today.

Since all the new features are already explained in details with the 3.1 RC Announcement Post, I will not repeat all the details here. Please read the RC post for new feature and changes you may need to do for your solution while upgrading to the version 3.1.

Creating New Solutions

You can create a new solution with the ABP Framework version 3.1 by either using the abp new command or using the direct download tab on the get started page.

See the getting started document for details.

How to Upgrade an Existing Solution

Install/Update the ABP CLI

First of all, install the ABP CLI or upgrade to the latest version.

If you haven't installed yet:

dotnet tool install -g Volo.Abp.Cli

To update an existing installation:

dotnet tool update -g Volo.Abp.Cli

ABP UPDATE Command

ABP CLI provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:

abp update

After the update command, check the RC blog post to learn if you need to make any changes in your solution.

You may want to see the new upgrading document.

About the version 3.2

The planned schedule for the version 3.2 is like that;

• September 17, 2020: 3.2.0-rc.1 (release candidate)
• October 1, 2020: 3.2.0 final (stable)

You can check the GitHub milestone to see the features/issues we are working on.

ABP Community & Articles

We had lunched the ABP Community web site a few weeks before. The core ABP team and the ABP community have started to create content for the community.

Here, the last three articles from the ABP Community:

• ABP Suite: How to Add the User Entity as a Navigation Property of Another Entity by @ebicoglu
• Reuse ABP vNext Modules to Quickly Implement Application Features by @gdlcf88
• Using DevExtreme Components With the ABP Framework by @cotur.

We are looking for your contributions; You can submit your article! We will promote your article to the community.

There were two main reasons of this long development cycle;

• We've switched to 4-weeks release cycle (was discussed in this issue).
• We've re-written the Angular service proxy generation system using the Angular schematics to make it more stable. There were some problems with the previous implementation.

This long development cycle brings a lot of new features, improvements and bug fixes. I will highlight the fundamental features and changes in this blog post.

3.1.0 final stable version has been published. See this post for details.

About the Preview/Stable Version Cycle

As mentioned above, it is planned to release a new stable feature version (like 3.1, 3.2, 3.3...) in every 4-weeks.

In addition, we are starting to deploy a preview version 2-weeks before the stable versions for every feature/major releases.

Today, we've released 3.1.0-rc.1 as the first preview version. We may release more previews if it is needed until the stable 3.1.0 version.

The stable 3.1.0 version will be released on September 3, 2020. Next RC version, 3.2.0-rc.1, is planned for September 17, 2020 (2 weeks after the stable 3.1.0 and 2 weeks before the stable 3.2.0).

We won't add new features to a version after publishing the preview version. We only will make bug fixes until the stable version. The new features being developed in this period will be available in the next version.

We will use -rc.x suffix (like 3.1.0-rc.1 and 3.1.0-rc.2) for preview releases. However, we may also publish with -preview.x suffix before RC (Release Candidate) releases, especially for major versions (like 4.0, 5.0...).

About the Nightly Builds

Don't confuse preview versions vs nightly builds. When we say preview, we are mentioning the preview system explained above.

We will continue to publish nightly builds for all the ABP Framework packages. Nightly pages are built from the development branch. You can refer to this document to learn how to use the nightly packages.

Get Started with the RC Versions

Please try the preview versions and provide feedback to us to release more stable versions. Please open an issue on the GitHub repository if you find a bug or want to give feedback.

Update the ABP CLI to the 3.1.0-rc.4

Since this is the first preview version, you need to upgrade the ABP CLI to the 3.1.0-rc.4 to be able to use the preview features:

dotnet tool update Volo.Abp.Cli -g --version 3.1.0-rc.4

New Solutions

The ABP.IO platform and the ABP CLI are compatible with the RC system. You can select the "preview" option on the download page or use the "--preview" parameter with the ABP CLI new command:

abp new Acme.BookStore --preview

This command will create a new project with the latest RC/Preview version. Whenever the stable version is released, you can switch to the stable version for your solution using the abp switch-to-stable command in the root folder of your solution.

Existing Solutions

If you already have a solution and want to use/test the latest RC/Preview version, use the abp switch-to-preview command in the root folder of your solution. You can return back to the latest stable using the abp switch-to-stable command later.

Note that the abp switch-to-preview command was being used to switch to nightly builds before the v3.1. Now, you should use the abp switch-to-nightly for nightly builds.

Breaking Changes / Special Notes

ABP & ABP Commercial

• You may need to upgrade the Microsoft.Extensions.FileProviders.Embedded package in your projects to 3.1.6 or a later version.
• If you are using EF Core, you may need to add a new migration after upgrading the packages. Just run the standard "Add-Migration" command, check the generated migration code and execute the "Update-Database" command to apply changes to the database.
• If you have implemented social/external logins for your MVC / Razor Page UI application before, you may want to check this issue. We made some improvements and changes that you may want to take action for your application. Beginning from v3.1, the users created their accounts via social login can still set a local password to login with local username/email & password.
• See the "Angular Service Proxies" section below for the Angular applications.

ABP Commercial Only

• We've moved favicons into /wwwroot/images/favicon/ folder for the ASP.NET Core MVC / Razor Page UI applications. There are 10 favicon related files (including the favicon.ico) under this directory to better work with different browser and cases. You can create a new application to check this folder and copy the files into your own application. Then you can customize the icons for your own brand (hint: you can use a tool like that to create the favicons with various formats).
• Removed direct Twitter & Facebook social login integrations from the account module, for MVC / Razor Pages UI. Follow this documentation to easily add social logins to your applications if you need. The account module provides all the infrastructure to handle social/external logins, you just need to configure it.

What's New with the ABP Framework 3.1 RC

Angular Service Proxies

ABP provides a system to generate Angular service proxies (with TypeScript) to consume the HTTP APIs of your application. Service proxy generation system has been completely re-written with the ABP Framework 3.1. The main goal was to build more stable and feature rich system that is better aligned with other ABP Framework features (like modularity).

You will continue to use the same abp generate-proxy command, however it internally uses an NPM package that implements the command using the Angular schematics. It will come pre-configured for new solutions. However, implement the following steps for existing solutions;

• Add @abp/ng.schematics package to the devDependencies of the Angular project.
• Add rootNamespace entry into the /apis/default/ section in the /src/environments/environment.ts, as shown below:

apis: {
  default: {
    url: 'https://localhost:44360',
    rootNamespace: 'Acme.BookStore' //<-- ADD THIS
  },    
}

Acme.BookStore should be replaced by the root namespace of your .NET project. This ensures to not create unnecessary nested folders.

• Finally, add the following paths to the tsconfig.base.json to have a shortcut while importing proxies:

"paths": {
    "@proxy": ["src/app/proxy/index.ts"],
    "@proxy/*": ["src/app/proxy/*"]
}

See the documentation to learn more about the service proxy generation for Angular applications.

The application development tutorial has been updated based on the new Angular Service proxy system.

Authorization Code Flow for the Angular UI

We were using the resource owner password authentication flow for the Angular UI login page. We've implemented Authorization Code Flow for the Angular account module and made it default for new projects. With this change, the Angular application now redirects to the login page of the MVC UI which was implemented using the Identity Server 4. We also removed the client secret from the Angular side with this change.

Old behavior remains exist. If you want to switch to the new flow (which is recommended), follow the steps below:

1. Add authorization_code to the IdentityServerClientGrantTypes table in the database, for the client used by the Angular UI (the ClientId is YourProjectName_App by default, in the IdentityServerClients table).

2. Add http://localhost:4200 to IdentityServerClientRedirectUris and IdentityServerClientPostLogoutRedirectUris tables for the same client.

3. Set RequireClientSecret to false in the IdentityServerClients table for the same client.

ABP Commercial users can make these changes on the Identity Server Management UI.

4. Change the oAuthConfig section in the src/environments/environment.ts file of the Angular application.

You can take this new configuration as a reference. Main changes are;

• Added responseType as code.
• Added redirectUri
• Added offline_access to the scope.
• Removed oidc: false option.
• Removed the client secret option.

Global Feature System

The new "Global Features" system allows to enable/disable features of an application or a module in a central point. It is especially useful if you want to use a module but don't want to bring all its features into your application. If the module was so designed, you can enable only the features you need.

When you disable a feature;

• The database tables related to that feature should not be created in the database.
• The HTTP APIs related to that feature should not be exposed. They returns 404 if they are directly requested.

So, the goal is that; when you disable a feature, it should behave like that feature doesn't exists in your system at all.

There is no way to enable/disable a global feature on runtime. You should decide it in the development time (remember, even database tables are not being created for disabled global features, so you can't enable it on runtime).

"Global Features" system is different than SaaS/multi-tenancy features, where you can enable/disable features for your tenants on runtime.

Assume that you are using the CMS Kit module (this module is in a very early stage) where you only want to enable the comment feature:

GlobalFeatureManager.Instance.Modules.CmsKit().Comments.Enable();

You can check if a feature was enabled:

GlobalFeatureManager.Instance.IsEnabled<CommentsFeature>();

Or you can add [RequiresGlobalFeature(...)] attribute to a controller/page to disable it if the related feature was disabled:

//...
[RequiresGlobalFeature(typeof(CommentsFeature))]
public class CommentController :  AbpController
{
    //...
}

See the issue #5061 until this is fully documented.

Social/External Logins

Implemented the infrastructure for social/external logins in the account module. So, now you can easily configure your application to support social/external logins by following the documentation. Once you configure a provider, a button will appear on the login page to use this provider.

The social logins will work as expected even if you are using the Angular UI, since the Angular UI uses the MVC login using the authorization code flow implemented with this new version (as explained above).

Forgot/Reset Password

Implemented forgot password / password reset for the account module.

You can now enter your email address to get an email containing a password reset link:

When you click to the link, you are redirected to a password reset page to determine your new password:

External Login System

The standard Social/External Login system (like Facebook login) works via OpenID Connect. That means the user is redirected to the login provider, logins there and redirected to your application.

While this is pretty nice for most scenarios, sometimes you want a simpler external login mechanism: User enters username & password in your own application's login form and you check the username & password from another source, not from your own database.

ABP v3.1 introduces an External Login System to check username & password from any source (from an external database, a REST service or from an LDAP / Active Directory server).

You can check the issue #4977 until it is fully documented.

We've implemented LDAP authentication for the ABP Commercial, using this new login extension system (see the ABP Commercial section below).

User Security Logs

The new Security Log System (of the Identity module) automatically logs all authentication related operations (login, logout, change password...) to a AbpSecurityLogs table in the database.

New BLOB Storage Providers

Implemented AWS and Aliyun providers for the BLOB storing system with this version.

Module Entity Extensibility

We had introduced a entity extension system that allows to add new properties to existing entities of depended modules by a simple configuration. When you add a new property, it appears on the create, edit and list views on the UI and created a new field in the related database table. We've implemented this system for the identity and tenant management modules, so you can extend entities of these modules. See the documentation.

Other Features / Highlights

Here, some other highlights from this release;

• UOW level caching system #4796
• Refactored the console application template to better integrate to the host builder #5006
• Volo.Abp.Ldap package now supports multi-tenancy.
• Introduce BasicAggregateRoot base class #4808
• Sets GUID Id in the InsertAsync method of the EF Core repository if it was not set by the developer #4634
• Added GetPagedListAsync methods to the repository to simplify paging #4617
• Configured Prettier for the startup template #4318
• Defined new layout hooks for the MVC UI: before page content & after page content #4008
• Allow to put static resources (js, css... files) under the Components folder for ASP.NET Core MVC UI.
• Upgraded to AutoMapper 10 and Quartz 3.1 for the related integration packages.

What's New with the ABP Commercial v3.1 RC

Security Logs UI

We've created a UI to report user security logs for authentication related operations, under the Identity Management menu:

Also, every user can see his/her own security logs by selecting the "My security logs" under the user menu:

LDAP Authentication

We've implemented LDAP authentication using the new external login system explained above. Also, created a UI to configure the server settings:

In this way, you can simply check passwords of the users from LDAP in the login page. If given username / password doesn't exists on LDAP, then it fallbacks to the local database, just like before.

Since it supports multi-tenancy, you can enable, disable and configure it for your tenants.

Email / Phone Number Verification

User profile management page now supports to Email & Phone Number verification flow:

When user clicks to the verify button, a verification email/SMS (that has a verification code) sent to the user and the UI waits to submit this code.

User Lock

Implemented to lock a user for a given period of time. Locked users can not login to the application for the given period of time:

ABP Suite: Angular UI Code Generation Revisited

Angular UI code generation has been re-written using the Angular Schematics for the ABP Suite. It is now more stable and produces a better application code.

ABP Suite also supports code generation on module development.

Others

• Social logins and authorization code flow are also implemented for the ABP Commercial, just as described above.
• Added breadcrumb and file icons for the file management module.

The ABP Community

We've lunched the community.abp.io ~two weeks ago with its initial version. It only has "Article submission" system for now. We are developing new exciting features. There will be an update in a few days and we'll publish a new blog post for it.

Conclusion

The main goals of the 3.1 version were;

• Complete the missing authentication features (like social logins, LDAP authentication, authorization code flow for the Angular UI...) for the ABP Framework & ABP Commercial.
• Re-write a stable and feature complete Angular service proxy generation system for the ABP Framework and CRUD UI generation system for the ABP Commercial.
• Develop a system to lunch preview versions of the platform. 3.1.0-rc.1 was the first preview version that has been published with this new system.
• Complete the fundamental documentation & tutorials (we've even created a video tutorial series).

ABP.IO platform will be more mature & stable with the v3.1. Enjoy Coding!

Bonus: Articles!

Beside developing our products, our team are constantly writing articles/tutorials on various topics. You may want to check the latest articles:

• ASP.NET CORE 3.1 Social Login and Multi-Tenancy
• File Upload/Download with BLOB Storage System in ASP.NET Core & ABP Framework
• Extracting and Hashing Lazy-Loaded CSS in Angular

We’d love to hear from you. Please leave your comments, suggestions, feeedbacks below.

Since this is a major version, it also includes some breaking changes. Don't panic, the changes are easy to adapt and will be explained below.

See the GitHub release notes for a detailed change log.

What's New with the ABP Framework 3.0?

This post will only cover the important features/changes. You can see all the changes on the GitHub release notes.

Angular 10!

Angular version 10 has just been released and we've immediately migrated the startup templates to Angular 10! So, when you create a new solution with the Angular UI, you will take the advantage of the new Angular.

We've prepared a migration guide for the projects created an older version and want to migrate to Angular 10.

The Oracle Integration Package

We had created an integration package for the Oracle for EF Core based applications using the Devart's library since the official Oracle EF Core package was not supporting the EF Core 3.1. It now supports as a beta release. While it is in beta, we've created the integration package, so you can use it in your application.

See the documentation for details.

Azure BLOB Storage Provider

We had created a BLOB storing system in the previous version with a file system and database storage provider. This release introduces the Azure BLOB Storage provider. See the documentation.

Distributed Cache Bulk Operations & the New Redis Cache Package

The standard IDistributeCache interface of the ASP.NET Core doesn't contain bulk operations, like setting multiple items with a single method/server call. ABP Framework introduces new methods those can be used for bulk operations on the ABP's IDistributedCache<T> interface:

• GetManyAsync / GetMany
• SetManyAsync / SetMany

Then we needed to implement these new methods for Redis cache and had to create a Redis integration package which extends the Microsoft's implementation.

These methods are also used by the ABP Framework to cache settings, features and permissions for a user/role/tenant and brings a significant performance improvement.

See the caching document for details.

Embedded Files Manifest Support for the Virtual File System

Virtual File System now supports to use GenerateEmbeddedFilesManifest in your projects to add the real file/directory structure of your embedded resources in the compiled assembly. So, you can now access to the files without any file name restriction (previously, some special chars like . in the directory names was a problem in some cases)

See the documentation to learn how to take the advantage of new system.

New Samples

Based on the requests from the community, we've prepared two new sample applications:

• StoredProcedureDemo demonstrates how to call stored procedures, views and functions inside a custom repository.
• OrganizationUnitSample shows how to use the organization unit system of the Identity module for your entities.

DynamicStringLength & DynamicMaxLength Attributes

The standard StringLength and MaxLength data annotation attributes is useful to validate properties of a class when the class is used as a Model or DTO. However, just like any other attribute, the length values should be literal (constant) values known at compile time.

Example: Using the StringLength

public class CreateBookDto
{
    public const int MaxNameLength = 128; //CONSTANT!
    
    [StringLength(MaxNameLength)]
    public string Name { get; set; }
}

ABP Framework now has the DynamicStringLength & DynamicMaxLength properties to allow to determine the lengths at runtime.

Example: Using the DynamicStringLength

public class CreateBookDto
{
    public static int MaxNameLength { get; set; } = 128;
    
    [DynamicStringLength(typeof(CreateBookDto), nameof(MaxNameLength))]
    public string Name { get; set; }
}

DynamicStringLength gets a class type and the name of a static property on this class to read the max length (there is also a minimum length option just like the StringLength).

This allows you to get the max value from a configuration and set on the application startup (generally, in the PreConfigureServices method of your module):

CreateBookDto.MaxNameLength = 200;

This feature is used by the pre-built application modules, so you can now override the max lengths of the properties defined in these modules.

Auto Distributed Events

ABP can automatically publish distributed events for all entities on their create, update and delete events. That's pretty useful since you commonly interest in these basic events in a distributed system.

This feature is mature and documented with the v3.0. You can easily configure some or all the entities to be published.

IAsyncQueryableExecuter

When you work with LINQ extension methods, you need to call ToListAsync(), FirstOrDefaultAsync()... methods on your queries. Unfortunately, these methods are not standard LINQ extension methods. They are defined in the Microsoft.EntityFrameworkCore package (or in the MongoDB.Driver package if you are using the MongoDB).

So, you need to depend on this package if you want to use the async extension methods. That breaks the layering and makes your application or domain layer depends on the EF Core / MongoDB package.

IAsyncQueryableExecuter is a service defined by the ABP Framework to execute queries asynchronously without depending the specific provider (EF Core / MongoDB) package.

See the documentation to read the details and learn our recommendations.

API documentation

We are now publishing API documents for the ABP Framework and modules in every release. So, you can explore the ABP Framework classes much more easier than before. Click the the API Documentation link on the navigation menu of the documentation.

Package List

We have created a page to list all the ABP-related official NuGet and NPM packages.

Others

• Implemented front-channel server-side clients sign out for the identity server.
• abp.currentUser (CurrentUser service in the Angular UI) now has a roles array that contains role names of the current user.
• Upgraded all the NuGet and NPM package dependencies.
• Introduced ReadOnlyAppService base class (which has only the get operations) in addition to the CrudAppService base class (which has get, create, update and delete operations).

See the GitHub release notes for others updates.

What's New with the ABP Commercial 3.0?

In addition to all the features coming with the ABP Framework, the ABP Commercial has additional features with this release, as always. This section covers the ABP Commercial highlights in the version 3.0.

New File Management Module

We've created a new module that is used to store and manage files in your application. This new module is based on the BLOB Storing system, so it can use different storage providers to store the file contents.

Example screenshot

You can upload, download and organize files in a hierarchical folder structure. It is also compatible to multi-tenancy and you can determine total size limit for your tenants. In the next versions, we will be working on a "share" system to share files between users in a more controlled way or share your files with your customers with a public link.

File Management module is currently available only for the MVC / Razor Pages UI. We are working on the Angular UI and it will be released in the next versions.

Breaking Changes

Since this is a major version, we've redesigned some APIs and introduced a few "easy to fix" breaking changes.

ABP Framework

• Changed some consts in the pre-built application modules to static properties that is possible to change by your code. If you've used these consts on an attribute, then use the DynamicStringLength as explained above.
• Changed ConcurrencyStamp max length to 40. You need to add a database migration and update your database after upgrading the ABP Framework.
• Using ~ instead of ^ for NPM package dependencies anymore, to be more stable.

ABP Commercial

• Changed file names for the application logos. Previously, it was using separate logo files for each theme, like theme1.png, theme1-reverse.png, theme2.png, theme2-reverse.png (... 6). Now, we have only two logo files: logo-light.png and logo-dark.png. So, rename your logo in the wwwroot/images/logo/ folder for the MVC UI and /src/assets/images/logo/ folder for the Angular UI.
• We've added the API documentation for the ABP Commercial too.

Also, see the migration guide for Angular UI.

Known Issues

• 3.0.0 version has a problem with tiered architecture. See this issue to fix it for your application until we release the v3.0.1.

About the Next Versions

We will continue to release a new minor/feature version in every two weeks. So, the next expected release date is 2020-07-16 for the version 3.1.

In the next few versions, we will be focused on the Blazor UI, as promised on the road map. We will continue to improve the documentation, create samples, add other new features and enhancements. Follow the ABP Framework Twitter account for the latest news...

Bonus: Articles!

Beside developing our products, our team are constantly writing articles/tutorials on various topics. You may want to check the latest articles:

• What is New in Angular 10?
• Real-Time Messaging In A Distributed Architecture Using ABP, SignalR & RabbitMQ
• How to Use Attribute Directives to Avoid Repetition in Angular Templates

We’d love to hear from you. Please leave your comments, suggestions, feeedbacks below.

What's New with the ABP Framework 2.9?

You can see all the changes on the GitHub release notes. This post will only cover the important features/changes.

Pre-Compiling Razor Pages

Pre-built pages (for the application modules) and view components were compiling on runtime until this version. Now, they are pre-compiled and we've measured that the application startup time (especially for the MVC UI) has been reduced more than 50%. In other words, it is two-times faster than the previous version. The speed change also effects when you visit a page for the first time.

Here, a test result for the startup application template with v2.8 and v.2.9:

v2.8

2020-06-04 22:59:04.891 +08:00 [INF] Starting web host.
2020-06-04 22:59:07.662 +08:00 [INF] Now listening on: https://localhost:44391
2020-06-04 22:59:17.315 +08:00 [INF] Request finished in 7756.6218ms 200 text/html;

Total: 12.42s

v2.9

2020-06-04 22:59:13.720 +08:00 [INF] Starting web host.
2020-06-04 22:59:16.639 +08:00 [INF] Now listening on: https://localhost:44369
2020-06-04 22:59:18.957 +08:00 [INF] Request finished in 1780.5461ms 200 text/html;

Total: 5.24s

You do nothing to get the benefit of the new approach. Overriding UI pages/components are also just working as before. We will be working on more performance improvements in the v3.0.

Organization Unit System

The Identity Module now has the most requested feature: Organization Units!

Organization unit system is used to create a hierarchical organization tree in your application. You can then use this organization tree to authorize data and functionality in your application.

The documentation will come soon...

New Blob Storing Package

We've created a new Blob Storing package to store arbitrary binary objects. It is generally used to store the content of the files in your application. This package provides an abstraction, so any application or module can save and retrieve files independent from the actual storing provider.

There are two storage provider currently implemented:

• Volo.Abp.BlobStoring.FileSystem package stores objects/files in the local file system.
• Volo.Abp.BlobStoring.Database module stores objects/files in a database. It currently supports Entity Framework Core (so, you can use any relational DBMS) and MongoDB.

Azure BLOB provider will be available with v3.0. You can request other cloud providers or contribute yourself on the GitHub repository.

One of the benefits of the blob storing system is that it allows you to create multiple containers (each container is a blob storage) and use different storage providers for each container.

Example: Use the default container to save and get a byte array

public class MyService : ITransientDependency
{
    private readonly IBlobContainer _container;

    public MyService(IBlobContainer container)
    {
        _container = container;
    }

    public async Task FooAsync()
    {
        //Save a BLOB
        byte[] bytes = GetBytesFromSomeWhere();
        await _container.SaveAsync("my-unique-blob-name", bytes);
        
        //Retrieve a BLOB
        bytes = await _container.GetAllBytesAsync("my-unique-blob-name");
    }
}

It can work with byte[] and Stream objects.

Example: Use a typed (named) container to save and get a stream

public class MyService : ITransientDependency
{
    private readonly IBlobContainer<TestContainer> _container;

    public MyService(IBlobContainer<TestContainer> container)
    {
        _container = container;
    }

    public async Task FooAsync()
    {
        //Save a BLOB
        Stream stream = GetStreamFromSomeWhere();
        await _container.SaveAsync("my-unique-blob-name", stream);
        
        //Retrieve a BLOB
        stream = await _container.GetAsync("my-unique-blob-name");
    }
}

TestContainer is an empty class that has no purpose than identifying the container:

[BlobContainerName("test")] //specifies the name of the container
public class TestContainer
{

}

A typed (named) container can be configured to use a different storing provider than the default one. It is a good practice to always use a typed container while developing re-usable modules, so the final application can configure provider for this container without effecting the other containers.

Example: Configure the File System provider for the TestContainer

Configure<AbpBlobStoringOptions>(options =>
{
    options.Containers.Configure<TestContainer>(configuration =>
    {
        configuration.UseFileSystem(fileSystem =>
        {
            fileSystem.BasePath = "C:\\MyStorageFolder";
        });
    });
});

See the blob storing documentation for more information.

Oracle Integration Package for Entity Framework Core

We've created an integration package for Oracle, so you can easily switch to the Oracle for the EF Core. It is tested for the framework and pre-built modules.

See the documentation to start using the Oracle integration package.

Automatically Determining the Database Provider

When you develop a reusable application module with EF Core integration, you generally want to develop your module DBMS independent. However, there are minor (sometimes major) differences between different DBMSs. If you perform a custom mapping based on the DBMS, you can now use ModelBuilder.IsUsingXXX() extension methods:

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

    modelBuilder.Entity<Phone>(b =>
    {
        //...
        if (modelBuilder.IsUsingPostgreSql()) //Check if using PostgreSQL!
        {
            b.Property(x => x.Number).HasMaxLength(20);
        }
        else
        {
            b.Property(x => x.Number).HasMaxLength(32);
        }
    });
}

Beside the stupid example above, you can configure your mapping however you need!

ABP CLI: Translate Command

abp translate is a new command that simplifies to translate localization files when you have multiple JSON localization files in a source control repository.

The main purpose of this command is to translate the ABP Framework localization files (since the abp repository has tens of localization files to be translated in different folders).

It is appreciated if you use this command to translate the framework resources for your mother language.

See the documentation to learn how to use it. Also see the contribution guide.

The New Virtual File System Explorer Module

Thanks to @realLiangshiwei created and contributed a new module to explore files in the Virtual File System. It works for MVC UI and shows all the virtual files in the application. Example screenshots:

See the documentation to learn how to use it.

Sample Application: SignalR with Tiered Architecture

Implementing SignalR in a distributed/tiered architecture can be challenging. We've created a sample application that demonstrate how to implement it using the SignalR integration and the distributed event bus system easily.

See the source code of the sample solution.

An article is on the road that will deeply explain the solution. Follow the @abpframework Twitter account.

A picture from the article that shows the communication diagram of the solution

About gRPC

We've created a sample application to show how to create and consume gRPC endpoints in your ABP based applications.

See the source code on GitHub.

We were planning to create gRPC endpoints for all the pre-built application modules, but we see that ASP.NET Core gRPC integration is not mature enough and doesn't support some common deployment scenarios yet. So, deferring this to the next versions (see this comment for more). However, it is pretty standard if you want to use gRPC in your applications. ABP Framework has no issue with gRPC. Just check the sample application.

Others

• Time zone system to support different time zones for an application.
• Support for virtual path deployment on IIS.
• RTL support for the Angular UI.

See the GitHub release notes for others updates.

What's New with the ABP Commercial 2.9

In addition to all the features coming with the ABP Framework, the ABP Commercial has additional features with this release, as always. This section covers the ABP Commercial highlights in the version 2.9.

Organization Unit Management UI

We've created the UI for manage organization units, their members and roles for the ABP Commercial Identity Module:

OU management is available for both of the MVC (Razor Pages) and the Angular user interfaces.

See this entry if you're upgrading your solution from an earlier version.

Chat Module Angular UI

We had introduced a new chat module in the previous version, which was only supporting the ASP.NET Core MVC / Razor Pages UI. Now, it has also an Angular UI option.

A screenshot from the chat module - two users are sending messages to each other

Easy CRM Angular UI

Easy CRM is a sample application that is built on the ABP Commercial to provide a relatively complex application to the ABP Commercial customers. In the version 2.7, we have lunched it with MVC / Razor Pages UI. With the 2.9 version, we are releasing the Angular UI for the Easy CRM application.

A screenshot from the "Order Details" page of the Easy CRM application.

See the Easy CRM document to learn how to download and run it.

Module Code Generation for the ABP Suite

ABP Suite is a tool that's main feature is to generate code for complete CRUD functionality for an entity, from database to the UI layer.

A screenshot from the ABP Suite: Define the properties of a new entity and let it to create the application code for you!

It was working only for the application template until this release. Now, it supports to generate code for the module projects too. That's a great way to create reusable application modules by taking the power of the code generation.

In addition to this main feature, we added many minor enhancements on the ABP Suite in this release.

Notice: Generating code for the module template is currently in beta. Please inform us if you find any bug.

Lepton Theme

Lepton Theme is the commercial theme we've developed for the ABP Commercial;

• It is 100% bootstrap compatible - so you don't write theme specific HTML!
• Provides different kind of styles - you see the material style in the picture below.
• Provides different kind of layouts (side/top menu, fluid/boxed layout...).
• It is lightweight, responsive and modern.
• And... it is upgradeable with no cost! You just update a NuGet/NPM package to get the new features.

We've create its own web site: http://leptontheme.com/

You can view all the components together, independent from an application:

This web site is currently in a very early stage. We will be documenting and improving this web site to be a reference for your development and explore the features of the theme.

Coming Soon: The File management Module

Based on the new blob storing system (introduced above), we've started to build a file management module that is used to manage (navigate/upload/download) a hierarchical file system on your application and share the files between your users and with your customers.

We plan to release the initial version with the ABP Commercial v3.0 and continue to improve it with the subsequent releases.

About the Next Version: 3.0

We have added many new features with the v2.8 and v2.9. In the next version, we will completely focus on the documentation, performance improvements and and other enhancements as well as bug fixes.

For a long time, we were releasing a new feature version in every 2 weeks. We will continue to this approach after v3.0. But, as an exception to the v3.0, the development cycle will be ~4 weeks. The planned release date for the v3.0 is the July 1, 2020.

Bonus: Articles!

Beside developing our products, our team are constantly writing articles/tutorials on various topics. You may want to check the latest articles:

• ASP.NET Core 3.1 WebHook Implementation Using Pub/Sub
• Using Azure Key Vault with ASP.NET Core