From 81822b8ebe29bee8f8d09ce943a82134ba38958c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Mon, 25 Oct 2021 08:52:47 +0300 Subject: [PATCH 1/4] Revised the 5.0 migration guide --- docs/en/Migration-Guides/Abp-5-0-MVC.md | 7 ++++ docs/en/Migration-Guides/Abp-5_0.md | 56 +++++++++++++++++-------- 2 files changed, 46 insertions(+), 17 deletions(-) create mode 100644 docs/en/Migration-Guides/Abp-5-0-MVC.md diff --git a/docs/en/Migration-Guides/Abp-5-0-MVC.md b/docs/en/Migration-Guides/Abp-5-0-MVC.md new file mode 100644 index 0000000000..a1ca8ed7fd --- /dev/null +++ b/docs/en/Migration-Guides/Abp-5-0-MVC.md @@ -0,0 +1,7 @@ +# ABP MVC / Razor Pages UI v4.x to v5.0 Migration Guide + +This document is for the ABP MVC / Razor Pages UI. See also [the main migration guide](Abp-5_0.md). + +## Use install-libs by default + +Removed the Gulp dependency from the MVC / Razor Pages UI projects in favor of `abp install-libs` command ([see](https://docs.abp.io/en/abp/5.0/UI/AspNetCore/Client-Side-Package-Management#install-libs-command)) of the ABP CLI. You should run this command whenever you change/upgrade your client-side package dependencies via `package.json`. \ No newline at end of file diff --git a/docs/en/Migration-Guides/Abp-5_0.md b/docs/en/Migration-Guides/Abp-5_0.md index 2dc880be3b..a4f89f5039 100644 --- a/docs/en/Migration-Guides/Abp-5_0.md +++ b/docs/en/Migration-Guides/Abp-5_0.md @@ -1,6 +1,42 @@ # ABP Framework v4.x to v5.0 Migration Guide -## IdentityUser +This document is a guide for upgrading ABP 4.x solutions to ABP 5.0. Please read them all since 5.0 has some important breaking changes. + +## .NET 6.0 + +ABP 5.0 runs on .NET 6.0. So, please upgrade your solution to .NET 6.0 if you want to use ABP 5.0. You can see [Microsoft's migration guide](https://docs.microsoft.com/en-us/aspnet/core/migration/50-to-60). + +## Bootstrap 5 + +ABP 5.0 uses the Bootstrap 5 as the fundamental HTML/CSS framework. We've migrated all the UI themes, tag helpers, UI components and the pages of the pre-built application modules. You may need to update your own pages by following the [Bootstrap's migration guide](https://getbootstrap.com/docs/5.0/migration/). + +## ABP Framework + +This section contains breaking changes in the ABP Framework. + +### MongoDB + +ABP Framework will serialize the datetime based on [AbpClockOptions](https://docs.abp.io/en/abp/latest/Timing#clock-options) starting from ABP v5.0. It was saving `DateTime` values as UTC in MongoDB. Check out [MongoDB Datetime Serialization Options](https://mongodb.github.io/mongo-csharp-driver/2.13/reference/bson/mapping/#datetime-serialization-options). + +If you want to revert back this feature, set `UseAbpClockHandleDateTime = false` in `AbpMongoDbOptions`: + +```cs +services.Configure(x => x.UseAbpClockHandleDateTime = false); +``` + +### Removed Obsolete APIs + +* `IRepository` doesn't inherit from `IQueryable` anymore. It was [made obsolete in 4.2](https://docs.abp.io/en/abp/latest/Migration-Guides/Abp-4_2#irepository-getqueryableasync). + +## UI Providers + +* [Angular UI 4.x to 5.0 Migration Guide](Abp-5_0-Angular.md) + +## Modules + +This section contains breaking and important changes in the application modules. + +### Identity `IsActive ` property is added to the `IdentityUser`. This flag will be checked during the authentication of the users. See the related [PR](https://github.com/abpframework/abp/pull/10185). **After the migration, set this property to `true` for the existing users: `UPDATE AbpUsers SET IsActive=1`** @@ -31,21 +67,7 @@ public partial class AddIsActiveToIdentityUser : Migration ``` For document base databases like MongoDB, you need to manually update the `IsActive` field for the existing user records. - -## MongoDB - -ABP Framework will serialize the datetime based on [AbpClockOptions](https://docs.abp.io/en/abp/latest/Timing#clock-options) starting from ABP v5.0. It was saving `DateTime` values as UTC in MongoDB. Check out [MongoDB Datetime Serialization Options](https://mongodb.github.io/mongo-csharp-driver/2.13/reference/bson/mapping/#datetime-serialization-options). - -To revert back this feature, set `UseAbpClockHandleDateTime = false` in `AbpMongoDbOptions`: - -```cs -services.Configure(x => x.UseAbpClockHandleDateTime = false); -``` - -## IApiScopeRepository - -`GetByNameAsync` method renamed as `FindByNameAsync`. -## Angular UI +### IdentityServer -See the [Angular UI 5.0 Migration Guide](Abp-5_0-Angular.md). +`IApiScopeRepository.GetByNameAsync` method renamed as `FindByNameAsync`. From 767c69b904962ec225d31ced7c3d9d4cef24d2d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Mon, 25 Oct 2021 09:07:53 +0300 Subject: [PATCH 2/4] Enhance the 5.0 migration guide. --- docs/en/Migration-Guides/Abp-5-0-Blazor.md | 7 +++++++ docs/en/Migration-Guides/Abp-5_0.md | 19 ++++++++++++++----- 2 files changed, 21 insertions(+), 5 deletions(-) create mode 100644 docs/en/Migration-Guides/Abp-5-0-Blazor.md diff --git a/docs/en/Migration-Guides/Abp-5-0-Blazor.md b/docs/en/Migration-Guides/Abp-5-0-Blazor.md new file mode 100644 index 0000000000..c13314e86b --- /dev/null +++ b/docs/en/Migration-Guides/Abp-5-0-Blazor.md @@ -0,0 +1,7 @@ +# ABP Blazor UI v4.x to v5.0 Migration Guide + +This document is for the ABP MVC / Razor Pages UI. See also [the main migration guide](Abp-5_0.md). + +## Upgrading to the latest Blazorise + +ABP 5.0 uses the latest version of the [Blazorise](https://blazorise.com/) library. Please upgrade the Blazorise NuGet packages in your solution. \ No newline at end of file diff --git a/docs/en/Migration-Guides/Abp-5_0.md b/docs/en/Migration-Guides/Abp-5_0.md index a4f89f5039..fba49102c2 100644 --- a/docs/en/Migration-Guides/Abp-5_0.md +++ b/docs/en/Migration-Guides/Abp-5_0.md @@ -31,6 +31,8 @@ services.Configure(x => x.UseAbpClockHandleDateTime = false); ## UI Providers * [Angular UI 4.x to 5.0 Migration Guide](Abp-5_0-Angular.md) +* [ASP.NET Core MVC / Razor Pages UI 4.x to 5.0 Migration Guide]() +* [Blazor UI 4.x to 5.0 Migration Guide](Abp-5-0-Blazor.md) ## Modules @@ -38,11 +40,12 @@ This section contains breaking and important changes in the application modules. ### Identity -`IsActive ` property is added to the `IdentityUser`. This flag will be checked during the authentication of the users. See the related [PR](https://github.com/abpframework/abp/pull/10185). -**After the migration, set this property to `true` for the existing users: `UPDATE AbpUsers SET IsActive=1`** +An `IsActive` (`bool`) property is added to the `IdentityUser` entity. This flag will be checked during the authentication of the users. EF Core developers need to add a new database migration and update their databases. -For EFCore you can set `defaultValue` to `true` in the migration class: -(This will add the column with `true` value for the existing records.) +**After the database migration, set this property to `true` for the existing users: `UPDATE AbpUsers SET IsActive=1`**. Otherwise, none of the users can login to the application. + +Alternatively, you can set `defaultValue` to `true` in the migration class (after adding the migration). +This will add the column with `true` value for the existing records. ```cs public partial class AddIsActiveToIdentityUser : Migration @@ -66,8 +69,14 @@ public partial class AddIsActiveToIdentityUser : Migration } ``` -For document base databases like MongoDB, you need to manually update the `IsActive` field for the existing user records. +For MongoDB, you need to manually update the `IsActive` field for the existing users. ### IdentityServer `IApiScopeRepository.GetByNameAsync` method renamed as `FindByNameAsync`. + +## See Also + +* [Angular UI 4.x to 5.0 Migration Guide](Abp-5_0-Angular.md) +* [ASP.NET Core MVC / Razor Pages UI 4.x to 5.0 Migration Guide]() +* [Blazor UI 4.x to 5.0 Migration Guide](Abp-5-0-Blazor.md) From 94f5e8a615f579b6f21ae5e2335b0f52d3498b95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Mon, 25 Oct 2021 09:25:48 +0300 Subject: [PATCH 3/4] Added sections to the 5.0 migration guide. --- .../Blog-Posts/2021-10-05 v5_0_Beta1/POST.md | 1 + docs/en/Migration-Guides/Abp-5-0-Blazor.md | 2 +- docs/en/Migration-Guides/Abp-5-0-MVC.md | 9 +++++++-- docs/en/Migration-Guides/Abp-5_0-Angular.md | 18 +++++++++--------- docs/en/Migration-Guides/Abp-5_0.md | 18 ++++++++++++++++++ 5 files changed, 36 insertions(+), 12 deletions(-) diff --git a/docs/en/Blog-Posts/2021-10-05 v5_0_Beta1/POST.md b/docs/en/Blog-Posts/2021-10-05 v5_0_Beta1/POST.md index 2fe9f6bad9..6e83db5da2 100644 --- a/docs/en/Blog-Posts/2021-10-05 v5_0_Beta1/POST.md +++ b/docs/en/Blog-Posts/2021-10-05 v5_0_Beta1/POST.md @@ -51,6 +51,7 @@ This is a major version and there are some breaking changes and upgrade steps. H * `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 ABP CLI. +* Deprecated EntityCreatingEventData, EntityUpdatingEventData, EntityDeletingEventData and EntityChangingEventData classes. See [#9897](https://github.com/abpframework/abp/issues/9897). Please see the [migration document](https://docs.abp.io/en/abp/5.0/Migration-Guides/Abp-5_0) for all the details. You can also see all [the closed issues and pull request](https://github.com/abpframework/abp/releases/tag/5.0.0-beta.1) on GitHub. diff --git a/docs/en/Migration-Guides/Abp-5-0-Blazor.md b/docs/en/Migration-Guides/Abp-5-0-Blazor.md index c13314e86b..f0c69b679a 100644 --- a/docs/en/Migration-Guides/Abp-5-0-Blazor.md +++ b/docs/en/Migration-Guides/Abp-5-0-Blazor.md @@ -1,6 +1,6 @@ # ABP Blazor UI v4.x to v5.0 Migration Guide -This document is for the ABP MVC / Razor Pages UI. See also [the main migration guide](Abp-5_0.md). +> This document is for the ABP MVC / Razor Pages UI. See also [the main migration guide](Abp-5_0.md). ## Upgrading to the latest Blazorise diff --git a/docs/en/Migration-Guides/Abp-5-0-MVC.md b/docs/en/Migration-Guides/Abp-5-0-MVC.md index a1ca8ed7fd..f2c863c634 100644 --- a/docs/en/Migration-Guides/Abp-5-0-MVC.md +++ b/docs/en/Migration-Guides/Abp-5-0-MVC.md @@ -1,7 +1,12 @@ # ABP MVC / Razor Pages UI v4.x to v5.0 Migration Guide -This document is for the ABP MVC / Razor Pages UI. See also [the main migration guide](Abp-5_0.md). +> This document is for the ABP MVC / Razor Pages UI. See also [the main migration guide](Abp-5_0.md). ## Use install-libs by default -Removed the Gulp dependency from the MVC / Razor Pages UI projects in favor of `abp install-libs` command ([see](https://docs.abp.io/en/abp/5.0/UI/AspNetCore/Client-Side-Package-Management#install-libs-command)) of the ABP CLI. You should run this command whenever you change/upgrade your client-side package dependencies via `package.json`. \ No newline at end of file +Removed the Gulp dependency from the MVC / Razor Pages UI projects in favor of `abp install-libs` command ([see](https://docs.abp.io/en/abp/5.0/UI/AspNetCore/Client-Side-Package-Management#install-libs-command)) of the ABP CLI. You should run this command whenever you change/upgrade your client-side package dependencies via `package.json`. + +## Switched to SweetAlert2 + +Switched from SweetAlert to SweetAlert2. Run the `abp install-libs` command (in the root directory of the web project) after upgrading your solution. See [#9607](https://github.com/abpframework/abp/pull/9607). + diff --git a/docs/en/Migration-Guides/Abp-5_0-Angular.md b/docs/en/Migration-Guides/Abp-5_0-Angular.md index 1188e68556..8226ed5896 100644 --- a/docs/en/Migration-Guides/Abp-5_0-Angular.md +++ b/docs/en/Migration-Guides/Abp-5_0-Angular.md @@ -1,8 +1,8 @@ # Angular UI v4.x to v5.0 Migration Guide -## Breaking Changes +This document is for the ABP MVC / Razor Pages UI. See also [the main migration guide](Abp-5_0.md). -### Overall +## Overall See the overall list of breaking changes: @@ -16,15 +16,15 @@ See the overall list of breaking changes: - Update all dependency versions to the latest [#9806](https://github.com/abpframework/abp/issues/9806) - Chart.js big include with CommonJS warning [#7472](https://github.com/abpframework/abp/issues/7472) -### Angular v12 +## Angular v12 The new ABP Angular UI is based on Angular v12. We started to compile Angular UI packages with the Ivy compilation. Therefore, **new packages only work with Angular v12**. If you are still on the older version of Angular v12, you have to update to Angular v12. The update is usually very easy. See [Angular Update Guide](https://update.angular.io/?l=2&v=11.0-12.0) for further information. -### Bootstrap 5 +## Bootstrap 5 TODO -### NGXS has been removed +## NGXS has been removed We aim to make the ABP Framework free of any state-management solutions. ABP developers should be able to use the ABP Framework with any library/framework of their choice. So, we decided to remove NGXS from ABP packages. @@ -42,7 +42,7 @@ NGXS states and actions, some namespaces have been removed. See [this issue](htt If you don't want to use the NGXS, you should remove all NGXS related imports, injections, etc., from your project. -### @angular/localize package +## @angular/localize package [`@angular/localize`](https://angular.io/api/localize) dependency has been removed from `@abp/ng.core` package. The package must be installed in your app. Run the following command to install: @@ -56,7 +56,7 @@ yarn add @angular/localize > ABP Angular UI packages are not dependent on the `@angular/localize` package. However, some packages (like `@ng-bootstrap/ng-bootstrap`) depend on the package. Thus, this package needs to be installed in your project. -### Proxy endpoints +## Proxy endpoints New endpoints named proxy have been created, related proxies have moved. For example; before v5.0, `IdentityUserService` could be imported from `@abp/ng.identity`. As of v5.0, the service can be imported from `@abp/ng.identity/proxy`. See an example: @@ -79,11 +79,11 @@ Following proxies have been affected: - `@abp/ng.tenant-management` to `@abp/ng.tenant-management/proxy` - **ProfileService** is deleted from `@abp/ng.core`. Instead, you can import it from `@abp/ng.identity/proxy` -### SettingTabsService +## SettingTabsService **SettingTabsService** has moved from `@abp/ng.core` to `@abp/ng.setting-management/config`. -### ChartComponent +## ChartComponent [`ChartComponent`](../UI/Angular/Chart-Component.md) has moved from `@abp/ng.theme.shared` to `@abp/ng.components/chart.js`. To use the component, you need to import the `ChartModule` to your module as follows: diff --git a/docs/en/Migration-Guides/Abp-5_0.md b/docs/en/Migration-Guides/Abp-5_0.md index fba49102c2..5e7011d02c 100644 --- a/docs/en/Migration-Guides/Abp-5_0.md +++ b/docs/en/Migration-Guides/Abp-5_0.md @@ -24,6 +24,18 @@ If you want to revert back this feature, set `UseAbpClockHandleDateTime = false` services.Configure(x => x.UseAbpClockHandleDateTime = false); ``` +### Publishing Auto-Events in the Same Unit of Work + +Local and distributed auto-events are handled in the same unit of work now. That means the event handles are executed in the same database transaction and they can rollback the transaction if they throw any exception. See [#9896](https://github.com/abpframework/abp/issues/9896) for more. + +### Deprecated EntityCreatingEventData, EntityUpdatingEventData, EntityDeletingEventData and EntityChangingEventData + +`EntityCreatingEventData`, `EntityUpdatingEventData`, `EntityDeletingEventData` and `EntityChangingEventData` is not necessary now, because `EntityCreatedEventData`, `EntityUpdatedEventData`, `EntityDeletedEventData` and `EntityChangedEventData` is already taken into the current unit of work. Please switch to `EntityCreatedEventData`, `EntityUpdatedEventData`, `EntityDeletedEventData` and `EntityChangedEventData` if you've used the deprecated events. See [#9897](https://github.com/abpframework/abp/issues/9897) to learn more. + +### Removed ModelBuilderConfigurationOptions classes + +If you've used these classes, please remove their usages and use the static properties to customize the module's database mappings. See [#8887](https://github.com/abpframework/abp/issues/8887) for more. + ### Removed Obsolete APIs * `IRepository` doesn't inherit from `IQueryable` anymore. It was [made obsolete in 4.2](https://docs.abp.io/en/abp/latest/Migration-Guides/Abp-4_2#irepository-getqueryableasync). @@ -40,6 +52,8 @@ This section contains breaking and important changes in the application modules. ### Identity +#### User Active/Passive + An `IsActive` (`bool`) property is added to the `IdentityUser` entity. This flag will be checked during the authentication of the users. EF Core developers need to add a new database migration and update their databases. **After the database migration, set this property to `true` for the existing users: `UPDATE AbpUsers SET IsActive=1`**. Otherwise, none of the users can login to the application. @@ -71,6 +85,10 @@ public partial class AddIsActiveToIdentityUser : Migration For MongoDB, you need to manually update the `IsActive` field for the existing users. +#### Identity -> Account API Changes + +`IProfileAppService` (and the implementation and the related DTOs) are moved to the Account module from the Identity module (done with [this PR](https://github.com/abpframework/abp/pull/10370/files)). + ### IdentityServer `IApiScopeRepository.GetByNameAsync` method renamed as `FindByNameAsync`. From 0945e491750e863344ebcc804d3f31fcfc9fd81f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Mon, 25 Oct 2021 14:14:27 +0300 Subject: [PATCH 4/4] Update Abp-5_0.md --- docs/en/Migration-Guides/Abp-5_0.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/en/Migration-Guides/Abp-5_0.md b/docs/en/Migration-Guides/Abp-5_0.md index 5e7011d02c..27c3f03dfd 100644 --- a/docs/en/Migration-Guides/Abp-5_0.md +++ b/docs/en/Migration-Guides/Abp-5_0.md @@ -10,6 +10,10 @@ ABP 5.0 runs on .NET 6.0. So, please upgrade your solution to .NET 6.0 if you wa ABP 5.0 uses the Bootstrap 5 as the fundamental HTML/CSS framework. We've migrated all the UI themes, tag helpers, UI components and the pages of the pre-built application modules. You may need to update your own pages by following the [Bootstrap's migration guide](https://getbootstrap.com/docs/5.0/migration/). +The startup template changes + +The startup template has changed. You don't need to apply all the changes, but it is strongly suggested to follow [this guide](Upgrading-Startup-Template.md) and make the necessary changes for your solution. + ## ABP Framework This section contains breaking changes in the ABP Framework. @@ -18,19 +22,19 @@ This section contains breaking changes in the ABP Framework. ABP Framework will serialize the datetime based on [AbpClockOptions](https://docs.abp.io/en/abp/latest/Timing#clock-options) starting from ABP v5.0. It was saving `DateTime` values as UTC in MongoDB. Check out [MongoDB Datetime Serialization Options](https://mongodb.github.io/mongo-csharp-driver/2.13/reference/bson/mapping/#datetime-serialization-options). -If you want to revert back this feature, set `UseAbpClockHandleDateTime = false` in `AbpMongoDbOptions`: +If you want to revert back this feature, set `UseAbpClockHandleDateTime` to `false` in `AbpMongoDbOptions`: ```cs -services.Configure(x => x.UseAbpClockHandleDateTime = false); +Configure(x => x.UseAbpClockHandleDateTime = false); ``` ### Publishing Auto-Events in the Same Unit of Work -Local and distributed auto-events are handled in the same unit of work now. That means the event handles are executed in the same database transaction and they can rollback the transaction if they throw any exception. See [#9896](https://github.com/abpframework/abp/issues/9896) for more. +Local and distributed auto-events are handled in the same unit of work now. That means the event handles are executed in the same database transaction and they can rollback the transaction if they throw any exception. The new behavior may affect your previous assumptions. See [#9896](https://github.com/abpframework/abp/issues/9896) for more. -### Deprecated EntityCreatingEventData, EntityUpdatingEventData, EntityDeletingEventData and EntityChangingEventData +#### Deprecated EntityCreatingEventData, EntityUpdatingEventData, EntityDeletingEventData and EntityChangingEventData -`EntityCreatingEventData`, `EntityUpdatingEventData`, `EntityDeletingEventData` and `EntityChangingEventData` is not necessary now, because `EntityCreatedEventData`, `EntityUpdatedEventData`, `EntityDeletedEventData` and `EntityChangedEventData` is already taken into the current unit of work. Please switch to `EntityCreatedEventData`, `EntityUpdatedEventData`, `EntityDeletedEventData` and `EntityChangedEventData` if you've used the deprecated events. See [#9897](https://github.com/abpframework/abp/issues/9897) to learn more. +As a side effect of the previous change, `EntityCreatingEventData`, `EntityUpdatingEventData`, `EntityDeletingEventData` and `EntityChangingEventData` is not necessary now, because `EntityCreatedEventData`, `EntityUpdatedEventData`, `EntityDeletedEventData` and `EntityChangedEventData` is already taken into the current unit of work. Please switch to `EntityCreatedEventData`, `EntityUpdatedEventData`, `EntityDeletedEventData` and `EntityChangedEventData` if you've used the deprecated events. See [#9897](https://github.com/abpframework/abp/issues/9897) to learn more. ### Removed ModelBuilderConfigurationOptions classes @@ -40,6 +44,12 @@ If you've used these classes, please remove their usages and use the static prop * `IRepository` doesn't inherit from `IQueryable` anymore. It was [made obsolete in 4.2](https://docs.abp.io/en/abp/latest/Migration-Guides/Abp-4_2#irepository-getqueryableasync). +### Other Breaking Changes + +* [#9549](https://github.com/abpframework/abp/pull/9549) `IObjectValidator` methods have been changed to asynchronous. +* [#9940](https://github.com/abpframework/abp/pull/9940) Use ASP NET Core's authentication scheme to handle `AbpAuthorizationException`. +* [#9180](https://github.com/abpframework/abp/pull/9180) Use `IRemoteContentStream` without form content headers. + ## UI Providers * [Angular UI 4.x to 5.0 Migration Guide](Abp-5_0-Angular.md) @@ -71,7 +81,7 @@ public partial class AddIsActiveToIdentityUser : Migration table: "AbpUsers", type: "bit", nullable: false, - defaultValue: true); // Default is false. + defaultValue: true); // Default is false, change it to true. } protected override void Down(MigrationBuilder migrationBuilder) @@ -83,7 +93,7 @@ public partial class AddIsActiveToIdentityUser : Migration } ``` -For MongoDB, you need to manually update the `IsActive` field for the existing users. +For MongoDB, you need to update the `IsActive` field for the existing users in the database. #### Identity -> Account API Changes