mirror of https://github.com/abpframework/abp.git
maliming
5 years ago
2241 changed files with 44130 additions and 54459 deletions
@ -0,0 +1,4 @@ |
|||||
|
codecov: |
||||
|
branch: dev |
||||
|
require_ci_to_pass: yes |
||||
|
allow_coverage_offsets: true |
||||
@ -0,0 +1,99 @@ |
|||||
|
# Hangfire Background Worker Manager |
||||
|
|
||||
|
[Hangfire](https://https://www.hangfire.io/) is an advanced background jobs and worker manager. You can integrate Hangfire with the ABP Framework to use it instead of the [default background worker manager](Background-Workers.md). |
||||
|
|
||||
|
The major advantage is that you can use the same server farm to manage your Background Jobs and Workers, as well as leverage the advanced scheduling that is available from Hangfire for [Recurring Jobs](https://docs.hangfire.io/en/latest/background-methods/performing-recurrent-tasks.html?highlight=recurring), aka Background Workers. |
||||
|
|
||||
|
## Installation |
||||
|
|
||||
|
It is suggested to use the [ABP CLI](CLI.md) to install this package. |
||||
|
|
||||
|
### Using the ABP CLI |
||||
|
|
||||
|
Open a command line window in the folder of the project (.csproj file) and type the following command: |
||||
|
|
||||
|
````bash |
||||
|
abp add-package Volo.Abp.BackgroundWorkers.Hangfire |
||||
|
```` |
||||
|
|
||||
|
### Manual Installation |
||||
|
|
||||
|
If you want to manually install; |
||||
|
|
||||
|
1. Add the [Volo.Abp.BackgroundWorkers.Hangfire](https://www.nuget.org/packages/Volo.Abp.BackgroundWorkers.Hangfire) NuGet package to your project: |
||||
|
|
||||
|
```` |
||||
|
Install-Package Volo.Abp.BackgroundWorkers.Hangfire |
||||
|
```` |
||||
|
|
||||
|
2. Add the `AbpBackgroundWorkersHangfireModule` to the dependency list of your module: |
||||
|
|
||||
|
````csharp |
||||
|
[DependsOn( |
||||
|
//...other dependencies |
||||
|
typeof(AbpBackgroundWorkersHangfireModule) //Add the new module dependency |
||||
|
)] |
||||
|
public class YourModule : AbpModule |
||||
|
{ |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
> Hangfire background worker integration provides an adapter `HangfirePeriodicBackgroundWorkerAdapter` to automatically load any `PeriodicBackgroundWorkerBase` and `AsyncPeriodicBackgroundWorkerBase` derived classes as `IHangfireBackgroundWorker` instances. This allows you to still to easily switch over to use Hangfire as the background manager even you have existing background workers that are based on the [default background workers implementation](Background-Workers.md). |
||||
|
|
||||
|
## Create a Background Worker |
||||
|
|
||||
|
`HangfireBackgroundWorkerBase` is an easy way to create a background worker. |
||||
|
|
||||
|
```` csharp |
||||
|
public class MyLogWorker : HangfireBackgroundWorkerBase |
||||
|
{ |
||||
|
public MyLogWorker() |
||||
|
{ |
||||
|
RecurringJobId = nameof(MyLogWorker); |
||||
|
CronExpression = Cron.Daily(); |
||||
|
} |
||||
|
|
||||
|
public override Task DoWorkAsync() |
||||
|
{ |
||||
|
Logger.LogInformation("Executed MyLogWorker..!"); |
||||
|
return Task.CompletedTask; |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
* **RecurringJobId** Is an optional parameter, see [Hangfire document](https://docs.hangfire.io/en/latest/background-methods/performing-recurrent-tasks.html) |
||||
|
* **CronExpression** Is a CRON expression, see [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) |
||||
|
|
||||
|
> You can directly implement the `IHangfireBackgroundWorker`, but `HangfireBackgroundWorkerBase` provides some useful properties like Logger. |
||||
|
|
||||
|
## Register BackgroundWorkerManager |
||||
|
|
||||
|
After creating a background worker class, you should add it to the `IBackgroundWorkerManager`. The most common place is the `OnApplicationInitialization` method of your module class: |
||||
|
|
||||
|
```` csharp |
||||
|
[DependsOn(typeof(AbpBackgroundWorkersModule))] |
||||
|
public class MyModule : AbpModule |
||||
|
{ |
||||
|
public override void OnApplicationInitialization( |
||||
|
ApplicationInitializationContext context) |
||||
|
{ |
||||
|
context.AddBackgroundWorker<MyLogWorker>(); |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
`context.AddBackgroundWorker(...)` is a shortcut extension method for the expression below: |
||||
|
|
||||
|
```` csharp |
||||
|
context.ServiceProvider |
||||
|
.GetRequiredService<IBackgroundWorkerManager>() |
||||
|
.Add( |
||||
|
context |
||||
|
.ServiceProvider |
||||
|
.GetRequiredService<MyLogWorker>() |
||||
|
); |
||||
|
```` |
||||
|
|
||||
|
So, it resolves the given background worker and adds to the `IBackgroundWorkerManager`. |
||||
|
|
||||
|
While we generally add workers in OnApplicationInitialization, there are no restrictions on that. You can inject IBackgroundWorkerManager anywhere and add workers at runtime. Background worker manager will stop and release all the registered workers when your application is being shut down. |
||||
@ -1,4 +1,4 @@ |
|||||
## Domain Services Best Practices & Conventions |
## Domain Services Best Practices & Conventions |
||||
|
|
||||
> **This document is not ready yet. Please see the [Domain Services](../Domain-Services.md) document.** |
> **This document is not ready yet. Please see the [Domain Services](../Domain-Services.md) document.** |
||||
|
|
||||
|
|||||
@ -0,0 +1,308 @@ |
|||||
|
# ABP Platform 5.0 Beta 1 Has Been Released |
||||
|
|
||||
|
Today, we are excited to release the [ABP Framework](https://abp.io/) and the [ABP Commercial](https://commercial.abp.io/) version **5.0 Beta**. This blog post introduces the new features and important changes in this new version. |
||||
|
|
||||
|
> **The planned release date for the [5.0.0 Release Candidate](https://github.com/abpframework/abp/milestone/51) version is November, 2021**. |
||||
|
|
||||
|
Please try the beta 1 version and provide feedback for a more stable ABP version 5.0! Thank you all. |
||||
|
|
||||
|
## Get Started with the 5.0 Beta 1 |
||||
|
|
||||
|
follow the steps below to try the version 5.0.0 beta 1 today; |
||||
|
|
||||
|
1) **Upgrade** the ABP CLI to the version `5.0.0-beta.1` using a command line terminal: |
||||
|
|
||||
|
````bash |
||||
|
dotnet tool update Volo.Abp.Cli -g --version 5.0.0-beta.1 |
||||
|
```` |
||||
|
|
||||
|
**or install** if you haven't installed before: |
||||
|
|
||||
|
````bash |
||||
|
dotnet tool install Volo.Abp.Cli -g --version 5.0.0-beta.1 |
||||
|
```` |
||||
|
|
||||
|
2) Create a **new application** with the `--preview` option: |
||||
|
|
||||
|
````bash |
||||
|
abp new BookStore --preview |
||||
|
```` |
||||
|
|
||||
|
See the [ABP CLI documentation](https://docs.abp.io/en/abp/latest/CLI) for all the available options. |
||||
|
|
||||
|
> You can also use the *Direct Download* tab on the [Get Started](https://abp.io/get-started) page by selecting the **Preview checkbox**. |
||||
|
|
||||
|
### Visual Studio Upgrade |
||||
|
|
||||
|
As .NET 6 is a preview version you need to make changes on the Visual Studio 2019. |
||||
|
If you want to run a .NET 6 project on Visual Studio 2019, you need to install the latest .NET SDK 6 from https://dotnet.microsoft.com/download/dotnet/6.0 |
||||
|
and also enable the `Use Previews of the .NET SDK` option from Visual Studio 2019 options. See the screenshot: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
|
||||
|
Alternatively you can download the latest Visual Studio 2022 preview to run/create the .NET 6 projects. We have tested the ABP solution with the Visual Studio 2022 `17.0.0 Preview 4.1`. Check out https://visualstudio.microsoft.com/vs/preview/ for more information. |
||||
|
|
||||
|
### 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-rc.1, so you need to move your solution to .NET 6.0 if you want to use the ABP 5.0. |
||||
|
* `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. |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
## What's new with Beta 1? |
||||
|
|
||||
|
In this section, I will introduce some major features released with beta 1. |
||||
|
|
||||
|
### Static (Generated) Client Proxies for C# and JavaScript |
||||
|
|
||||
|
Dynamic C# ([see](https://docs.abp.io/en/abp/latest/API/Dynamic-CSharp-API-Clients)) and JavaScript ([see](https://docs.abp.io/en/abp/latest/UI/AspNetCore/Dynamic-JavaScript-Proxies)) 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:** |
||||
|
|
||||
|
````bash |
||||
|
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: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
Once the proxies are generated, you can inject and use the application service interfaces of these proxies, like `IProductAppService` in this example. Usage is same of the [dynamic C# client proxies](https://docs.abp.io/en/abp/latest/API/Dynamic-CSharp-API-Clients). |
||||
|
|
||||
|
#### 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](https://docs.abp.io/en/abp/latest/UI/AspNetCore/Dynamic-JavaScript-Proxies). |
||||
|
|
||||
|
**Example usage:** |
||||
|
|
||||
|
````bash |
||||
|
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](https://docs.abp.io/en/abp/latest/UI/AspNetCore/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](https://docs.abp.io/en/abp/latest/UI/Angular/Service-Proxies). |
||||
|
|
||||
|
**Example usage:** |
||||
|
|
||||
|
````bash |
||||
|
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](https://microservices.io/patterns/data/transactional-outbox.html) 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](https://github.com/abpframework/abp/tree/dev/test/DistEvents), 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 |
||||
|
|
||||
|
Install the new [Volo.Abp.EventBus.Boxes](https://www.nuget.org/packages/Volo.Abp.EventBus.Boxes) NuGet package to your database layer (to `EntityFrameworkCore` or `MongoDB` project) or to the host application. Open a command-line terminal at the root directory of your database (or host) project and execute the following command: |
||||
|
|
||||
|
````csharp |
||||
|
abp add-package Volo.Abp.EventBus.Boxes |
||||
|
```` |
||||
|
|
||||
|
This will install the package and setup the ABP module dependency. This package depends on [DistributedLock.Core](https://www.nuget.org/packages/DistributedLock.Core) library which provides a distributed locking system for concurrency control in a distributed environment. There are [many distributed lock providers](https://github.com/madelson/DistributedLock#implementations), including Redis, SqlServer and ZooKeeper. You can use the one you like. Here, I will show the Redis provider. |
||||
|
|
||||
|
Add [DistributedLock.Redis](https://www.nuget.org/packages/DistributedLock.Redis) NuGet package to your project, then add the following code into the ConfigureService method of your ABP module class: |
||||
|
|
||||
|
````csharp |
||||
|
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: |
||||
|
|
||||
|
````json |
||||
|
"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: |
||||
|
|
||||
|
````csharp |
||||
|
public DbSet<IncomingEventRecord> IncomingEvents { get; set; } |
||||
|
public DbSet<OutgoingEventRecord> OutgoingEvents { get; set; } |
||||
|
```` |
||||
|
|
||||
|
Add the following lines inside the `OnModelCreating` method of your `DbContext` class: |
||||
|
|
||||
|
````csharp |
||||
|
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: |
||||
|
|
||||
|
````bash |
||||
|
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: |
||||
|
|
||||
|
````csharp |
||||
|
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](https://docs.abp.io/en/abp/latest/Distributed-Event-Bus) 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](https://docs.abp.io/en/abp/latest/Distributed-Event-Bus-RabbitMQ-Integration) or [Kafka](https://docs.abp.io/en/abp/latest/Distributed-Event-Bus-Kafka-Integration)), the [distributed events](https://docs.abp.io/en/abp/latest/Distributed-Event-Bus) are actually executed in-process, just like the [local events](https://docs.abp.io/en/abp/latest/Local-Event-Bus). 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](https://github.com/abpframework/abp/issues/9897) related to this change (some pre-defined events [will be removed](https://github.com/abpframework/abp/issues/9908) in the next major version since they are not needed anymore) |
||||
|
|
||||
|
### Inactivating a user |
||||
|
|
||||
|
The [Identity module](https://docs.abp.io/en/abp/latest/Modules/Identity) 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](https://docs.abp.io/en/abp/latest/Features) 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](https://docs.abp.io/en/abp/5.0/Background-Jobs-Hangfire). 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: |
||||
|
|
||||
|
````csharp |
||||
|
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: |
||||
|
|
||||
|
````csharp |
||||
|
app.UseHangfireDashboard("/hangfire", new DashboardOptions |
||||
|
{ |
||||
|
AsyncAuthorization = new[] { |
||||
|
new AbpHangfireAuthorizationFilter("MyPermissionName") |
||||
|
} |
||||
|
}); |
||||
|
```` |
||||
|
|
||||
|
You can define the permission (`MyPermissionName` in this example) using the standard [permission system](https://docs.abp.io/en/abp/5.0/Authorization#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:** |
||||
|
|
||||
|
````csharp |
||||
|
[Route("api/products")] |
||||
|
public class ProductController : AbpControllerBase |
||||
|
{ |
||||
|
// TODO: ... |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
## Ongoing Works & Next Release |
||||
|
|
||||
|
We'd published important features and changes with this beta 1 release. However, there are still some major works in development. The most important work is the **Bootstrap 5 upgrade**. ABP 5.0 will work on Bootstrap 5, which is an important change for existing applications. We suggest to prepare for this change from now. |
||||
|
|
||||
|
The next release will be 5.0.0-beta.2. It will include the Bootstrap 5 upgrade. We don't plan make another big work for the version 5.0. After the beta.2, we will work on tests, feedbacks and documentation to prepare a stable final release. |
||||
|
|
||||
|
## Community News |
||||
|
|
||||
|
### ABP was on ASP.NET Community Startup! |
||||
|
|
||||
|
It was great for us to be invited to Microsoft's [ASP.NET Community Weekly Standup](https://dotnet.microsoft.com/live/community-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](https://www.youtube.com/watch?v=vMWM-_ihjwM). |
||||
|
|
||||
|
### Upcoming ABP Book! |
||||
|
|
||||
|
I am currently authoring the first official book for the ABP Framework and it is on [pre-sale on Amazon](https://www.amazon.com/Mastering-ABP-Framework-maintainable-implementing-dp-1801079242/dp/1801079242) 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](https://www.amazon.com/Mastering-ABP-Framework-maintainable-implementing-dp-1801079242/dp/1801079242)! |
||||
|
|
||||
|
### New ABP Community posts |
||||
|
|
||||
|
Here, the latest posts added to the [ABP community](https://community.abp.io/): |
||||
|
|
||||
|
* [Deploy ABP Framework .NET Core tiered application to docker swarm](https://community.abp.io/articles/deploy-abp-framework-dotnet-core-tiered-app-to-docker-swarm-kcrjbjec) |
||||
|
* [How to override localization strings of depending modules](https://community.abp.io/articles/how-to-override-localization-strings-of-depending-modules-ba1oy03l) |
||||
|
* [Centralized logging for .NET Core ABP microservices application using Seq](https://community.abp.io/articles/centralized-logging-for-.net-core-abp-microservices-app-using-seq-g1xe7e7y) |
||||
|
* [Extend Tenant management and add custom host to your ABP application](https://community.abp.io/articles/extend-tenant-management-and-add-custom-host-to-your-abp-app-lwmi9lr5) |
||||
|
|
||||
|
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](https://github.com/abpframework/abp). Thank you all! |
||||
|
After Width: | Height: | Size: 125 KiB |
|
After Width: | Height: | Size: 4.8 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 5.6 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 28 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 26 KiB |
@ -0,0 +1,88 @@ |
|||||
|
# How to override localization strings of depending modules |
||||
|
|
||||
|
## Source Code |
||||
|
|
||||
|
You can find the source of the example solution used in this article [here](https://github.com/abpframework/abp-samples/tree/master/DocumentationSamples/ExtendLocalizationResource). |
||||
|
|
||||
|
## Getting Started |
||||
|
|
||||
|
This example is based on the following document |
||||
|
https://docs.abp.io/en/abp/latest/Localization#extending-existing-resource |
||||
|
|
||||
|
We will change the default `DisplayName:Abp.Timing.Timezone` and `Description:Abp.Timing.Timezone` of [`AbpTimingResource`](https://github.com/abpframework/abp/blob/dev/framework/src/Volo.Abp.Timing/Volo/Abp/Timing/Localization/AbpTimingResource.cs) and add localized text in [Russian language(`ru`)](https://github.com/abpframework/abp/blob/dev/framework/src/Volo.Abp.Timing/Volo/Abp/Timing/Localization/en.json). |
||||
|
|
||||
|
I created the `AbpTiming` folder in the `Localization` directory of the `ExtendLocalizationResource.Domain.Shared` project. |
||||
|
|
||||
|
Create `en.json` and `ru.json` in its directory. |
||||
|
|
||||
|
`en.json` |
||||
|
```json |
||||
|
{ |
||||
|
"culture": "en", |
||||
|
"texts": { |
||||
|
"DisplayName:Abp.Timing.Timezone": "My Time zone", |
||||
|
"Description:Abp.Timing.Timezone": "My Application time zone" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
`ru.json` |
||||
|
```json |
||||
|
{ |
||||
|
"culture": "ru", |
||||
|
"texts": { |
||||
|
"DisplayName:Abp.Timing.Timezone": "Часовой пояс", |
||||
|
"Description:Abp.Timing.Timezone": "Часовой пояс приложения" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
 |
||||
|
|
||||
|
We have below content in `ExtendLocalizationResource.Domain.Shared.csproj` file, See [Virtual-File-System](https://docs.abp.io/en/abp/latest/Virtual-File-System#working-with-the-embedded-files) understand how it works. |
||||
|
|
||||
|
```xml |
||||
|
<ItemGroup> |
||||
|
<EmbeddedResource Include="Localization\ExtendLocalizationResource\*.json" /> |
||||
|
<Content Remove="Localization\ExtendLocalizationResource\*.json" /> |
||||
|
</ItemGroup> |
||||
|
|
||||
|
<ItemGroup> |
||||
|
<PackageReference Include="Microsoft.Extensions.FileProviders.Embedded" Version="5.0.*" /> |
||||
|
</ItemGroup> |
||||
|
``` |
||||
|
|
||||
|
Change the code of the `ConfigureServices` method in `ExtendLocalizationResourceDomainSharedModule`. |
||||
|
|
||||
|
```cs |
||||
|
Configure<AbpLocalizationOptions>(options => |
||||
|
{ |
||||
|
options.Resources |
||||
|
.Add<ExtendLocalizationResourceResource>("en") |
||||
|
.AddBaseTypes(typeof(AbpValidationResource)) |
||||
|
.AddVirtualJson("/Localization/ExtendLocalizationResource"); |
||||
|
|
||||
|
//add following code |
||||
|
options.Resources |
||||
|
.Get<AbpTimingResource>() |
||||
|
.AddVirtualJson("/Localization/AbpTiming"); |
||||
|
|
||||
|
options.DefaultResourceType = typeof(ExtendLocalizationResourceResource); |
||||
|
}); |
||||
|
``` |
||||
|
|
||||
|
Execute `ExtendLocalizationResource.DbMigrator` to migrate the database and run `ExtendLocalizationResource.Web`. |
||||
|
|
||||
|
We have changed the English localization text and added Russian localization. |
||||
|
|
||||
|
### Index page |
||||
|
|
||||
|
```cs |
||||
|
<p>@AbpTimingResource["DisplayName:Abp.Timing.Timezone"]</p> |
||||
|
@using(CultureHelper.Use("ru")) |
||||
|
{ |
||||
|
<p>@AbpTimingResource["DisplayName:Abp.Timing.Timezone"]</p> |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
 |
||||
@ -1,3 +1,3 @@ |
|||||
# Configuration |
# Configuration |
||||
|
|
||||
ASP.NET Core has an flexible and extensible key-value based configuration system. In fact, the configuration system is a part of Microsoft.Extensions libraries and it is independent from ASP.NET Core. That means it can be used in any type of application. See [Microsoft's documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/) to learn the configuration infrastructure. ABP framework is 100% compatible with the configuration system. |
ASP.NET Core has an flexible and extensible key-value based configuration system. In fact, the configuration system is a part of Microsoft.Extensions libraries and it is independent from ASP.NET Core. That means it can be used in any type of application. See [Microsoft's documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/) to learn the configuration infrastructure. ABP framework is 100% compatible with the configuration system. |
||||
@ -0,0 +1,133 @@ |
|||||
|
# Distributed Event Bus Azure Integration |
||||
|
|
||||
|
> This document explains **how to configure the [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus/)** as the distributed event bus provider. See the [distributed event bus document](Distributed-Event-Bus.md) to learn how to use the distributed event bus system |
||||
|
|
||||
|
## Installation |
||||
|
|
||||
|
Use the ABP CLI to add [Volo.Abp.EventBus.Azure](https://www.nuget.org/packages/Volo.Abp.EventBus.Azure) NuGet package to your project: |
||||
|
|
||||
|
* Install the [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) if you haven't installed before. |
||||
|
* Open a command line (terminal) in the directory of the `.csproj` file you want to add the `Volo.Abp.EventBus.Azure` package. |
||||
|
* Run `abp add-package Volo.Abp.EventBus.Azure` command. |
||||
|
|
||||
|
If you want to do it manually, install the [Volo.Abp.EventBus.Azure](https://www.nuget.org/packages/Volo.Abp.EventBus.Azure) NuGet package to your project and add `[DependsOn(typeof(AbpEventBusAzureModule))]` to the [ABP module](Module-Development-Basics.md) class inside your project. |
||||
|
|
||||
|
## Configuration |
||||
|
|
||||
|
You can configure using the standard [configuration system](Configuration.md), like using the `appsettings.json` file, or using the [options](Options.md) classes. |
||||
|
|
||||
|
### `appsettings.json` file configuration |
||||
|
|
||||
|
This is the simplest way to configure the Azure Service Bus settings. It is also very strong since you can use any other configuration source (like environment variables) that is [supported by the AspNet Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/). |
||||
|
|
||||
|
**Example: The minimal configuration to connect to Azure Service Bus Namespace with default configurations** |
||||
|
|
||||
|
````json |
||||
|
{ |
||||
|
"Azure": { |
||||
|
"ServiceBus": { |
||||
|
"Connections": { |
||||
|
"Default": { |
||||
|
"ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={};EntityPath=marketing-consent" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"EventBus": { |
||||
|
"ConnectionName": "Default", |
||||
|
"SubscriberName": "MySubscriberName", |
||||
|
"TopicName": "MyTopicName" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
* `MySubscriberName` is the name of this subscription, which is used as the **Subscriber** on the Azure Service Bus. |
||||
|
* `MyTopicName` is the **topic name**. |
||||
|
|
||||
|
See [the Azure Service Bus document](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions) to understand these options better. |
||||
|
|
||||
|
#### Connections |
||||
|
|
||||
|
If you need to connect to another Azure Service Bus Namespace the Default, you need to configure the connection properties. |
||||
|
|
||||
|
**Example: Declare two connections and use one of them for the event bus** |
||||
|
|
||||
|
````json |
||||
|
{ |
||||
|
"Azure": { |
||||
|
"ServiceBus": { |
||||
|
"Connections": { |
||||
|
"Default": { |
||||
|
"ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey={{SharedAccessKey}}" |
||||
|
}, |
||||
|
"SecondConnection": { |
||||
|
"ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={{SharedAccessKey}}" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"EventBus": { |
||||
|
"ConnectionName": "SecondConnection", |
||||
|
"SubscriberName": "MySubscriberName", |
||||
|
"TopicName": "MyTopicName" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
This allows you to use multiple Azure Service Bus namespaces in your application, but select one of them for the event bus. |
||||
|
|
||||
|
You can use any of the [ServiceBusAdministrationClientOptions](https://docs.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.administration.servicebusadministrationclientoptions?view=azure-dotnet), [ServiceBusClientOptions](https://docs.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusclientoptions?view=azure-dotnet), [ServiceBusProcessorOptions](https://docs.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusprocessoroptions?view=azure-dotnet) properties for the connection. |
||||
|
|
||||
|
**Example: Specify the Admin, Client and Processor options** |
||||
|
|
||||
|
````json |
||||
|
{ |
||||
|
"Azure": { |
||||
|
"ServiceBus": { |
||||
|
"Connections": { |
||||
|
"Default": { |
||||
|
"ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={};EntityPath=marketing-consent", |
||||
|
"Admin": { |
||||
|
"Retry": { |
||||
|
"MaxRetries": 3 |
||||
|
} |
||||
|
}, |
||||
|
"Client": { |
||||
|
"RetryOptions": { |
||||
|
"MaxRetries": 1 |
||||
|
} |
||||
|
}, |
||||
|
"Processor": { |
||||
|
"AutoCompleteMessages": true, |
||||
|
"ReceiveMode": "ReceiveAndDelete" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"EventBus": { |
||||
|
"ConnectionName": "Default", |
||||
|
"SubscriberName": "MySubscriberName", |
||||
|
"TopicName": "MyTopicName" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
### The Options Classes |
||||
|
|
||||
|
`AbpAzureServiceBusOptions` and `AbpAzureEventBusOptions` classes can be used to configure the connection strings and event bus options for Azure Service Bus. |
||||
|
|
||||
|
You can configure this options inside the `ConfigureServices` of your [module](Module-Development-Basics.md). |
||||
|
|
||||
|
**Example: Configure the connection** |
||||
|
|
||||
|
````csharp |
||||
|
Configure<AbpAzureServiceBusOptions>(options => |
||||
|
{ |
||||
|
options.Connections.Default.ConnectionString = "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={}"; |
||||
|
options.Connections.Default.Admin.Retry.MaxRetries = 3; |
||||
|
options.Connections.Default.Client.RetryOptions.MaxRetries = 1; |
||||
|
}); |
||||
|
```` |
||||
|
|
||||
|
Using these options classes can be combined with the `appsettings.json` way. Configuring an option property in the code overrides the value in the configuration file. |
||||
@ -1 +1 @@ |
|||||
This document has been [moved to here](Testing.md). |
This document has been [moved to here](Testing.md). |
||||
@ -1,3 +1,3 @@ |
|||||
# JSON |
# JSON |
||||
|
|
||||
TODO |
TODO |
||||
@ -0,0 +1,101 @@ |
|||||
|
# Angular UI v4.x to v5.0 Migration Guide |
||||
|
|
||||
|
## Breaking Changes |
||||
|
|
||||
|
### Overall |
||||
|
|
||||
|
See the overall list of breaking changes: |
||||
|
|
||||
|
- Bootstrap 5 implementation [#10067](https://github.com/abpframework/abp/issues/10067) |
||||
|
- Remove NGXS dependency & states [#9952](https://github.com/abpframework/abp/issues/9952) |
||||
|
- Install @angular/localize package to startup templates [#10099](https://github.com/abpframework/abp/issues/10099) |
||||
|
- Create new secondary entrypoints and move the related proxies to there [#10060](https://github.com/abpframework/abp/issues/10060) |
||||
|
- Move SettingTabsService to @abp/ng.setting-management/config package from @abp/ng.core [#10061](https://github.com/abpframework/abp/issues/10061) |
||||
|
- Make the @abp/ng.account dependent on @abp/ng.identity [#10059](https://github.com/abpframework/abp/issues/10059) |
||||
|
- Set default abp-modal size medium [#10118](https://github.com/abpframework/abp/issues/10118) |
||||
|
- 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 |
||||
|
|
||||
|
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 |
||||
|
|
||||
|
TODO |
||||
|
|
||||
|
### 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. |
||||
|
|
||||
|
If you'd like to use NGXS after upgrading to v5.0, you have to install the NGXS to your project. The package can be installed with the following command: |
||||
|
|
||||
|
```bash |
||||
|
npm install @ngxs/store |
||||
|
|
||||
|
# or |
||||
|
|
||||
|
yarn add @ngxs/store |
||||
|
``` |
||||
|
|
||||
|
NGXS states and actions, some namespaces have been removed. See [this issue](https://github.com/abpframework/abp/issues/9952) for the details. |
||||
|
|
||||
|
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`](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: |
||||
|
|
||||
|
```bash |
||||
|
npm install @angular/localize |
||||
|
|
||||
|
# or |
||||
|
|
||||
|
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 |
||||
|
|
||||
|
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: |
||||
|
|
||||
|
```ts |
||||
|
import { IdentityUserService } from '@abp/ng.identity/proxy'; |
||||
|
|
||||
|
@Component({}) |
||||
|
export class YourComponent { |
||||
|
constructor(private identityUserService: IdentityUserService) {} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Following proxies have been affected: |
||||
|
|
||||
|
- `@abp/ng.account` to `@abp/ng.account.core/proxy` |
||||
|
- `@abp/ng.feature-management` to `@abp/ng.feature-management/proxy` |
||||
|
- `@abp/ng.identity` to `@abp/ng.identity/proxy` |
||||
|
- `@abp/ng.permission-management` to `@abp/ng.permission-management/proxy` |
||||
|
- `@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** has moved from `@abp/ng.core` to `@abp/ng.setting-management/config`. |
||||
|
|
||||
|
### 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: |
||||
|
|
||||
|
```ts |
||||
|
import { ChartModule } from '@abp/ng.components/chart.js'; |
||||
|
|
||||
|
@NgModule({ |
||||
|
imports: [ |
||||
|
ChartModule, |
||||
|
// ... |
||||
|
], |
||||
|
// ... |
||||
|
}) |
||||
|
export class YourFeatureModule {} |
||||
|
``` |
||||
@ -0,0 +1,51 @@ |
|||||
|
# ABP Framework v4.x to v5.0 Migration Guide |
||||
|
|
||||
|
## IdentityUser |
||||
|
|
||||
|
`IsActive <bool>` 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`** |
||||
|
|
||||
|
For EFCore you can set `defaultValue` to `true` in the migration class: |
||||
|
(This will add the column with `true` value for the existing records.) |
||||
|
|
||||
|
```cs |
||||
|
public partial class AddIsActiveToIdentityUser : Migration |
||||
|
{ |
||||
|
protected override void Up(MigrationBuilder migrationBuilder) |
||||
|
{ |
||||
|
migrationBuilder.AddColumn<bool>( |
||||
|
name: "IsActive", |
||||
|
table: "AbpUsers", |
||||
|
type: "bit", |
||||
|
nullable: false, |
||||
|
defaultValue: true); // Default is false. |
||||
|
} |
||||
|
|
||||
|
protected override void Down(MigrationBuilder migrationBuilder) |
||||
|
{ |
||||
|
migrationBuilder.DropColumn( |
||||
|
name: "IsActive", |
||||
|
table: "AbpUsers"); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
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<AbpMongoDbOptions>(x => x.UseAbpClockHandleDateTime = false); |
||||
|
``` |
||||
|
|
||||
|
## IApiScopeRepository |
||||
|
|
||||
|
`GetByNameAsync` method renamed as `FindByNameAsync`. |
||||
|
|
||||
|
## Angular UI |
||||
|
|
||||
|
See the [Angular UI 5.0 Migration Guide](Abp-5_0-Angular.md). |
||||
@ -1,7 +1,7 @@ |
|||||
# ABP Framework Migration Guides |
# ABP Framework Migration Guides |
||||
|
|
||||
* [4.2 to 4.3](Abp-4_3.md) |
- [4.x to 5.0](Abp-5_0.md) |
||||
* [4.x to 4.2](Abp-4_2.md) |
- [4.2 to 4.3](Abp-4_3.md) |
||||
* [3.3.x to 4.0](Abp-4_0.md) |
- [4.x to 4.2](Abp-4_2.md) |
||||
* [2.9.x to 3.0](../UI/Angular/Migration-Guide-v3.md) |
- [3.3.x to 4.0](Abp-4_0.md) |
||||
|
- [2.9.x to 3.0](../UI/Angular/Migration-Guide-v3.md) |
||||
|
|||||
@ -1,3 +1,3 @@ |
|||||
# RabbitMQ |
# RabbitMQ |
||||
|
|
||||
TODO! |
TODO! |
||||
@ -0,0 +1,249 @@ |
|||||
|
# Chart Component |
||||
|
|
||||
|
ABP Chart component exposed by `@abp/ng.components/chart.js` is based on [`charts.js`](https://www.chartjs.org/) v3+. You don't need to install the `chart.js` package. Since the `@abp/ng.components` is dependent on the `chart.js`, the package is already installed in your project. |
||||
|
|
||||
|
> Chart component loads `chart.js` script lazy. So it does not increase the bundle size. |
||||
|
|
||||
|
## How to Use |
||||
|
|
||||
|
First of all, need to import the `ChartModule` to your feature module as follows: |
||||
|
|
||||
|
```ts |
||||
|
// your-feature.module.ts |
||||
|
|
||||
|
import { ChartModule } from '@abp/ng.components/chart.js'; |
||||
|
import { ChartDemoComponent } from './chart-demo.component'; |
||||
|
|
||||
|
@NgModule({ |
||||
|
imports: [ |
||||
|
ChartModule, |
||||
|
// ... |
||||
|
], |
||||
|
declarations: [ChartDemoComponent], |
||||
|
// ... |
||||
|
}) |
||||
|
export class YourFeatureModule {} |
||||
|
``` |
||||
|
|
||||
|
Then, `abp-chart` component can be used. See an example: |
||||
|
|
||||
|
```ts |
||||
|
// chart-demo.component.ts |
||||
|
|
||||
|
import { Component } from '@angular/core'; |
||||
|
|
||||
|
@Component({ |
||||
|
selector: 'app-chart-demo', |
||||
|
template: ` <abp-chart type="pie" [data]="data"></abp-chart> `, |
||||
|
}) |
||||
|
export class ChartDemoComponent { |
||||
|
data = { |
||||
|
labels: ['Data 1', 'Data 2', 'Data 3'], |
||||
|
datasets: [ |
||||
|
{ |
||||
|
label: 'Dataset 1', |
||||
|
data: [40, 15, 45], |
||||
|
backgroundColor: ['#ff7675', '#fdcb6e', '#0984e3'], |
||||
|
}, |
||||
|
], |
||||
|
}; |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
> **Important Note**: Changing the chart data without creating a new data instance does not trigger change detection. In order to chart to redraw itself, a new data object needs to be created. |
||||
|
|
||||
|
See the result: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
## Examples |
||||
|
|
||||
|
### Doughnut |
||||
|
|
||||
|
```ts |
||||
|
import { Component } from '@angular/core'; |
||||
|
|
||||
|
@Component({ |
||||
|
selector: 'app-chart-demo', |
||||
|
template: ` |
||||
|
<abp-chart |
||||
|
type="doughnut" |
||||
|
[data]="data" |
||||
|
[options]="options" |
||||
|
width="400px" |
||||
|
height="400px" |
||||
|
></abp-chart> |
||||
|
`, |
||||
|
}) |
||||
|
export class ChartDemoComponent { |
||||
|
data = { |
||||
|
labels: ['Data 1', 'Data 2', 'Data 3'], |
||||
|
datasets: [ |
||||
|
{ |
||||
|
label: 'Dataset 1', |
||||
|
data: [40, 15, 45], |
||||
|
backgroundColor: ['#a0e6c3', '#f0ea4c', '#5b9dc3'], |
||||
|
}, |
||||
|
], |
||||
|
}; |
||||
|
|
||||
|
options = { |
||||
|
plugins: { |
||||
|
title: { |
||||
|
display: true, |
||||
|
text: 'Doughnut Chart', |
||||
|
fontSize: 16, |
||||
|
}, |
||||
|
legend: { |
||||
|
position: 'bottom', |
||||
|
}, |
||||
|
}, |
||||
|
}; |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Result: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### Bar |
||||
|
|
||||
|
```ts |
||||
|
import { Component } from '@angular/core'; |
||||
|
|
||||
|
@Component({ |
||||
|
selector: 'app-chart-demo', |
||||
|
template: ` |
||||
|
<abp-chart |
||||
|
type="bar" |
||||
|
[data]="data" |
||||
|
width="400px" |
||||
|
height="400px" |
||||
|
></abp-chart> |
||||
|
`, |
||||
|
}) |
||||
|
export class ChartDemoComponent { |
||||
|
data = { |
||||
|
labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'], |
||||
|
datasets: [ |
||||
|
{ |
||||
|
label: 'First dataset', |
||||
|
backgroundColor: '#42A5F5', |
||||
|
data: [65, 59, 80, 81, 56, 55, 40], |
||||
|
}, |
||||
|
{ |
||||
|
label: 'Second dataset', |
||||
|
backgroundColor: '#FFA726', |
||||
|
data: [28, 48, 40, 19, 86, 27, 90], |
||||
|
}, |
||||
|
], |
||||
|
}; |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Result: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### Radar |
||||
|
|
||||
|
```ts |
||||
|
import { Component } from '@angular/core'; |
||||
|
|
||||
|
@Component({ |
||||
|
selector: 'app-chart-demo', |
||||
|
template: ` |
||||
|
<abp-chart |
||||
|
type="radar" |
||||
|
[data]="data" |
||||
|
width="400px" |
||||
|
height="400px" |
||||
|
></abp-chart> |
||||
|
|
||||
|
<button class="btn btn-primary-outline mt-4" (click)="addDataset()"> |
||||
|
Add dataset |
||||
|
</button> |
||||
|
`, |
||||
|
}) |
||||
|
export class ChartDemoComponent { |
||||
|
data = { |
||||
|
labels: [ |
||||
|
'January', |
||||
|
'February', |
||||
|
'March', |
||||
|
'April', |
||||
|
'May', |
||||
|
'June', |
||||
|
'July', |
||||
|
'August', |
||||
|
'September', |
||||
|
'October', |
||||
|
'November', |
||||
|
'December', |
||||
|
], |
||||
|
datasets: [ |
||||
|
{ |
||||
|
label: 'Dataset 1', |
||||
|
backgroundColor: 'rgba(179,181,198,0.2)', |
||||
|
borderColor: 'rgba(179,181,198,1)', |
||||
|
data: [65, 59, 90, 81, 56, 55, 40, 35, 82, 51, 62, 95], |
||||
|
}, |
||||
|
{ |
||||
|
label: 'Dataset 2', |
||||
|
backgroundColor: 'rgba(255,99,132,0.2)', |
||||
|
borderColor: 'rgba(255,99,132,1)', |
||||
|
data: [28, 48, 40, 58, 96, 27, 100, 44, 85, 77, 71, 39], |
||||
|
}, |
||||
|
], |
||||
|
}; |
||||
|
|
||||
|
addDataset() { |
||||
|
this.data = { |
||||
|
...this.data, |
||||
|
datasets: [ |
||||
|
...this.data.datasets, |
||||
|
{ |
||||
|
label: 'Dataset 3', |
||||
|
backgroundColor: 'rgba(54,162,235,0.2)', |
||||
|
borderColor: 'rgba(54, 162, 235, 1)', |
||||
|
data: [90, 95, 98, 91, 99, 96, 89, 95, 98, 93, 92, 90], |
||||
|
}, |
||||
|
], |
||||
|
}; |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Result: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
See the [`chart.js` samples](https://www.chartjs.org/docs/latest/samples) for more examples. |
||||
|
|
||||
|
## API |
||||
|
|
||||
|
### `abp-chart` |
||||
|
|
||||
|
#### Properties |
||||
|
|
||||
|
| Name | Description | Type | Default | |
||||
|
| --------------- | ---------------------------------------------------------------- | ----------------------- | ------- | |
||||
|
| `[type]` | Type of the chart. | `string` | null | |
||||
|
| `[data]` | Chart data to display | `any` | null | |
||||
|
| `[options]` | Chart options to customize | `any` | null | |
||||
|
| `[plugins]` | Chart plugins to customize behaviour | `any` | null | |
||||
|
| `[width]` | Witdh of the chart | `string` | null | |
||||
|
| `[height]` | Height of the chart | `string` | null | |
||||
|
| `[responsive]` | Whether the chart is responsive | `boolean` | true | |
||||
|
| `(dataSelect)` | A callback that executes when an element on the chart is clicked | `EventEmitter<any>` | - | |
||||
|
| `(initialized)` | A callback that executes when the chart is initialized | `EventEmitter<boolean>` | - | |
||||
|
|
||||
|
#### Methods |
||||
|
|
||||
|
| Name | Description | Parameters | |
||||
|
| ---------------- | ------------------------------------------------------------------- | ---------- | |
||||
|
| `refresh` | Redraws the chart | - | |
||||
|
| `reinit` | Destroys the chart then creates it again | - | |
||||
|
| `getBase64Image` | Returns a base 64 encoded string of the chart in it's current state | - | |
||||
|
| `generateLegend` | Returns an HTML string of a legend for the chart | - | |
||||
|
| `getCanvas` | Returns the canvas HTML element | - | |
||||
@ -0,0 +1,10 @@ |
|||||
|
## Angular UI Extensions |
||||
|
|
||||
|
Angular UI extensions system allows you to add a new action to the actions menu, a new column to the data table, a new action to the toolbar of a page, and add a new field to the create and/or edit forms. |
||||
|
|
||||
|
See the documents below for the details: |
||||
|
|
||||
|
* [Entity Action Extensions](Entity-Action-Extensions.md) |
||||
|
* [Data Table Column (or Entity Prop) Extensions](Data-Table-Column-Extensions.md) |
||||
|
* [Page Toolbar Extension](Page-Toolbar-Extensions.md) |
||||
|
* [Dynamic Form (or Form Prop) Extensions](Dynamic-Form-Extensions.md) |
||||
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 3.2 MiB |
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue