diff --git a/docs/en/Audit-Logging.md b/docs/en/Audit-Logging.md index f11a3f19e3..7e0f358a16 100644 --- a/docs/en/Audit-Logging.md +++ b/docs/en/Audit-Logging.md @@ -1,3 +1,294 @@ # Audit Logging -TODO \ No newline at end of file +[Wikipedia](https://en.wikipedia.org/wiki/Audit_trail): "*An audit trail (also called **audit log**) is a security-relevant chronological record, set of records, and/or destination and source of records that provide documentary evidence of the sequence of activities that have affected at any time a specific operation, procedure, or event*". + +ABP Framework provides an **extensible audit logging system** that automates the audit logging by **convention** and provides **configuration** points to control the level of the audit logs. + +An **audit log object** (see the Audit Log Object section below) is typically created & saved per web request. It includes; + +* **Request & response details** (like URL, Http method, Browser info, HTTP status code... etc.). +* **Performed actions** (controller actions and application service method calls with their parameters). +* **Entity changes** occurred in the web request. +* **Exception** information (if there was an error while executing the request). +* **Request duration** (to measure the performance of the application). + +> [Startup templates](Startup-Templates/Index.md) are configured for the audit logging system which is suitable for most of the applications. Use this document for a detailed control over the audit log system. + +### Database Provider Support + +* Fully supported by the [Entity Framework Core](Entity-Framework-Core.md) provider. +* Entity change logging is not supported by the [MongoDB](MongoDB.md) provider. Other features work as expected. + +## UseAuditing() + +`UseAuditing()` middleware should be added to the ASP.NET Core request pipeline in order to create and save the audit logs. If you've created your applications using [the startup templates](Startup-Templates/Index.md), it is already added. + +## AbpAuditingOptions + +`AbpAuditingOptions` is the main [options object](Options.md) to configure the audit log system. You can configure it in the `ConfigureServices` method of your [module](Module-Development-Basics.md): + +````csharp +Configure(options => +{ + options.IsEnabled = false; //Disables the auditing system +}); +```` + +Here, a list of the options you can configure: + +* `IsEnabled` (default: `true`): A root switch to enable or disable the auditing system. Other options is not used if this value is `false`. +* `HideErrors` (default: `true`): Audit log system hides and write regular [logs](Logging.md) if any error occurs while saving the audit log objects. If saving the audit logs is critical for your system, set this to `false` to throw exception in case of hiding the errors. +* `IsEnabledForAnonymousUsers` (default: `true`): If you want to write audit logs only for the authenticated users, set this to `false`. If you save audit logs for anonymous users, you will see `null` for `UserId` values for these users. +* `IsEnabledForGetRequests` (default: `false`): HTTP GET requests should not make any change in the database normally and audit log system doesn't save audit log objects for GET request. Set this to `true` to enable it also for the GET requests. +* `ApplicationName`: If multiple applications saving audit logs into a single database, set this property to your application name, so you can distinguish the logs of different applications. +* `IgnoredTypes`: A list of `Type`s to be ignored for audit logging. If this is an entity type, changes for this type of entities will not be saved. This list is also used while serializing the action parameters. +* `EntityHistorySelectors`: A list of selectors those are used to determine if an entity type is selected for saving the entity change. See the section below for details. +* `Contributors`: A list of `AuditLogContributor` implementations. A contributor is a way of extending the audit log system. See the "Audit Log Contributors" section below. + +### Entity History Selectors + +Saving all changes of all your entities would require a lot of database space. For this reason, **audit log system doesn't save any change for the entities unless you explicitly configure it**. + +To save all changes of all entities, simply use the `AddAllEntities()` extension method. + +````csharp +Configure(options => +{ + options.EntityHistorySelectors.AddAllEntities(); +}); +```` + +`options.EntityHistorySelectors` actually a list of type predicate. You can write a lambda expression to define your filter. + +The example selector below does the same of the `AddAllEntities()` extension method defined above: + +````csharp +Configure(options => +{ + options.EntityHistorySelectors.Add( + new NamedTypeSelector( + "MySelectorName", + type => + { + if (typeof(IEntity).IsAssignableFrom(type)) + { + return true; + } + else + { + return false; + } + } + ) + ); +}); +```` + +The condition `typeof(IEntity).IsAssignableFrom(type)` will be `true` for any class implements the `IEntity` interface (this is technically all the entities in your application). You can conditionally check and return `true` or `false` based on your preference. + +`options.EntityHistorySelectors` is a flexible and dynamic way of selecting the entities for audit logging. Another way is to use the `Audited` and `DisableAuditing` attributes per entity. + +## Enabling/Disabling Audit Logging for Services + +### Enable/Disable for Controllers & Actions + +All the controller actions are logged by default (see `IsEnabledForGetRequests` above for GET requests). + +You can use the `[DisableAuditing]` to disable it for a specific controller type: + +````csharp +[DisableAuditing] +public class HomeController : AbpController +{ + //... +} +```` + +Use `[DisableAuditing]` for any action to control it in the action level: + +````csharp +public class HomeController : AbpController +{ + [DisableAuditing] + public async Task Home() + { + //... + } + + public async Task OtherActionLogged() + { + //... + } +} +```` + +### Enable/Disable for Application Services & Methods + +[Application service](Application-Services.md) method calls also included into the audit log by default. You can use the `[DisableAuditing]` in service or method level. + +#### Enable/Disable for Other Services + +Action audit logging can be enabled for any type of class (registered to and resolved from the [dependency injection](Dependency-Injection.md)) while it is only enabled for the controllers and the application services by default. + +Use `[Audited]` and `[DisableAuditing]` for any class or method that need to be audit logged. In addition, your class can (directly or inherently) implement the `IAuditingEnabled` interface to enable the audit logging for that class by default. + +### Enable/Disable for Entities & Properties + +An entity is ignored on entity change audit logging in the following cases; + +* If you add an entity type to the `AbpAuditingOptions.IgnoredTypes` (as explained before), it is completely ignored in the audit logging system. +* If the object is not an [entity](Entities.md) (not implements `IEntity` directly or inherently - All entities implement this interface by default). +* If entity type is not public. + +Otherwise, you can use `Audited` to enable entity change audit logging for an entity: + +````csharp +[Audited] +public class MyEntity : Entity +{ + //... +} +```` + +Or disable it for an entity: + +````csharp +[DisableAuditing] +public class MyEntity : Entity +{ + //... +} +```` + +Disabling audit logging can be necessary only if the entity is being selected by the `AbpAuditingOptions.EntityHistorySelectors` that explained before. + +You can disable auditing only some properties of your entities for a detailed control over the audit logging: + +````csharp +[Audited] +public class MyUser : Entity +{ + public string Name { get; set; } + + public string Email { get; set; } + + [DisableAuditing] //Ignore the Passoword on audit logging + public string Password { get; set; } +} +```` + +Audit log system will save changes for the `MyUser` entity while it ignores the `Password` property which can be dangerous to save for security purposes. + +In some cases, you may want to save a few properties but ignore all others. Writing `[DisableAuditing]` for all the other properties would be tedious. In such cases, use `[Audited]` only for the desired properties and mark the entity with the `[DisableAuditing]` attribute: + +````csharp +[DisableAuditing] +public class MyUser : Entity +{ + [Audited] //Only log the Name change + public string Name { get; set; } + + public string Email { get; set; } + + public string Password { get; set; } +} +```` + +## IAuditingStore + +`IAuditingStore` is an interface that is used to save the audit log objects (explained below) by the ABP Framework. If you need to save the audit log objects to a custom data store, you can implement the `IAuditingStore` in your own application and replace using the [dependency injection system](Dependency-Injection.md). + +`SimpleLogAuditingStore` is used if no audit store was registered. It simply writes the audit object to the standard [logging system](Logging.md). + +[The Audit Logging Module](Modules/Audit-Logging.md) has been configured in [the startup templates](Startup-Templates/Index.md) saves audit log objects to a database (it supports multiple database providers). So, most of the times you don't care about how `IAuditingStore` was implemented and used. + +## Audit Log Object + +An **audit log object** is created for each **web request** by default. An audit log object can be represented by the following relation diagram: + +![**auditlog-object-diagram**](images/auditlog-object-diagram.png) + +* **AuditLogInfo**: The root object with the following properties: + * `ApplicationName`: When you save audit logs of different applications to the same database, this property is used to distinguish the logs of the applications. + * `UserId`: Id of the current user, if the user has logged in. + * `UserName`: User name of the current user, if the user has logged in (this value is here to not depend on the identity module/system for lookup). + * `TenantId`: Id of the current tenant, for a multi-tenant application. + * `TenantName`: Name of the current tenant, for a multi-tenant application. + * `ExecutionTime`: The time when this audit log object has been created. + * `ExecutionDuration`: Total execution duration of the request, in milliseconds. This can be used to observe the performance of the application. + * `ClientId`: Id of the current client, if the client has been authenticated. A client is generally a 3rd-party application using the system over an HTTP API. + * `ClientName`: Name of the current client, if available. + * `ClientIpAddress`: IP address of the client/user device. + * `CorrelationId`: Current [Correlation Id]((CorrelationId.md)). Correlation Id is used to relate the audit logs written by different applications (or microservices) in a single logical operation. + * `BrowserInfo`: Browser name/version info of the current user, if available. + * `HttpMethod`: HTTP method of the current request (GET, POST, PUT, DELETE... etc.). + * `HttpStatusCode`: HTTP response status code for this request. + * `Url`: URL of the request. +* **AuditLogActionInfo**: An audit log action is typically a controller action or an [application service](Application-Services.md) method call during the web request. One audit log may contain multiple actions. An action object has the following properties: + * `ServiceName`: Name of the executed controller/service. + * `MethodName`: Name of the executed method of the controller/service. + * `Parameters`: A JSON formatted text representing the parameters passed to the method. + * `ExecutionTime`: The time when this method was executed. + * `ExecutionDuration`: Duration of the method execution, in milliseconds. This can be used to observe the performance of the method. +* **EntityChangeInfo**: Represents a change of an entity in this web request. An audit log may contain zero or more entity changes. An entity change has the following properties: + * `ChangeTime`: The time when the entity was changed. + * `ChangeType`: An enum with the following fields: `Created` (0), `Updated` (1) and `Deleted` (2). + * `EntityId`: Id of the entity that was changed. + * `EntityTenantId`: Id of the tenant this entity belongs to. + * `EntityTypeFullName`: Type (class) name of the entity with full namespace (like *Acme.BookStore.Book* for the Book entity). +* **EntityPropertyChangeInfo**: Represents a change of a property of an entity. An entity change info (explained above) may contain one or more property change with the following properties: + * `NewValue`: New value of the property. It is `null` if the entity was deleted. + * `OriginalValue`: Old/original value before the change. It is `null` if the entity was newly created. + * `PropertyName`: The name of the property on the entity class. + * `PropertyTypeFullName`: Type (class) name of the property with full namespace. +* **Exception**: An audit log object may contain zero or more exception. In this way, you can get a report of the failed requests. +* **Comment**: An arbitrary string value to add custom messages to the audit log entry. An audit log object may contain zero or more comments. + +In addition to the standard properties explained above, `AuditLogInfo`, `AuditLogActionInfo` and `EntityChangeInfo` objects implement the `IHasExtraProperties` interface, so you can add custom properties to these objects. + +## Audit Log Contributors + +You can extend the auditing system by creating a class that is derived from the `AuditLogContributor` class which defines the `PreContribute` and the `PostContribute` methods. + +The only pre-built contributor is the `AspNetCoreAuditLogContributor` class which sets the related properties for an HTTP request. + +A contributor can set properties and collections of the `AuditLogInfo` class to add more information. + +Example: + +````csharp +public class MyAuditLogContributor : AuditLogContributor +{ + public override void PreContribute(AuditLogContributionContext context) + { + var currentUser = context.ServiceProvider.GetRequiredService(); + context.AuditInfo.SetProperty( + "MyCustomClaimValue", + currentUser.FindClaimValue("MyCustomClaim") + ); + } + + public override void PostContribute(AuditLogContributionContext context) + { + context.AuditInfo.Comments.Add("Some comment..."); + } +} +```` + +* `context.ServiceProvider` can be used to resolve services from the [dependency injection](Dependency-Injection.md). +* `context.AuditInfo` can be used to access to the current audit log object to manipulate it. + +After creating such a contributor, you must add it to the `AbpAuditingOptions.Contributors` list: + +````csharp +Configure(options => +{ + options.Contributors.Add(new MyAuditLogContributor()); +}); +```` + +## The Audit Logging Module + +The Audit Logging Module basically implements the `IAuditingStore` to save the audit log objects to a database. It supports multiple database providers. This module is added to the startup templates by default. + +See [the Audit Logging Module document](Modules/Audit-Logging.md) for more about it. \ No newline at end of file diff --git a/docs/en/Blog-Posts/2020-01-15 v2_0_Release/Post.md b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/Post.md index c4646e66d1..d3a525c63f 100644 --- a/docs/en/Blog-Posts/2020-01-15 v2_0_Release/Post.md +++ b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/Post.md @@ -1,8 +1,8 @@ # ABP Framework v2.0 and the ABP Commercial -ABP Framework v2.0 has been released this week. This post explains why we have released an **early major version** and what is changed with version 2.0. +ABP Framework v2.0 has been released in this week. This post explains why we have released an **early major version** and what is changed with version 2.0. -In addition to the v2.0 release, we have also announced **ABP Commercial** which is a set of professional modules, tools, themes, and services built on top of the open-source ABP framework. +In addition to the v2.0 release, we are excited to announce the **ABP Commercial**, which is a set of professional modules, tools, themes, and services built on top of the open-source ABP framework. ## ABP Framework v2.0 @@ -12,7 +12,7 @@ It was planned to release v1.2 after the [v1.1.2](https://github.com/abpframewor We have investigated the problem deeply and have seen that the root cause of the problem was related to the implementation of **intercepting `async` methods**. Besides, there were some **`async` over `sync`** usages that effected the thread pool optimization. -Finally, we **solved all the problems** with the great help of the **community**. But we also had some important **design decisions** which cause some **breaking changes** and we had to change the major version number of the framework because of the **semantic versioning**. +Finally, we **solved all the problems** with the great help of the **community**. But we also had some important **design decisions** which cause some **breaking changes** and we had to change the major version number of the framework because of the [semantic versioning](https://semver.org/). Most of the applications won't be affected by [the breaking changes](https://github.com/abpframework/abp/releases), or it will be trivial to make these necessary changes. @@ -74,15 +74,15 @@ See [the release notes](https://github.com/abpframework/abp/releases/tag/2.0.0) ### Documentation -We have completed some missing documentation with the v2.0 release. In the following weeks, we will mostly focus on the basic documentation and tutorials. +We have completed some missing documentation with the v2.0 release. In the following weeks, we will mostly focus on the documentation and tutorials. ## ABP Commercial [ABP Commercial](https://commercial.abp.io/) is a set of professional **modules, tools, themes, and services** built on top of the open-source ABP framework. - It provides [professional modules](https://commercial.abp.io/modules) in addition to the ABP Framework's free & [open source modules](https://docs.abp.io/en/abp/latest/Modules/Index). -- It includes a beautiful a [UI theme](https://commercial.abp.io/themes). -- It provides [ABP Suite](https://commercial.abp.io/tools/suite); A tool to assist your development to make you more productive. It currently can create full-stack CRUD pages in a few seconds by configuring your entity properties. More functionalities will be added over time. +- It includes a beautiful a [UI theme](https://commercial.abp.io/themes) with 5 different styles. +- It provides the [ABP Suite](https://commercial.abp.io/tools/suite); A tool to assist your development to make you more productive. It currently can create full-stack CRUD pages in a few seconds by configuring your entity properties. More functionalities will be added over time. - [Premium support](https://commercial.abp.io/support) for enterprise companies. In addition to these standard set of features, we will provide customer basis services. See the [commercial.abp.io](https://commercial.abp.io/) web site for other details. @@ -91,11 +91,25 @@ In addition to these standard set of features, we will provide customer basis se The ABP Commercial **is not a paid version** of the ABP Framework. You can consider it as **set of additional benefits** for professional companies. You can use it to save your time and develop your product faster. -ABP Framework is open source & free and will always be free! +ABP Framework is **open source & free** and will always be like that! As a principle, we build the main infrastructure as open-source and sell additional pre-built application features, themes, and tools. The main idea similar to the [ASP.NET Boilerplate](https://aspnetboilerplate.com/) & the [ASP.NET Zero](https://aspnetzero.com/) products. -Buying a commercial license saves you significant time and effort and you can focus on your own business, besides you get dedicated and high priority support. Also, you will be supporting the ABP core team since we are spending most of our time to develop, maintain and support the open-source ABP Framework. +Buying a commercial license saves your significant time and effort and you can focus on your own business, besides you get dedicated and high priority support. Also, you will be supporting the ABP core team since we are spending most of our time to develop, maintain and support the open-source ABP Framework. + +With the introduction of the ABP Commercial, now ABP becomes a platform. We call it as the **ABP.IO Platform** which consists of the open source ABP Framework and the ABP Commercial. + +### Demo + +If you are wondering how exactly looks like the ABP Commercial application startup template, you can easily [create a demo](https://commercial.abp.io/demo) and see it in action. The demo includes all the pre-built modules and the theme. + +Here, a screenshot from the IdentityServer management module UI: + +![abp-commercial-demo](abp-commercial-demo.png) + +This is another screenshot from a demo application using the material design style of the theme: + +![lepton-theme-material](lepton-theme-material.png) ### Pricing @@ -105,7 +119,7 @@ You can build **unlimited projects/products**, sell to **unlimited customers**, - **Business license**: Allows downloading the source code of all the modules and the themes. Also, it includes 5 developer licenses by default. You can buy additional developer licenses. - **Enterprise license**: Provides unlimited and private support in addition to the benefits of the business license. -See the [pricing page](https://commercial.abp.io/pricing) for details. In addition to the standard packages, we are also providing custom services and custom licensing. [Contact us](https://commercial.abp.io/contact) if you have further questions. +See the [pricing page](https://commercial.abp.io/pricing) for details. In addition to the standard packages, we are also providing custom services and custom licensing. [Contact us](https://commercial.abp.io/contact) if you have any questions. #### License Comparison @@ -113,11 +127,11 @@ The license price changes based on your developer count, support level and sourc ##### The Source-Code -Team license doesn't include the source-code of the pre-built modules & themes. It uses all these modules as `NuGet` & `NPM` packages. In this way, you can easily get new features and bug fixes by just updating the package dependencies. But you can't access their source-code. So you don't have the possibility to embed a module's source code into your application and freely change the source-code. +Team license doesn't include the source-code of the pre-built modules & themes. It uses all these modules as **NuGet & NPM packages**. In this way, you can easily **get new features and bug fixes** by just updating the package dependencies. But you can't access their source-code. So you don't have the possibility to embed a module's source code into your application and freely change the source-code. -Pre-built modules provide some level of customization and extensibility and allow you to override services, UI parts and so on. We are working on to make them much more customizable and extensible. If you don't need to make major changes in the pre-built modules, the team license will be ideal for you, because it is cheaper and allows you to easily get new features and bug fixes. +Pre-built modules provide some level of **customization** and **extensibility** and allow you to override services, UI parts and so on. We are working on to make them much more customizable and extensible. If you don't need to make major changes in the pre-built modules, the team license will be ideal for you, because it is cheaper and allows you to easily get new features and bug fixes. -Business and Enterprise licenses allow you to download the source-code of any module or the theme when you need it. They also use the same startup template with the team license, so all modules are used as `NuGet` & `NPM` packages. But in case of need, you can remove the package dependencies for a module and embed its source-code into your own solution to completely customize it. In this case, upgrading the module will not be as easy as before when a new version is available. You don't have to upgrade it, surely! But if you want, you should do it yourself using some merge tool or `Git` branch system. +Business and Enterprise licenses allow you to **download the source-code** of any module or the theme when you need it. They also use the same startup template with the team license, so all modules are used as `NuGet` & `NPM` packages by default. But in case of need, you can remove the package dependencies for a module and embed its source-code into your own solution to completely customize it. In this case, upgrading the module will not be as easy as before when a new version is available. You don't have to upgrade it, surely! But if you want, you should do it yourself using some merge tool or Git branch system. #### License Lifetime @@ -129,4 +143,22 @@ However, the following services are covered for one year: - You can not get **updates** of the modules & the themes after one year. You can continue to use the last obtained version. You can even get bug fixes and enhancements for your current major version. - You can use the **ABP Suite** tool for one year. -If you want to continue to get these benefits, you can extend your license period. Renewing price is 20% less than the regular price. \ No newline at end of file +If you want to continue to get these benefits, you can extend your license period. Renewing price is 20% less than the regular price. + +## NDC London 2020 + +Just like the [previous year](https://medium.com/volosoft/impressions-of-ndc-london-2019-f8f391bb7a9c), we are a partner of the famous software development conference: [NDC London](https://ndc-london.com/)! In the previous year, we were there with the [ASP.NET Boilerplate](https://aspnetboilerplate.com/) & [ASP.NET Zero](https://aspnetzero.com/) theme: + +![ndc-london-volosoft](ndc-london-volosoft.png) + +This year, we will be focusing on the **ABP.IO Platform** (The Open Source ABP Framework and the ABP Commercial). Our booth wall will be like that: + +![ndc-london-volosoft](ndc-2020-volosoft-booth-wall.png) + +If you attend to the conference, remember to visit our booth. We would be glad to talk about the ABP platform features, goals and software development in general. + +### Would you like to meet the ABP Team? + +If you are in London and want to have a coffee with us, we will be available at February 1st afternoon. [@hibrahimkalkan](https://twitter.com/hibrahimkalkan) and [@ismcagdas](https://twitter.com/ismcagdas) will be there. + +Just write to info@abp.io if you want to meet :) \ No newline at end of file diff --git a/docs/en/Blog-Posts/2020-01-15 v2_0_Release/abp-commercial-demo.png b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/abp-commercial-demo.png new file mode 100644 index 0000000000..caddce27ab Binary files /dev/null and b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/abp-commercial-demo.png differ diff --git a/docs/en/Blog-Posts/2020-01-15 v2_0_Release/abp-io-abpcommercial-release.png b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/abp-io-abpcommercial-release.png new file mode 100644 index 0000000000..4366ceb986 Binary files /dev/null and b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/abp-io-abpcommercial-release.png differ diff --git a/docs/en/Blog-Posts/2020-01-15 v2_0_Release/lepton-theme-material.png b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/lepton-theme-material.png new file mode 100644 index 0000000000..72cb5c0639 Binary files /dev/null and b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/lepton-theme-material.png differ diff --git a/docs/en/Blog-Posts/2020-01-15 v2_0_Release/ndc-2020-volosoft-booth-wall.png b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/ndc-2020-volosoft-booth-wall.png new file mode 100644 index 0000000000..70fb9d54f7 Binary files /dev/null and b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/ndc-2020-volosoft-booth-wall.png differ diff --git a/docs/en/Blog-Posts/2020-01-15 v2_0_Release/ndc-london-volosoft.png b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/ndc-london-volosoft.png new file mode 100644 index 0000000000..afaed37a7a Binary files /dev/null and b/docs/en/Blog-Posts/2020-01-15 v2_0_Release/ndc-london-volosoft.png differ diff --git a/docs/en/Entities.md b/docs/en/Entities.md index 8ae7cdf235..8e0a039dfd 100644 --- a/docs/en/Entities.md +++ b/docs/en/Entities.md @@ -1,34 +1,27 @@ -## Entities +# Entities Entities are one of the core concepts of DDD (Domain Driven Design). Eric Evans describe it as "*An object that is not fundamentally defined by its attributes, but rather by a thread of continuity and identity*". An entity is generally mapped to a table in a relational database. -### Entity Class +## Entity Class -Entities are derived from `Entity` class as shown below: +Entities are derived from the `Entity` class as shown below: ```C# -public class Person : Entity +public class Book : Entity { public string Name { get; set; } - public DateTime CreationTime { get; set; } - - public Person() - { - CreationTime = DateTime.Now; - } + public float Price { get; set; } } ``` > If you do not want to derive your entity from the base `Entity` class, you can directly implement `IEntity` interface. -`Entity` class just defines an `Id` property with the given primary **key type**, which is `int` in the sample above. It can be other types like `string`, `Guid`, `long` or whatever you need. - -Entity class also overrides the **equality** operator (==) to easily check if two entities are equal (they are equals if they are same entity type and their Ids are equals). +`Entity` class just defines an `Id` property with the given primary **key type**, which is `Guid` in the example above. It can be other types like `string`, `int`, `long` or whatever you need. -#### Entities with Composite Keys +### Entities with Composite Keys Some entities may need to have **composite keys**. In that case, you can derive your entity from the non-generic `Entity` class. Example: @@ -53,31 +46,31 @@ public class UserRole : Entity } ```` -For the example above, the composite key is composed of `UserId` and `RoleId`. For a relational database, it is the composite primary key of the related table. - -Entities with composite keys should implement the `GetKeys()` method as shown above. +For the example above, the composite key is composed of `UserId` and `RoleId`. For a relational database, it is the composite primary key of the related table. Entities with composite keys should implement the `GetKeys()` method as shown above. -Notice that you also need to define keys of the entity in your **object-relational mapping** (ORM) configuration. +> Notice that you also need to define keys of the entity in your **object-relational mapping** (ORM) configuration. See the [Entity Framework Core](Entity-Framework-Core.md) integration document for example. -> Also note that Entities with Composite Primary Keys cannot utilize the `IRepository` interface since it requires a single unique Id property. However, you can always use `IRepository`. See [repositories documentation](Repositories.md) for more. +> Also note that Entities with Composite Primary Keys cannot utilize the `IRepository` interface since it requires a single Id property. However, you can always use `IRepository`. See [repositories documentation](Repositories.md) for more. -### AggregateRoot Class +## AggregateRoot Class "*Aggregate is a pattern in Domain-Driven Design. A DDD aggregate is a cluster of domain objects that can be treated as a single unit. An example may be an order and its line-items, these will be separate objects, but it's useful to treat the order (together with its line items) as a single aggregate.*" (see the [full description](http://martinfowler.com/bliki/DDD_Aggregate.html)) -`AggregateRoot` class extends the `Entity` class. So, it also has an `Id` property by default. +`AggregateRoot` class extends the `Entity` class. So, it also has an `Id` property by default. -> Notice that ABP creates default repositories only for aggregate roots by default. However, it's possible to include all entities. See [repositories documentation](Repositories.md) for more. +> Notice that ABP creates default repositories only for aggregate roots by default. However, it's possible to include all entities. See the [repositories documentation](Repositories.md) for more. -ABP does not force you to use aggregate roots, you can in fact use the `Entity` class as defined before. However, if you want to implement DDD and want to create aggregate root classes, there are some best practices you may want to consider: +ABP does not force you to use aggregate roots, you can in fact use the `Entity` class as defined before. However, if you want to implement the [Domain Driven Design](Domain-Driven-Design.md) and want to create aggregate root classes, there are some best practices you may want to consider: * An aggregate root is responsible to preserve it's own integrity. This is also true for all entities, but aggregate root has responsibility for it's sub entities too. So, the aggregate root must always be in a valid state. * An aggregate root can be referenced by it's Id. Do not reference it by it's navigation property. * An aggregate root is treated as a single unit. It's retrieved and updated as a single unit. It's generally considered as a transaction boundary. * Work with sub-entities over the aggregate root- do not modify them independently. -#### Aggregate Example +See the [entity design best practice guide](Best-Practices/Entities.md) if you want to implement DDD in your application. + +### Aggregate Example This is a full sample of an aggregate root with a related sub-entity collection: @@ -156,6 +149,11 @@ public class OrderLine : Entity { Count = newCount; } + + public override object[] GetKeys() + { + return new Object[] {OrderId, ProductId}; + } } ```` @@ -163,15 +161,80 @@ public class OrderLine : Entity `Order` is an **aggregate root** with `Guid` type `Id` property. It has a collection of `OrderLine` entities. `OrderLine` is another entity with a composite primary key (`OrderId` and ` ProductId`). -While this example may not implement all the best practices of an aggregate root, it still follows good practices: +While this example may not implement all the best practices of an aggregate root, it still follows some good practices: * `Order` has a public constructor that takes **minimal requirements** to construct an `Order` instance. So, it's not possible to create an order without an id and reference number. The **protected/private** constructor is only necessary to **deserialize** the object while reading from a data source. * `OrderLine` constructor is internal, so it is only allowed to be created by the domain layer. It's used inside of the `Order.AddProduct` method. * `Order.AddProduct` implements the business rule to add a product to an order. * All properties have `protected` setters. This is to prevent the entity from arbitrary changes from outside of the entity. For exmple, it would be dangerous to set `TotalItemCount` without adding a new product to the order. It's value is maintained by the `AddProduct` method. -ABP does not force you to apply any DDD rule or patterns. However, it tries to make it possible and easier when you do want to apply them. The documentation also follows the same principle. +ABP Framework does not force you to apply any DDD rule or patterns. However, it tries to make it possible and easier when you do want to apply them. The documentation also follows the same principle. -#### Aggregate Roots with Composite Keys +### Aggregate Roots with Composite Keys While it's not common (and not suggested) for aggregate roots, it is in fact possible to define composite keys in the same way as defined for the mentioned entities above. Use non-generic `AggregateRoot` base class in that case. + +## Base Classes & Interfaces for Audit Properties + +There are some properties like `CreationTime`, `CreatorId`, `LastModificationTime`... which are very common in all applications. ABP Framework provides some interfaces and base classes to **standardize** these properties and also **sets their values automatically**. + +### Auditing Interfaces + +There are a lot of auditing interfaces, so you can implement the one that you need. + +> While you can manually implement these interfaces, you can use **the base classes** defined in the next section to simplify it. + +* `IHasCreationTime` defines the following properties: + * `CreationTime` +* `IMayHaveCreator` defines the following properties: + * `CreatorId` +* `ICreationAuditedObject` inherits from the `IHasCreationTime` and the `IMayHaveCreator`, so it defines the following properties: + * `CreationTime` + * `CreatorId` +* `IHasModificationTime` defines the following properties: + * `LastModificationTime` +* `IModificationAuditedObject` extends the `IHasModificationTime` and adds the `LastModifierId` property. So, it defines the following properties: + * `LastModificationTime` + * `LastModifierId` +* `IAuditedObject` extends the `ICreationAuditedObject` and the `IModificationAuditedObject`, so it defines the following properties: + * `CreationTime` + * `CreatorId` + * `LastModificationTime` + * `LastModifierId` +* `ISoftDelete` (see the [data filtering document](Data-Filtering.md)) defines the following properties: + * `IsDeleted` +* `IHasDeletionTime` extends the `ISoftDelete` and adds the `DeletionTime` property. So, it defines the following properties: + * `IsDeleted` + * `DeletionTime` +* `IDeletionAuditedObject` extends the `IHasDeletionTime` and adds the `DeleterId` property. So, it defines the following properties: + * `IsDeleted` + * `DeletionTime` + * `DeleterId` +* `IFullAuditedObject` inherits from the `IAuditedObject` and the `IDeletionAuditedObject`, so it defines the following properties: + * `CreationTime` + * `CreatorId` + * `LastModificationTime` + * `LastModifierId` + * `IsDeleted` + * `DeletionTime` + * `DeleterId` + +Once you implement any of the interfaces, or derive from a class defined in the next section, ABP Framework automatically manages these properties wherever possible. + +> Implementing `ISoftDelete`, `IDeletionAuditedObject` or `IFullAuditedObject` makes your entity **soft-delete**. See the [data filtering document](Data-Filtering.md) to learn about the soft-delete pattern. + +### Auditing Base Classes + +While you can manually implement any of the interfaces defined above, it is suggested to inherit from the base classes defined here: + +* `CreationAuditedEntity` and `CreationAuditedAggregateRoot` implement the `ICreationAuditedObject` interface. +* `AuditedEntity` and `AuditedAggregateRoot` implement the `IAuditedObject` interface. +* `FullAuditedEntity` and `FullAuditedAggregateRoot` implement the `IFullAuditedObject` interface. + +All these base classes also have non-generic versions to take `AuditedEntity` and `FullAuditedAggregateRoot` to support the composite primary keys. + +All these base classes also have `...WithUser` pairs, like `FullAuditedAggregateRootWithUser` and`FullAuditedAggregateRootWithUser`. This makes possible to add a navigation property to your user entity. However, it is not a good practice to add navigation properties between aggregate roots, so this usage is not suggested (unless you are using an ORM, like EF Core, that well supports this scenario and you really need it - otherwise remember that this approach doesn't work for NoSQL databases like MongoDB where you must truly implement the aggregate pattern). + +## See Also + +* [Best practice guide to design the entities](Best-Practices/Entities.md) \ No newline at end of file diff --git a/docs/en/Modules/Audit-Logging.md b/docs/en/Modules/Audit-Logging.md new file mode 100644 index 0000000000..922f99284b --- /dev/null +++ b/docs/en/Modules/Audit-Logging.md @@ -0,0 +1,7 @@ +# Audit Logging Module + +The Audit Logging Module basically implements the `IAuditingStore` to save the audit log objects to a database. + +> Audit Logging module is already installed and configured for [the startup templates](../Startup-Templates/Index.md). So, most of the times you don't need to manually add this module to your application. + +See [the audit logging system](../Audit-Logging.md) document for more about the audit logging. \ No newline at end of file diff --git a/docs/en/Modules/Index.md b/docs/en/Modules/Index.md index 8616ed2281..6d920877cd 100644 --- a/docs/en/Modules/Index.md +++ b/docs/en/Modules/Index.md @@ -11,16 +11,20 @@ There are **two types of modules.** They don't have any structural difference bu There are some **free and open source** application modules developed and maintained by the ABP community: -* **Account**: Used to make user login/register to the application. -* **Audit Logging**: Used to persist audit logs to a database. -* **Background Jobs**: Used to persist background jobs when using default background job manager. +* **Account**: Provides UI for the account management and allows user to login/register to the application. +* [**Audit Logging**](Audit-Logging.md): Persists audit logs to a database. +* **Background Jobs**: Persist background jobs when using the default background job manager. * **Blogging**: Used to create fancy blogs. ABP's [own blog](https://abp.io/blog/abp/) already using this module. * [**Docs**](Docs.md): Used to create technical documentation pages. ABP's [own documentation](https://docs.abp.io) already using this module. -* **Identity**: Used to manage roles, users and their permissions. +* **Identity**: Manages roles, users and their permissions, based on the Microsoft Identity library. * **IdentityServer**: Integrates to IdentityServer4. * **Permission Management**: Used to persist permissions. * **[Setting Management](Setting-Management.md)**: Used to persist and manage the [settings](../Settings.md). -* **Tenant Management**: Used to manage tenants for a [multi-tenant](../Multi-Tenancy.md) application. -* **Users**: Used to abstract users, so other modules can depend on this instead of the Identity module. +* **Tenant Management**: Manages tenants for a [multi-tenant](../Multi-Tenancy.md) application. +* **Users**: Abstract users, so other modules can depend on this module instead of the Identity module. -Documenting the modules is in the progress. See [this repository](https://github.com/abpframework/abp/tree/master/modules) for source code of all modules. +See [the GitHub repository](https://github.com/abpframework/abp/tree/master/modules) for source code of all modules. + +## Commercial Application Modules + +[ABP Commercial](https://commercial.abp.io/) license provides additional pre-built application modules on top of the ABP framework. See the [module list](https://commercial.abp.io/modules) provided by the ABP Commercial. \ No newline at end of file diff --git a/docs/en/Modules/Setting-Management.md b/docs/en/Modules/Setting-Management.md index c64f1014ca..134e24aed2 100644 --- a/docs/en/Modules/Setting-Management.md +++ b/docs/en/Modules/Setting-Management.md @@ -67,6 +67,8 @@ namespace Demo So, you can get or set a setting value for different setting value providers (Default, Global, User, Tenant... etc). +> Use the `ISettingProvider` instead of the `ISettingManager` if you only need to read the setting values, because it implements caching and supports all deployment scenarios. You can use the `ISettingManager` if you are creating a setting management UI. + ### Setting Cache Setting values are cached using the [distributed cache](../Caching.md) system. Always use the `ISettingManager` to change the setting values which manages the cache for you. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index cf636ca182..6657ac629a 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -105,7 +105,8 @@ "path": "Caching.md" }, { - "text": "Auditing" + "text": "Audit Logging", + "path": "Audit-Logging.md" }, { "text": "Settings", diff --git a/docs/en/images/auditlog-object-diagram.png b/docs/en/images/auditlog-object-diagram.png new file mode 100644 index 0000000000..a7e86a2bb2 Binary files /dev/null and b/docs/en/images/auditlog-object-diagram.png differ diff --git a/docs/zh-Hans/FluentValidation.md b/docs/zh-Hans/FluentValidation.md index 2254e896d4..265a2cc2ca 100644 --- a/docs/zh-Hans/FluentValidation.md +++ b/docs/zh-Hans/FluentValidation.md @@ -1,3 +1,59 @@ # FluentValidation 集成 -TODO \ No newline at end of file +ABP[验证](Validation.md)基础设施是可扩展的. [Volo.Abp.FluentValidation](https://www.nuget.org/packages/Volo.Abp.FluentValidation) NuGet 包扩展了验证系统使其与[FluentValidation](https://fluentvalidation.net/)库一起工作. + +## 安装 + +建议使用[ABP CLI](CLI.md)安装包. + +### 使用ABP CLI + +在项目(.csproj文件)的文件夹中打开命令行窗口并输入以下命令: + +````bash +abp add-package Volo.Abp.FluentValidation +```` + +### 手动安装 + +如果你想手动安装; + +1. 添加 [Volo.Abp.FluentValidation](https://www.nuget.org/packages/Volo.Abp.FluentValidation) NuGet包到你的项目: + + ```` + Install-Package Volo.Abp.FluentValidation + ```` + +2. 添加 `AbpFluentValidationModule` 到你的模块的依赖列表: + +````csharp +[DependsOn( + //...other dependencies + typeof(AbpFluentValidationModule) //Add the FluentValidation module + )] +public class YourModule : AbpModule +{ +} +```` + +## 使用 FluentValidation + +按照 [FluentValidation文档](https://fluentvalidation.net/) 创建验证器类. +例如: + +````csharp +public class CreateUpdateBookDtoValidator : AbstractValidator +{ + public CreateUpdateBookDtoValidator() + { + RuleFor(x => x.Name).Length(3, 10); + RuleFor(x => x.Price).ExclusiveBetween(0.0f, 999.0f); + } +} +```` + +ABP会自动找到这个类并在对象验证时与 `CreateUpdateBookDto` 关联. + +## 另请参阅 + +* [验证系统](Validation.md) \ No newline at end of file diff --git a/framework/src/Volo.Abp.Auditing/Volo/Abp/Auditing/AuditingInterceptorRegistrar.cs b/framework/src/Volo.Abp.Auditing/Volo/Abp/Auditing/AuditingInterceptorRegistrar.cs index 546d54299c..94920fe1be 100644 --- a/framework/src/Volo.Abp.Auditing/Volo/Abp/Auditing/AuditingInterceptorRegistrar.cs +++ b/framework/src/Volo.Abp.Auditing/Volo/Abp/Auditing/AuditingInterceptorRegistrar.cs @@ -32,6 +32,8 @@ namespace Volo.Abp.Auditing //TODO: Move to a better place public static bool ShouldAuditTypeByDefault(Type type) { + //TODO: In an inheritance chain, it would be better to check the attributes on the top class first. + if (type.IsDefined(typeof(AuditedAttribute), true)) { return true; diff --git a/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/HelpCommand.cs b/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/HelpCommand.cs index 060bd91cc7..70d5112e95 100644 --- a/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/HelpCommand.cs +++ b/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/HelpCommand.cs @@ -32,6 +32,13 @@ namespace Volo.Abp.Cli.Commands return Task.CompletedTask; } + if (!AbpCliOptions.Commands.ContainsKey(commandLineArgs.Target)) + { + Logger.LogWarning($"There is no command named {commandLineArgs.Target}."); + Logger.LogInformation(GetUsageInfo()); + return Task.CompletedTask; + } + var commandType = AbpCliOptions.Commands[commandLineArgs.Target]; using (var scope = ServiceScopeFactory.CreateScope()) diff --git a/framework/src/Volo.Abp.Core/Volo/Abp/Modularity/AbpModule.cs b/framework/src/Volo.Abp.Core/Volo/Abp/Modularity/AbpModule.cs index 6153f4be97..f40c6caf12 100644 --- a/framework/src/Volo.Abp.Core/Volo/Abp/Modularity/AbpModule.cs +++ b/framework/src/Volo.Abp.Core/Volo/Abp/Modularity/AbpModule.cs @@ -121,5 +121,17 @@ namespace Volo.Abp.Modularity { ServiceConfigurationContext.Services.PreConfigure(configureOptions); } + + protected void PostConfigure(Action configureOptions) + where TOptions : class + { + ServiceConfigurationContext.Services.PostConfigure(configureOptions); + } + + protected void PostConfigureAll(Action configureOptions) + where TOptions : class + { + ServiceConfigurationContext.Services.PostConfigureAll(configureOptions); + } } } \ No newline at end of file diff --git a/modules/account/src/Volo.Abp.Account.Application.Contracts/Volo/Abp/Account/Localization/Resources/en.json b/modules/account/src/Volo.Abp.Account.Application.Contracts/Volo/Abp/Account/Localization/Resources/en.json index 1f8c0f2eca..ea2d94f5f2 100644 --- a/modules/account/src/Volo.Abp.Account.Application.Contracts/Volo/Abp/Account/Localization/Resources/en.json +++ b/modules/account/src/Volo.Abp.Account.Application.Contracts/Volo/Abp/Account/Localization/Resources/en.json @@ -1,16 +1,16 @@ { "culture": "en", "texts": { - "UserName": "User name", + "UserName": "Username", "EmailAddress": "Email address", - "UserNameOrEmailAddress": "User name or email address", + "UserNameOrEmailAddress": "Username or email address", "Password": "Password", "RememberMe": "Remember me", "UseAnotherServiceToLogin": "Use another service to log in", "UserLockedOutMessage": "The user account has been locked out due to invalid login attempts. Please wait a while and try again.", "InvalidUserNameOrPassword": "Invalid username or password!", "LoginIsNotAllowed": "You are not allowed to login! You need to confirm your email/phone number.", - "SelfRegistrationDisabledMessage": "Self user registration is disabled for this application. Contact to the application administrator to register a new user.", + "SelfRegistrationDisabledMessage": "Self-registration is disabled for this application. Please contact the application administrator to register a new user.", "Login": "Login", "Cancel": "Cancel", "Register": "Register", @@ -23,7 +23,7 @@ "DisplayName:NewPassword": "New password", "DisplayName:NewPasswordConfirm": "Confirm new password", "PasswordChangedMessage": "Your password has been changed successfully.", - "DisplayName:UserName": "User name", + "DisplayName:UserName": "Username", "DisplayName:Email": "Email", "DisplayName:Name": "Name", "DisplayName:Surname": "Surname", @@ -39,6 +39,6 @@ "DisplayName:Abp.Account.IsSelfRegistrationEnabled": "Is self-registration enabled", "Description:Abp.Account.IsSelfRegistrationEnabled": "Whether a user can register the account by him or herself.", "DisplayName:Abp.Account.EnableLocalLogin": "Authenticate with a local account", - "Description:Abp.Account.EnableLocalLogin": "Indicates if Server will allow users to authenticate with a local account." + "Description:Abp.Account.EnableLocalLogin": "Indicates if the server will allow users to authenticate with a local account." } -} \ No newline at end of file +} diff --git a/modules/audit-logging/src/Volo.Abp.AuditLogging.Domain/Volo/Abp/AuditLogging/AuditingStore.cs b/modules/audit-logging/src/Volo.Abp.AuditLogging.Domain/Volo/Abp/AuditLogging/AuditingStore.cs index 6674233de6..50380549dc 100644 --- a/modules/audit-logging/src/Volo.Abp.AuditLogging.Domain/Volo/Abp/AuditLogging/AuditingStore.cs +++ b/modules/audit-logging/src/Volo.Abp.AuditLogging.Domain/Volo/Abp/AuditLogging/AuditingStore.cs @@ -47,6 +47,7 @@ namespace Volo.Abp.AuditLogging } catch (Exception ex) { + Logger.LogWarning("Could not save the audit log object: " + Environment.NewLine + auditInfo.ToString()); Logger.LogException(ex, LogLevel.Error); } } diff --git a/npm/ng-packs/packages/theme-basic/src/lib/constants/styles.ts b/npm/ng-packs/packages/theme-basic/src/lib/constants/styles.ts index cacf326031..be67bece5a 100644 --- a/npm/ng-packs/packages/theme-basic/src/lib/constants/styles.ts +++ b/npm/ng-packs/packages/theme-basic/src/lib/constants/styles.ts @@ -68,4 +68,9 @@ export default ` .ui-table .ui-table-tbody > tr.empty-row > div.empty-row-content { border: 1px solid #c8c8c8; } + +.modal-backdrop { +background-color: rgba(0, 0, 0, 0.6); +} + `; diff --git a/npm/ng-packs/packages/theme-shared/src/lib/components/modal/modal.component.scss b/npm/ng-packs/packages/theme-shared/src/lib/components/modal/modal.component.scss index 023830ceeb..321bf9342d 100644 --- a/npm/ng-packs/packages/theme-shared/src/lib/components/modal/modal.component.scss +++ b/npm/ng-packs/packages/theme-shared/src/lib/components/modal/modal.component.scss @@ -4,7 +4,7 @@ } &-backdrop { - background-color: rgba(0, 0, 0, 0.6); + opacity: 0.8; } &::-webkit-scrollbar {