Merge pull request #15031 from abpframework/EngincanV/integration-services-docs

Document integration services

docs/en/Audit-Logging.md

@@ -40,12 +40,14 @@ Here, a list of the options you can configure:
 * `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.
 * `AlwaysLogOnException` (default: `true`): If you set to true, it always saves the audit log on an exception/error case without checking other options (except `IsEnabled`, which completely disables the audit logging).
+* `IsEnabledForIntegrationService` (default: `false`): Audit Logging is disabled for [integration services](Integration-Services.md) by default. Set this property as `true` to enable it.
 * `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.
 * `DisableLogActionInfo` (default: `false`):If you set to true, Will no longer log `AuditLogActionInfo`.
-* `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. If you don't set, it is set from the `IApplicationInfoAccessor.ApplicationName` value, which is the entry assembly name by default.
+* `ApplicationName`: If multiple applications are saving audit logs into a single database, set this property to your application name, so you can distinguish the logs of different applications. If you don't set, it will set from the `IApplicationInfoAccessor.ApplicationName` value, which is the entry assembly name by default.
 * `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.
+* `AlwaysLogSelectors`: A list of selectors to save the audit logs for the matched criteria. 
 
 ### Entity History Selectors
 

docs/en/Integration-Services.md

@@ -0,0 +1,80 @@
+# Integration Services
+
+The *Integration Service* concept was created to distinguish the [application services](Application-Services.md) that are built for inter-module (or inter-microservice) communication from the application services that are intended to be consumed from a UI or a client application.
+
+The following figure shows a few microservices behind an API Gateway that is consumed by a UI application and 3rd-party client applications:
+
+![integration-services](images/integration-services.png)
+
+HTTP requests coming from out of the API Gateway can be called as *external request*, while the HTTP requests performed between microservices can be considered as *internal requests*. The application services that are designed to respond to these external requests are called as *integration services*, because their purpose is to integrate microservices in the system, rather than respond to user requests.
+
+## Marking an Application Service as Integration Service
+
+Assume that you have an application service named `ProductAppService`, and you want to use that application service as an integration service. In that case, you can use the `[IntegrationService]` attribute on top of the application service class as shown below:
+
+```csharp
+[IntegrationService]
+public class ProductAppService : ApplicationService, IProductAppService
+{
+    // ...
+}
+```
+
+If your application service has an interface, like `IProductService` in this example, you can use it on the service interface:
+
+```csharp
+[IntegrationService]
+public interface IProductAppService : IApplicationService
+{
+    // ...
+}
+```
+
+> If you've used the `[IntegrationService]` on top of your service interface, it is *not needed* to use on the service class too.
+
+That's all. From now, ABP will handle your application service as integration service and implement the followings by convention:
+
+* If you are using the [Auto API Controllers](API/Auto-API-Controllers.md) feature in your application, the URL prefix will be `/integration-api` instead of `/api` for your integration services. Thus, you can distinguish internal and external service communications and take additional actions, such as preventing REST API calls for integration services out of API Gateway.
+* Audit logging is disabled by default for the integration services. See the next section if you want to enable it.
+
+## Configuration
+
+### Enabling/Disabling the Audit Logging
+
+Audit Logging is disabled by default for integration services but it can be enabled by configuring the `AbpAuditingOptions` [options class](Options.md) in the `ConfigureServices` method of your [module class](Module-Development-Basics.md):
+
+```csharp
+Configure<AbpAuditingOptions>(options =>
+{
+    options.IsEnabledForIntegrationService = true;
+});
+```
+
+> Please refer to the [audit logging document](Audit-Logging.md) for other options and details.
+
+### Filtering Auto API Controllers
+
+You can filter integration services (or non-integration services) while creating [Auto API Controllers](API/Auto-API-Controllers.md), using the `ApplicationServiceTypes` option of the `ConventionalControllerSetting` by configuring the `AbpAspNetCoreMvcOptions` as shown below:
+
+```csharp
+Configure<AbpAspNetCoreMvcOptions>(options =>
+{
+    options.ConventionalControllers.Create(
+        typeof(MyApplicationModule).Assembly,
+        conventionalControllerSetting =>
+        {
+            conventionalControllerSetting.ApplicationServiceTypes = 
+                ApplicationServiceTypes.IntegrationServices;
+        });
+});
+```
+
+Tip: You can call the `options.ConventionalControllers.Create` multiple times to configure regular application services and integration services with different options.
+
+> Please refer to the [Auto API Controllers document](API/Auto-API-Controllers.md) for more information about the Auto API Controller system.
+
+## See Also
+
+* [Application Services](Application-Services.md)
+* [Auto API Controllers](API/Auto-API-Controllers.md)
+* [Audit Logging](Audit-Logging.md)

docs/en/docs-nav.json

@@ -604,18 +604,6 @@
     {
       "text": "API",
       "items": [
-        {
-          "text": "Auto API Controllers",
-          "path": "API/Auto-API-Controllers.md"
-        },
-        {
-          "text": "Dynamic C# API Clients",
-          "path": "API/Dynamic-CSharp-API-Clients.md"
-        },
-        {
-          "text": "Static C# API Clients",
-          "path": "API/Static-CSharp-API-Clients.md"
-        },
         {
           "text": "ABP Endpoints",
           "items": [
@@ -629,13 +617,29 @@
             }
           ]
         },
-        {
-          "text": "Swagger Integration",
-          "path": "API/Swagger-Integration.md"
-        },
         {
           "text": "API Versioning",
           "path": "API/API-Versioning.md"
+        },
+        {
+          "text": "Auto API Controllers",
+          "path": "API/Auto-API-Controllers.md"
+        },
+        {
+          "text": "Dynamic C# API Clients",
+          "path": "API/Dynamic-CSharp-API-Clients.md"
+        },
+        {
+          "text": "Integration Services",
+          "path": "Integration-Services.md"
+        },
+        {
+          "text": "Static C# API Clients",
+          "path": "API/Static-CSharp-API-Clients.md"
+        },
+        {
+          "text": "Swagger Integration",
+          "path": "API/Swagger-Integration.md"
         }
       ]
     },