ABP Commercial Version 8.1 Migration Guide

This document is a guide for upgrading ABP Commercial v8.x solutions to ABP Commercial v8.1. Please read them all carefully since v8.1 has some changes that you should take care of.

See the ABP Framework migration guide for the changes made in the ABP Framework.

Added NormalizedName property to Tenant

The Tenant entity has a new property called NormalizedName. It is used to find/cache a tenant by its name in a case-insensitive way.

This property is automatically set when a tenant is created or updated. It gets the normalized name of the tenant name by UpperInvariantTenantNormalizer(ITenantNormalizer) service. You can implement this service to change the normalization logic.

ITenantStore

The ITenantStore will use the NormalizedName parameter to get tenants, Please use the ITenantNormalizer to normalize the tenant name before calling the ITenantStore methods.

Update NormalizedName in appsettings.json

If your tenants are defined in the appsettings.json file, you should add the NormalizedName property to your tenants.

"Tenants": [
    {
      "Id": "446a5211-3d72-4339-9adc-845151f8ada0",
      "Name": "tenant1",
      "NormalizedName": "TENANT1" // <-- Add this property
    },
    {
      "Id": "25388015-ef1c-4355-9c18-f6b6ddbaf89d",
      "Name": "tenant2",
      "NormalizedName": "TENANT2", // <-- Add this property
      "ConnectionStrings": {
        "Default": "...tenant2's db connection string here..."
      }
    }
  ]

Update NormalizedName in the database

Please add a SQL script to your migration to set the NormalizedName property of the existing tenants. You can use the following script:

UPDATE SaasTenants SET NormalizedName = UPPER(Name) WHERE NormalizedName IS NULL OR NormalizedName = ''

This script is for the SQL Server database. You can update the SQL query for your database.

The table name SaasTenants is used for the ABP Commercial's Saas Module. AbpTenants is for the open-source ABP Framework's Tenant Management module.

/// <inheritdoc />
public partial class Add_NormalizedName : Migration
{
    /// <inheritdoc />
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.AddColumn<string>(
            name: "NormalizedName",
            table: "SaasTenants",
            type: "nvarchar(64)",
            nullable: false,
            defaultValue: "");

        migrationBuilder.Sql("UPDATE SaasTenants SET NormalizedName = UPPER(Name) WHERE NormalizedName IS NULL OR NormalizedName = ''");

        migrationBuilder.CreateIndex(
            name: "IX_SaasTenants_NormalizedName",
            table: "SaasTenants",
            column: "NormalizedName");
    }

    /// <inheritdoc />
    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropIndex(
            name: "IX_SaasTenants_NormalizedName",
            table: "SaasTenants");

        migrationBuilder.DropColumn(
            name: "NormalizedName",
            table: "SaasTenants");
    }
}

See https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/managing?tabs=dotnet-core-cli#adding-raw-sql to learn how to add raw SQL to migrations.

Use Asp.Versioning.Mvc to replace Microsoft.AspNetCore.Mvc.Versioning

The Microsoft.AspNetCore.Mvc.Versioning packages are now deprecated and superseded by Asp.Versioning.Mvc. See the announcement here: https://github.com/dotnet/aspnet-api-versioning/discussions/807

The namespace of the [ControllerName] attribute has changed to using Asp.Versioning. Please update your code to use the new namespace.

Related PR: https://github.com/abpframework/abp/pull/18380

New asynchronous methods for the IAppUrlProvider

The IsRedirectAllowedUrl method of IAppUrlProvider has been changed to IsRedirectAllowedUrlAsync and it is now an async method.

You should update your usage of IAppUrlProvider to use the new method.

Related PR: https://github.com/abpframework/abp/pull/18492