tsai
/
abp
mirror of https://github.com/abpframework/abp.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Merge pull request #20422 from abpframework/cli-upgrade-doc 

Change `Migrating from Open Source Templates` document
pull/20447/head
Berkan Sasmaz 2 years ago
committed by GitHub
parent
7203014e4c 2a65469b93
commit
9fb13efbaa
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
4 changed files with 42 additions and 466 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      docs/en/cli/index.md
  2. 506
      docs/en/guides/migrating-from-open-source.md
  3. BIN
      docs/en/images/studio-upgrade-to-pro.png
  4. 1
      docs/en/studio/solution-explorer.md

1
docs/en/cli/index.md
View File

@ -782,6 +782,7 @@ abp switch-to-local --paths "D:\Github\abp|D:\Github\my-repo"
### upgrade
Upgrades the ABP modules to pro modules, such as upgrading [Identity](../modules/identity.md) to [Identity Pro](../modules/identity-pro.md). You can use this for [Single Layer Web Application](../solution-templates/single-layer-web-application/index.md) and [Layered Web Application](../solution-templates/layered-web-application/index.md) templates.
This command is specially designed for users who already started their development before having a license. Therefore this command requires license.
Usage:

506
docs/en/guides/migrating-from-open-source.md
View File

@ -1,483 +1,57 @@
# Migrating from Open Source Templates
````json
//[doc-params]
{
"DB": ["EF", "Mongo"]
}
````
ABP Studio provides a way for users, who already started the development before purchasing a license, to auto-upgrade their solutions with Pro modules. You can use this functionality through ABP Studio UI or ABP Studio CLI:
This guide provides you a step-by-step guidance to migrating your existing application (that uses the ABP) to ABP. Since ABP uses the main structure of the ABP and is built on top of that, this process is pretty straightforward, you can apply the steps mentioned in each step and easily migrate your project to ABP.
* A new button labeled `Upgrade to Pro` will be visible if you have a license but the current solution is created with open-source (free) license.
> After following this documentation, you should be able to migrate your project to ABP. However, if you have any problems or cannot migrate your project, we are providing paid consultancy, which you can find details at [https://abp.io/additional-services](https://abp.io/additional-services). On this page, you can find related pieces of information about our trainings, custom project development, and porting existing projects services, and you can fill-out the contact form, so we can reach out to you.
![upgrade-to-pro](../images/studio-upgrade-to-pro.png)
## ABP Migration Steps
* Alternatively, you can use the following ABP Studio CLI command to achieve the same functionality:
In this guide, we assume that you have a middle-complex ABP based solution and want to migrate to ABP. Throughout this documentation, `Acme.BookStore` application will be used as a reference solution (example application that is described in ABP's tutorial documents){{if DB == "EF"}}, which you can find at [https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore){{end}} but all of these steps are applicable for your own applications, only some of them can be changed according to your project choose and structure. However, the migration flow is the same.
```bash
abp upgrade [-t <template-name>]
Examples:
abp upgrade -t app
abp upgrade -t app-nolayers
```
There are 4 main steps to migrating from ABP to ABP, and each one of them is explained in the following sections, step-by-step and project-based:
## Changes in the solution
### 1. License Transition
### Module changes
The first step is to obtain the necessary license for ABP to be able to get the benefit of the pro modules and unlock the additional features. To do that, you should first get your `ApiKey` from the [organization's detail page](https://abp.io/my-organizations).
This command will remove the following modules from your solution:
You can update the **NuGet.Config** file in the root directory of your solution and add the *packageSource* as follows (don't forget to replace `<api-key>` placeholder):
- Volo.Abp.Account
- Volo.Abp.Identity
- Volo.Abp.TenantManagement
- Volo.Abp.LeptonXLiteTheme
```diff
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+ <add key="ABP NuGet Source" value="https://nuget.abp.io/<api-key>/v3/index.json" />
</packageSources>
</configuration>
```
And install the following modules to your solution:
After that, you can obtain an `AbpLicenseCode` by creating a startup template and copying the code from the `appsettings.secrets.json` file. Then, you can open the `appsettings.secrets.json` files under the `*.DbMigrator` and `*.Domain` projects and add your `AbpLicenseCode`:
- Volo.Abp.Account.Pro
- Volo.Abp.AuditLogging.Pro
- Volo.Abp.Identity.Pro
- Volo.Abp.OpenIddict.Pro
- Volo.Saas
- Volo.Abp.LanguageManagement
- Volo.Abp.TextTemplateManagement
- Volo.FileManagement
- Volo.Chat
- Volo.Abp.Gdpr
- Volo.Abp.LeptonXTheme
```json
{
//...
"AbpLicenseCode": "<AbpLicenseCode>"
}
### Other changes
```
The command will also do the following changes in your solution:
> `ApiKey` is needed to be able to use ABP's NuGet packages and `AbpLicenseCode` is needed for license checks per module.
- It will add `nuget.abp.io` NuGet source to `NuGet.config` file.
- It will create or update `appsettings.secrets.json` files to place the license key needed for Pro module usage.
- It will update the database. (And it will create a new migration if the solution uses EntityFramework Core)
- It will run `install-libs` command at the end.
### 2. Installing the ABP Modules
## Things to pay attention before using
After, you have added the `ApiKey` and `AbpLicenseCode` to the relevant places, now you can add [ABP's modules](../modules) to your solution. ABP provides plenty of modules that extend the ABP modules, such as the `Account Pro` module over the `Account` module or the `Identity Pro` module over the `Identity` module.
To replace these modules and also add the additional modules provided by ABP, you can use the `abp add-module` command (and then remove the free modules as described in the next section). This command finds all packages of the specified module, finds the related projects in the solution, and adds each package to the corresponding project in the solution. Therefore, by using this command, you don't need to manually add the package references to the `*.csproj` files and add related `[DependsOn(typeof(<>))]` statements to the module classes, instead, this command does this on behalf of you.
You can run the following commands one after another in your solution directory and add all the related modules into your solution as you would have started with [one of the startup templates of ABP](../solution-templates):
1. `abp add-module Volo.Identity.Pro --skip-db-migrations` → [Identity Module](../modules/identity.md)
2. `abp add-module Volo.OpenIddict.Pro --skip-db-migrations` → [OpenIddict Module](../modules/openiddict.md)
3. `abp add-module Volo.Saas --skip-db-migrations` → [SaaS Module](../modules/saas.md)
4. `abp add-module Volo.AuditLogging.Ui --skip-db-migrations` → [Audit Logging UI Module](../modules/audit-logging.md)
5. `abp add-module Volo.Account.Pro --skip-db-migrations` → [Account Module](../modules/account.md)
6. `abp add-module Volo.TextTemplateManagement --skip-db-migrations` → [Text Template Management Module](../modules/text-template-management.md)
7. `abp add-module Volo.LanguageManagement --skip-db-migrations` → [Language Management Module](../modules/language-management.md)
8. `abp add-module Volo.Gdpr --skip-db-migrations` → [GDPR Module](../modules/gdpr.md)
9. `abp add-module Volo.Abp.BlobStoring.Database --skip-db-migrations` → [Blob Storing - Database Provider](../framework/infrastructure/blob-storing/database.md)
> These 9 modules are pre-installed on the [startup templates of ABP](../solution-templates). Therefore, you can install all of them if you want to align your project with the startup templates, but it's totally optional, so you can skip running the command above for a module that you don't want to add to your solution.
After running the commands above, all of the related commercial packages and their dependencies will be added to your solution. In addition to these module packages, you can add `Volo.Abp.Commercial.SuiteTemplates` package into your domain application to be able to use ABP Suite later on. By doing that you will be able to add your solution from [ABP Suite UI](../suite) and generate CRUD pages for your applications whenever you want.
So, open your `*Domain.csproj` file and add the line below (don't forget to replace the `<Version>` placeholder):
```xml
<PackageReference Include="Volo.Abp.Commercial.SuiteTemplates" Version="<Version>" />
```
Then, for the final step, you need to add the related `DependsOn` statement to the `*DomainModule.cs` file as follows:
```cs
using Volo.Abp.Commercial.SuiteTemplates;
// ...
[DependsOn(typeof(VoloAbpCommercialSuiteTemplatesModule))]
public class BookStoreDomainModule : AbpModule
{
//omited for code abbreviation...
}
```
### 3. Removing the ABP Module References & Updating Configurations
After the license transition and installing the ABP Modules, now you can remove the unnecessary free modules. For example, now you don't need the `Identity` module in your solution, because you have added the `Identity PRO` module in the previous section and it already has dependency on the free module and extends it.
You should remove various dependencies and references in different projects in your solution. All of the required changes are listed below in different sections, please apply the following steps to remove the unnecessary ABP Modules:
#### 3.1 - Domain.Shared Project
Remove the unnecessary references from the `*Domain.Shared.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Identity.Domain.Shared" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.Domain.Shared" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.OpenIddict.Domain.Shared" Version="8.0.4" />
```
Remove the unnecessary namespaces, and **DependsOn** statements from `*DomainSharedModule.cs`:
```diff
- using Volo.Abp.TenantManagement;
- typeof(AbpIdentityDomainSharedModule),
- typeof(AbpOpenIddictDomainSharedModule),
- typeof(AbpTenantManagementDomainSharedModule)
```
#### 3.2 - Domain Project
Remove the unnecessary references from the `*Domain.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Identity.Domain" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.Domain" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.OpenIddict.Domain" Version="8.0.4" />
```
Remove the unnecessary namespaces, and **DependsOn** statements from `*DomainModule.cs`:
```diff
- using Volo.Abp.TenantManagement;
- typeof(AbpIdentityDomainModule),
- typeof(AbpOpenIddictDomainModule),
- typeof(AbpTenantManagementDomainModule),
```
After removing the unnecessary references, we should update the namespaces in the `BookStoreDbMigrationService` class under the **Data** folder:
```diff
- using Volo.Abp.TenantManagement;
+ using Volo.Saas.Tenants;
```
{{ if DB == "EF" }}
#### 3.3 - EntityFrameworkCore Project
Remove the unnecessary references from the `*EntityFrameworkCore.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Identity.EntityFrameworkCore" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.EntityFrameworkCore" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.OpenIddict.EntityFrameworkCore" Version="8.0.4" />
```
Remove the unnecessary namespaces from `*EntityFrameworkCoreModule.cs`:
```diff
- using Volo.Abp.TenantManagement.EntityFrameworkCore;
- typeof(AbpIdentityEntityFrameworkCoreModule),
- typeof(AbpOpenIddictEntityFrameworkCoreModule),
- typeof(AbpTenantManagementEntityFrameworkCoreModule)
```
Then, update the`*DbContext.cs` and make the related configurations:
```diff
- using Volo.Abp.TenantManagement;
- using Volo.Abp.TenantManagement.EntityFrameworkCore;
+ using Volo.Saas.Editions;
+ using Volo.Saas.EntityFrameworkCore;
+ using Volo.Saas.Tenants;
+ using Volo.Abp.LanguageManagement.EntityFrameworkCore;
[ReplaceDbContext(typeof(IIdentityDbContext))]
- [ReplaceDbContext(typeof(ITenantManagementDbContext))]
+ [ReplaceDbContext(typeof(ISaasDbContext))]
[ConnectionStringName("Default")]
public class BookStoreDbContext :
AbpDbContext<BookStoreDbContext>,
IIdentityDbContext,
- ITenantManagementDbContext
+ ISaasDbContext
{
//...
- // Tenant Management
- public DbSet<Tenant> Tenants { get; set; }
- public DbSet<TenantConnectionString> TenantConnectionStrings { get; set; }
+ // SaaS
+ public DbSet<Tenant> Tenants { get; set; }
+ public DbSet<Edition> Editions { get; set; }
+ public DbSet<TenantConnectionString> TenantConnectionStrings { get; set; }
//...
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
//...
- builder.ConfigureIdentity();
+ builder.ConfigureIdentityPro();
- builder.ConfigureOpenIddict();
+ builder.ConfigureOpenIddictPro();
- builder.ConfigureTenantManagement();
+ builder.ConfigureSaas();
+ builder.ConfigureLanguageManagement();
}
}
```
{{ else }}
#### 3.3 - MongoDB Project
Remove the unnecessary references from the `*MongoDb.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Identity.MongoDb" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.MongoDb" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.OpenIddict.MongoDb" Version="8.0.4" />
```
Remove the unnecessary namespaces from `*MongoDbModule.cs`:
```diff
- using Volo.Abp.TenantManagement.MongoDb;
- typeof(AbpIdentityMongoDbModule),
- typeof(AbpOpenIddictMongoDbModule),
- typeof(AbpTenantManagementMongoDbModule)
```
{{ end }}
#### 3.4 - Application.Contracts Project
Remove the unnecessary references from the `*Application.Contracts.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Account.Application.Contracts" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.Identity.Application.Contracts" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.Application.Contracts" Version="8.0.4" />
```
Remove the unnecessary namespaces, and **DependsOn** statements from `*ApplicationContractsModule.cs`:
```diff
- using Volo.Abp.TenantManagement;
- typeof(AbpAccountApplicationContractsModule),
- typeof(AbpTenantManagementApplicationContractsModule),
```
#### 3.5 - Application Project
Remove the unnecessary references from the `*Application.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Account.Application" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.Identity.Application" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.Application" Version="8.0.4" />
```
Remove the unnecessary namespaces, and **DependsOn** statements from `*ApplicationModule.cs`:
```diff
- using Volo.Abp.TenantManagement;
- typeof(AbpAccountApplicationModule),
- typeof(AbpTenantManagementApplicationModule),
```
#### 3.6 - HttpApi Project
Remove the unnecessary references from the `*HttpApi.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Account.HttpApi" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.Identity.HttpApi" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.HttpApi" Version="8.0.4" />
```
Remove the unnecessary namespaces, and **DependsOn** statements from `*HttpApiModule.cs`:
```diff
- using Volo.Abp.TenantManagement;
- typeof(AbpAccountHttpApiModule),
- typeof(AbpTenantManagementHttpApiModule),
```
#### 3.7 - HttpApi.Client Project
Remove the unnecessary references from the `*HttpApi.Client.csproj`:
```diff
- <PackageReference Include="Volo.Abp.Account.HttpApi.Client" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.Identity.HttpApi.Client" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.HttpApi.Client" Version="8.0.4" />
```
Remove the unnecessary namespaces, and **DependsOn** statements from `*HttpApiClientModule.cs`:
```diff
- using Volo.Abp.TenantManagement;
- typeof(AbpAccountHttpApiClientModule),
- typeof(AbpTenantManagementHttpApiClientModule),
```
#### 3.8 - Web Project
Remove the unnecessary references from the `*Web.csproj`:
```diff
- <PackageReference Include="Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonXLite" Version="3.0.*-*" />
+ <PackageReference Include="Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonX" Version="3.0.*-*" />
- <PackageReference Include="Volo.Abp.Identity.Web" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.TenantManagement.Web" Version="8.0.4" />
- <PackageReference Include="Volo.Abp.Account.Web.OpenIddict" Version="8.0.4" />
+ <PackageReference Include="Volo.Abp.Account.Pro.Public.Web.OpenIddict" Version="8.0.4" />
```
> Notice, that you have also changed the LeptonXLite theme reference with the [LeptonX Theme](../ui-themes/lepton-x), which is a commercial theme provided by ABP and has superior features to the LeptonX Lite theme.
Update namespaces for the `*WebModule.cs`:
```diff
- using Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonXLite;
- using Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonXLite.Bundling;
+ using Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonX;
+ using Volo.Abp.AspNetCore.Mvc.UI.Theme.LeptonX.Bundling;
- using Volo.Abp.TenantManagement.Web;
+ using Volo.Abp.Gdpr.Web.Extensions;
+ using Volo.Abp.LeptonX.Shared;
+ using Volo.Abp.PermissionManagement;
```
Then, we can update the configurations and add missing middlewares to the request pipeline in the same file, as follows:
```diff
- typeof(AbpAccountWebOpenIddictModule),
+ typeof(AbpAccountPublicWebOpenIddictModule),
- typeof(AbpTenantManagementWebModule),
- typeof(AbpAspNetCoreMvcUiLeptonXLiteThemeModule),
+ typeof(AbpAspNetCoreMvcUiLeptonXThemeModule),
public override void ConfigureServices(ServiceConfigurationContext context)
{
//other configurations...
+ context.Services.AddAbpCookieConsent(options =>
+ {
+ options.IsEnabled = true;
+ options.CookiePolicyUrl = "/CookiePolicy";
+ options.PrivacyPolicyUrl = "/PrivacyPolicy";
+ });
+ Configure<LeptonXThemeOptions>(options =>
+ {
+ options.DefaultStyle = LeptonXStyleNames.System;
+ });
+ Configure<LeptonXThemeMvcOptions>(options =>
+ {
+ options.ApplicationLayout = LeptonXMvcLayouts.SideMenu;
+ });
+ Configure<PermissionManagementOptions>(options =>
+ {
+ options.IsDynamicPermissionStoreEnabled = true;
+ });
}
//...
Configure<AbpBundlingOptions>(options =>
{
options.StyleBundles.Configure(
- LeptonXLiteThemeBundles.Styles.Global,
+ LeptonXThemeBundles.Styles.Global,
bundle =>
{
bundle.AddFiles("/global-styles.css");
}
);
});
public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
var app = context.GetApplicationBuilder();
var env = context.GetEnvironment();
//...
+ app.UseAbpCookieConsent();
app.UseCorrelationId();
+ app.UseAbpSecurityHeaders();
app.UseStaticFiles();
//...
}
```
> **Note:** In the startup templates of ABP, besides these configurations, there are some additional configurations, such as [configuring impersonation](../modules/account/impersonation.md), [configuring external providers](https://docs.abp.io/en/abp/latest/Modules/Account#configure-the-provider), and configuring health checks. These configurations are optional, and for the sake of simplicity, in this documentation, we did not mention them. You can apply the related configurations by checking the related documentation and from the default startup templates.
Update the namespaces in the `BookStoreMenuContributor` file as follows:
```diff
- using Volo.Abp.TenantManagement.Web.Navigation;
+ using Volo.Abp.TextTemplateManagement.Web.Navigation;
+ using Volo.Abp.AuditLogging.Web.Navigation;
+ using Volo.Abp.LanguageManagement.Navigation;
+ using Volo.Abp.OpenIddict.Pro.Web.Menus;
```
Then, we can update the `ConfigureMainMenuAsync` method in this file to specify the order of the menu items:
```csharp
private Task ConfigureMainMenuAsync(MenuConfigurationContext context)
{
//other configurations for menu items...
//Administration
var administration = context.Menu.GetAdministration();
administration.Order = 5;
//Administration->Identity
administration.SetSubItemOrder(IdentityMenuNames.GroupName, 1);
//Administration->OpenIddict
administration.SetSubItemOrder(OpenIddictProMenus.GroupName, 2);
//Administration->Language Management
administration.SetSubItemOrder(LanguageManagementMenuNames.GroupName, 3);
//Administration->Text Template Management
administration.SetSubItemOrder(TextTemplateManagementMainMenuNames.GroupName, 4);
//Administration->Audit Logs
administration.SetSubItemOrder(AbpAuditLoggingMainMenuNames.GroupName, 5);
//Administration->Settings
administration.SetSubItemOrder(SettingManagementMenuNames.GroupName, 6);
return Task.CompletedTask;
}
```
Replace LeptonX Lite npm package with LeptonX package in `package.json` file:
```diff
- "@abp/aspnetcore.mvc.ui.theme.leptonxlite": "~3.0.3",
+ "@volo/abp.aspnetcore.mvc.ui.theme.leptonx": "~3.0.3",
```
### 4. Creating Migrations & Running Application
That's it, you have applied the all related steps to migrate your application from ABP to ABP. Now, you can create a new migration, apply it to your database, and run your application!
To create a new migration, open a terminal in your {{ if DB == "EF" }}`*.EntityFrameworkCore`{{else}}`*.MongoDb`{{end}} project directory, and run the following command:
```bash
dotnet ef migrations add Migrated_To_ABP_Commercial
```
Then, to apply the database into your database and seed the initial data, you can run the `*.DbMigrator` project. After it's completed, you can run the `*.Web` project to see your application as working.
> **Note:** If you have an existing database, then creating a new migration and applying it to the database may not happen correctly. At that point, if it's possible you can drop the existing database and create a new one, or you can have a backup of your existing db, and after applying the new migration, you can synchronize the database with the backup.
## Consultancy
If you find the migration process challenging or prefer professional assistance, we offer a [paid consultancy service](https://abp.io/additional-services). Our experienced consultants can help ensure a smooth transition to ABP, addressing any specific needs or challenges your project may encounter. For detailed guidance and support, feel free to [reach out](https://abp.io/contact).
- The command covers the most common scenarios, but there is still a possibility that it can mess up something in your solution. Therefore, we strongly recommend a version control system (like [Git](https://git-scm.com)) to track what is changed in your solution and revert if needed.
- The command will not remove your custom codes that may be related with the removed modules listed above. So there may be build errors if you referenced one of those modules. You can clear them manually.

BIN
docs/en/images/studio-upgrade-to-pro.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

1
docs/en/studio/solution-explorer.md
View File

@ -117,6 +117,7 @@ A [module](./concepts.md#module) is a sub-solution that can contains zero, one o
- `JetBrains Rider`: Opens the module in JetBrains Rider. This option is only available if you have JetBrains Rider installed.
- `Terminal`: Opens the terminal in the module directory.
- `Explorer`: Opens the file explorer in the module directory.
- `Upgrade to Pro`: This will be visible only when you purchased a license but still using the modules came with open-source (free) license. For more details, check out [Migrating from Open Source Templates](../guides/migrating-from-open-source.md) document. This is not shown in the screenshot above.
### Adding a New Empty Module

Write Preview
Loading…
Cancel
Save