From 368eb9c565543934ab4d23b706b59a1f7e8556c1 Mon Sep 17 00:00:00 2001 From: maliming Date: Thu, 25 Jan 2024 13:53:30 +0800 Subject: [PATCH 1/3] Migration notes for NormalizedName property of Tenant. Resolve #18857 --- docs/en/Migration-Guides/Abp-8_1.md | 86 +++++++++++++++++++++++++++++ docs/en/Multi-Tenancy.md | 2 +- 2 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 docs/en/Migration-Guides/Abp-8_1.md diff --git a/docs/en/Migration-Guides/Abp-8_1.md b/docs/en/Migration-Guides/Abp-8_1.md new file mode 100644 index 0000000000..d5ec87a3ca --- /dev/null +++ b/docs/en/Migration-Guides/Abp-8_1.md @@ -0,0 +1,86 @@ +# ABP Version 8.1 Migration Guide + +This document is a guide for upgrading ABP v8.0 solutions to ABP v8.1. There are some changes in this version that may affect your applications, please read it carefully and apply the necessary changes to your application. + +## 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 defined in the `appsettings.json` file, you should add the `NormalizedName` property to your tenants. + +````json +"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: + +> This script is for the SQL Server database. You can change it for your database. + +> The table name `SaasTenants` is used for ABP commercial Saas module. `AbpTenants` is for the ABP open-source Tenant Management module. + +```sql +UPDATE SaasTenants SET NormalizedName = UPPER(Name) WHERE NormalizedName IS NULL OR NormalizedName = '' +``` + +```csharp +/// +public partial class Add_NormalizedName : Migration +{ + /// + protected override void Up(MigrationBuilder migrationBuilder) + { + migrationBuilder.AddColumn( + name: "NormalizedName", + table: "SaasTenants", + type: "citext", + maxLength: 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"); + } + + /// + 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. + diff --git a/docs/en/Multi-Tenancy.md b/docs/en/Multi-Tenancy.md index 392bea6809..698879bdf1 100644 --- a/docs/en/Multi-Tenancy.md +++ b/docs/en/Multi-Tenancy.md @@ -394,7 +394,7 @@ app.UseMultiTenancy(); `ITenantStore` is used to get the tenant configuration from a data source. -> Tenant names are not case-sensitive. `ITenantStore` will use the `NormalizedName` parameter to get tenants, You need to use `ITenantNormalizer to normalize tenant names. +> Tenant names are not case-sensitive. `ITenantStore` will use the `NormalizedName` parameter to get tenants, You need to use `ITenantNormalizer`` to normalize tenant names. #### Tenant Management Module From 1fe4a25b9cf73921b84305f8d258126f9db09436 Mon Sep 17 00:00:00 2001 From: maliming Date: Thu, 25 Jan 2024 13:55:42 +0800 Subject: [PATCH 2/3] Update Multi-Tenancy.md --- docs/en/Multi-Tenancy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/Multi-Tenancy.md b/docs/en/Multi-Tenancy.md index 698879bdf1..922976767d 100644 --- a/docs/en/Multi-Tenancy.md +++ b/docs/en/Multi-Tenancy.md @@ -394,7 +394,7 @@ app.UseMultiTenancy(); `ITenantStore` is used to get the tenant configuration from a data source. -> Tenant names are not case-sensitive. `ITenantStore` will use the `NormalizedName` parameter to get tenants, You need to use `ITenantNormalizer`` to normalize tenant names. +> Tenant names are not case-sensitive. `ITenantStore` will use the `NormalizedName` parameter to get tenants, You need to use `ITenantNormalizer` to normalize tenant names. #### Tenant Management Module From 1bffcc7220b99eb9346fc4f88ca70722168e970d Mon Sep 17 00:00:00 2001 From: maliming Date: Thu, 25 Jan 2024 14:05:36 +0800 Subject: [PATCH 3/3] Update Abp-8_1.md --- docs/en/Migration-Guides/Abp-8_1.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/en/Migration-Guides/Abp-8_1.md b/docs/en/Migration-Guides/Abp-8_1.md index d5ec87a3ca..6f4c316d3f 100644 --- a/docs/en/Migration-Guides/Abp-8_1.md +++ b/docs/en/Migration-Guides/Abp-8_1.md @@ -55,8 +55,7 @@ public partial class Add_NormalizedName : Migration migrationBuilder.AddColumn( name: "NormalizedName", table: "SaasTenants", - type: "citext", - maxLength: 64, + type: "nvarchar(64)", nullable: false, defaultValue: "");