mirror of https://github.com/abpframework/abp.git
maliming
1 year ago
265 changed files with 4509 additions and 2587 deletions
@ -0,0 +1,67 @@ |
|||
# ABP Studio Goes AOT: Faster Startups with Ready-to-Run (R2R) Publishing |
|||
|
|||
We're excited that [ABP Studio](https://abp.io/studio) now supports [Ready-to-Run (R2R) publishing](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) (starting from v0.9.16+), a hybrid form of ahead-of-time (AOT) compilation. This enhancement significantly improves the startup time and overall performance of ABP Studio, making it faster and more performant than ever before. |
|||
|
|||
Let's dive into what R2R publishing is, how it works, and the benefits it brings to ABP Studio. |
|||
|
|||
## What is Ready-to-Run (R2R) Publishing? |
|||
|
|||
Ready-to-Run (R2R) is a form of AOT compilation available in the .NET ecosystem. Unlike traditional just-in-time (JIT) compilation, R2R precompiles parts of your application to native code before deployment. This precompiled code helps reduce the startup time by minimizing the work needed during runtime. |
|||
|
|||
However, R2R isn't a complete AOT compilation. Instead, it's a hybrid approach because it stores both: |
|||
|
|||
* **Native code for precompiled methods** (to improve startup time and performance) |
|||
|
|||
* **Intermediate Language (IL) code** for methods that may need further JIT compilation |
|||
|
|||
This hybrid nature is why R2R binaries are typically larger. For ABP Studio, the storage size increased by ~150 MB with R2R enabled, but the trade-off is well worth it for the performance and startup-time gains. |
|||
|
|||
## How R2R (Ready-to-Run) Improves ABP Studio |
|||
|
|||
### Faster Startup Time 🚀 |
|||
|
|||
One of the biggest advantages of R2R publishing is its impact on startup times. In our local tests, enabling R2R resulted in startup times being **reduced by 2.5x** ⬇️. |
|||
|
|||
This means you can get to work faster, without waiting for the application to being startup from the beginning. Whether you're launching ABP Studio to manage projects, generate code, or deploy applications, the improved responsiveness is noticeable. |
|||
|
|||
### Performance Enhancements 📈 |
|||
|
|||
In addition to faster startups, R2R publishing contributes to overall performance improvements. By precompiling frequently used methods, R2R reduces the workload on the JIT compiler during execution, leading to smoother and more efficient operations. |
|||
|
|||
### Trade-offs: Increased Storage Size 🆙 |
|||
|
|||
With great performance comes a slight trade-off: storage size. R2R binaries include both **native** and **IL code**, which increases the file size. In the case of ABP Studio, the storage footprint increased by ~150 MB. However, the substantial improvements in speed and responsiveness make this a worthwhile investment. |
|||
|
|||
## How to Enable R2R Publishing in Your Applications? |
|||
|
|||
If you're developing applications and want to benefit from R2R, here's a quick guide on how to enable it in your .NET projects: |
|||
|
|||
1. You can add the following configuration to your final project's `.csproj` file: |
|||
|
|||
```xml |
|||
<PropertyGroup> |
|||
<PublishReadyToRun>true</PublishReadyToRun> |
|||
</PropertyGroup> |
|||
``` |
|||
|
|||
2. Then, publish your application with the `dotnet publish` command: |
|||
|
|||
```bash |
|||
dotnet publish -c Release |
|||
``` |
|||
|
|||
Alternatively, you can specify the _PublishReadyToRun_ flag directly to the `dotnet publish` command as follows: |
|||
|
|||
```bash |
|||
dotnet publish -c Release -r win-x64 -p:PublishReadyToRun=true |
|||
``` |
|||
|
|||
That's it! Your application will now include precompiled native code for faster startup and great performance benefits. |
|||
|
|||
> Please refer to the [official documentation](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) before publishing your application with R2R. |
|||
|
|||
## Conclusion |
|||
|
|||
As ABP team, we're always looking for ways to improve the developer experience. By adopting **Ready-to-Run (R2R) publishing** for ABP Studio, we're aiming to deliver a faster and more efficient tool for your development needs. |
|||
|
|||
Stay tuned for more updates and enhancements as we continue to optimize ABP Studio and please provide us with your invaluable feedback. |
|||
@ -0,0 +1,234 @@ |
|||
# The new Unit Test structure in ABP application |
|||
|
|||
A typical ABP modular project usually consists of three main projects: `Application`, `Domain`, and `EntityFrameworkCore/MongoDB`. In these projects, we may provide many services that require unit testing. |
|||
|
|||
Using abstract unit test classes involves first writing tests in the `Application` and `Domain` layers that are independent of the storage technology, ensuring the correctness of core business logic. These abstract tests are then implemented in `EntityFrameworkCore` or `MongoDB`. The benefits of this approach include: |
|||
|
|||
1. **Reduced Coupling**: Core logic tests do not depend on specific storage technologies, so switching databases does not require rewriting test code. |
|||
2. **Better Isolation**: Focuses on verifying business logic correctness, avoiding interference from database operations. |
|||
3. **Increased Reusability**: The same abstract tests can be reused with different storage implementations. |
|||
4. **Easier Maintenance and Extensibility**: Different storage implementations can be extended independently without breaking existing tests. |
|||
5. **Faster and More Reliable Tests**: Reduces dependency on databases, making tests faster and more stable. |
|||
|
|||
## How to migrate old unit tests to the new unit test structure |
|||
|
|||
Assume our project name is `MyCompanyName.MyProjectName`. |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.Application.Tests` project: |
|||
|
|||
1. Remove the `MyCompanyName.MyProjectName.Application.Tests` project's `MyProjectNameApplicationCollection` class. |
|||
2. Modify the `MyCompanyName.MyProjectName.Application.Tests` project's `MyProjectNameApplicationTestBase` class. |
|||
|
|||
```csharp |
|||
public abstract class MyProjectNameApplicationTestBase<TStartupModule> : MyProjectNameTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
3. Modify the `MyCompanyName.MyProjectName.Application.Tests` project's unit test classes to become abstract unit test classes, such as: `SampleAppServiceTests`. |
|||
|
|||
```csharp |
|||
public abstract class SampleAppServiceTests<TStartupModule> : MyProjectNameApplicationTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
[Fact] |
|||
public async Task Initial_Data_Should_Contain_Admin_User() |
|||
{ |
|||
//... |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.Domain.Tests` project: |
|||
|
|||
1. Remove the `MyCompanyName.MyProjectName.Domain.Tests` project's `MyProjectNameDomainCollection` class. |
|||
2. Modify the `MyCompanyName.MyProjectName.Domain.Tests` project's `MyProjectNameDomainTestBase` class. |
|||
|
|||
```csharp |
|||
public abstract class MyProjectNameDomainTestBase<TStartupModule> : MyProjectNameTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
3. Modify the `MyCompanyName.MyProjectName.Domain.Tests` project's unit test classes to become abstract unit test classes, such as: `SampleDomainTests`. |
|||
|
|||
```csharp |
|||
public abstract class SampleDomainTests<TStartupModule> : MyProjectNameDomainTestBase<TStartupModule> |
|||
where TStartupModule : IAbpModule |
|||
{ |
|||
[Fact] |
|||
public async Task Should_Set_Email_Of_A_User() |
|||
{ |
|||
//... |
|||
} |
|||
} |
|||
``` |
|||
|
|||
4. Modify the `MyCompanyName.MyProjectName.Domain.Tests` project's `csproj` and module class. Remove references to `EntityFrameworkCore/MongoDB`. |
|||
|
|||
`MyCompanyName.MyProjectName.Domain.Tests.csproj`: |
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.Domain\MyCompanyName.MyProjectName.Domain.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.TestBase\MyCompanyName.MyProjectName.TestBase.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
|
|||
``` |
|||
|
|||
`MyProjectNameDomainTestModule.cs`: |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(MyProjectNameDomainModule), |
|||
typeof(MyProjectNameTestBaseModule) |
|||
)] |
|||
public class MyProjectNameDomainTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.EntityFrameworkCore.Tests` project: |
|||
|
|||
Here, we need to create implementation classes for all abstract unit tests. |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class EfCoreSampleAppServiceTests : SampleAppServiceTests<MyProjectNameEntityFrameworkCoreTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class EfCoreSampleDomainTests : SampleDomainTests<MyProjectNameEntityFrameworkCoreTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
We also need to modify the project's dependencies and module class, which should directly or indirectly reference the `Application` and `Domain` test projects. |
|||
|
|||
`MyCompanyName.MyProjectName.EntityFrameworkCore.Tests.csproj`: |
|||
|
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.EntityFrameworkCore\MyCompanyName.MyProjectName.EntityFrameworkCore.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" /> |
|||
<ProjectReference Include="..\..\..\..\..\framework\src\Volo.Abp.EntityFrameworkCore.Sqlite\Volo.Abp.EntityFrameworkCore.Sqlite.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
``` |
|||
|
|||
`MyProjectNameEntityFrameworkCoreTestModule.cs`: |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(MyProjectNameApplicationTestModule), |
|||
typeof(MyProjectNameEntityFrameworkCoreModule), |
|||
typeof(AbpEntityFrameworkCoreSqliteModule) |
|||
)] |
|||
public class MyProjectNameEntityFrameworkCoreTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.MongoDB.Tests` project (skip this step if not using MongoDB): |
|||
|
|||
Like the `EntityFrameworkCore` project, we need to create implementation classes for all abstract unit tests and modify the project's dependencies and module class. |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class MongoDBSampleAppServiceTests : SampleAppServiceTests<MyProjectNameMongoDbTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
```csharp |
|||
[Collection(MyProjectNameTestConsts.CollectionDefinitionName)] |
|||
public class MongoDBSampleDomainTests : SampleDomainTests<MyProjectNameMongoDbTestModule> |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.MongoDB\MyCompanyName.MyProjectName.MongoDB.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
``` |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(MyProjectNameApplicationTestModule), |
|||
typeof(MyProjectNameMongoDbModule) |
|||
)] |
|||
public class MyProjectNameMongoDbTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
### Changes to the `MyCompanyName.MyProjectName.Web.Tests` project: |
|||
|
|||
We need to reference the `EntityFrameworkCore/MongoDB` test projects in this test project. |
|||
|
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
//... |
|||
|
|||
<ItemGroup> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.Application.Tests\MyCompanyName.MyProjectName.Application.Tests.csproj" /> |
|||
<ProjectReference Include="..\..\src\MyCompanyName.MyProjectName.Web\MyCompanyName.MyProjectName.Web.csproj" /> |
|||
<ProjectReference Include="..\..\..\..\..\framework\src\Volo.Abp.AspNetCore.TestBase\Volo.Abp.AspNetCore.TestBase.csproj" /> |
|||
<ProjectReference Include="..\MyCompanyName.MyProjectName.EntityFrameworkCore.Tests\MyCompanyName.MyProjectName.EntityFrameworkCore.Tests.csproj" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
``` |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(AbpAspNetCoreTestBaseModule), |
|||
typeof(MyProjectNameWebModule), |
|||
typeof(MyProjectNameApplicationTestModule), |
|||
typeof(MyProjectNameEntityFrameworkCoreTestModule) |
|||
)] |
|||
public class MyProjectNameWebTestModule : AbpModule |
|||
{ |
|||
//... |
|||
} |
|||
``` |
|||
|
|||
We no longer need the `MyProjectNameWebCollection` class in this project. Please delete it and use `[Collection(MyProjectNameTestConsts.CollectionDefinitionName)]` instead. |
|||
|
|||
## Conclusion |
|||
|
|||
This is our new unit test structure. Decoupling unit tests from storage technologies ensures the independence of business logic and allows easy switching between storage implementations. Abstract unit test classes improve test reusability, maintainability, and efficiency, reducing refactoring costs and providing flexibility for future tech updates. |
|||
|
|||
## References |
|||
|
|||
- [Unit Test](https://abp.io/docs/latest/testing/unit-tests) |
|||
- [Abstract all db-related unit tests](https://github.com/abpframework/abp/pull/17880) |
|||
|
After Width: | Height: | Size: 82 KiB |
@ -0,0 +1,465 @@ |
|||
# Layered Application Solution Template |
|||
|
|||
This template provides a layered application structure based on the [Domain Driven Design](../../framework/architecture/domain-driven-design) (DDD) practices. |
|||
|
|||
## Getting Started |
|||
|
|||
This document explains **the solution structure** and projects in details. If you want to start quickly, follow the guides below: |
|||
|
|||
* [The getting started document](../../get-started/layered-web-application.md) explains how to create a new application in a few minutes. |
|||
* [The application development tutorial](../../tutorials/book-store/part-01.md) explains step by step application development. |
|||
|
|||
## How to Start With? |
|||
|
|||
You can use the [ABP CLI](../../cli) to create a new project using this startup template. Alternatively, you can generate a CLI command from the [Get Started](https://abp.io/get-started) page. CLI approach is used here. |
|||
|
|||
First, install the ABP CLI if you haven't installed it before: |
|||
|
|||
````bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
```` |
|||
|
|||
Then use the `abp new` command in an empty folder to create a new solution: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -t app |
|||
```` |
|||
|
|||
* `Acme.BookStore` is the solution name, like *YourCompany.YourProduct*. You can use single-level, two-level or three-level naming. |
|||
* This example specified the template name (`-t` or `--template` option). However, `app` is already the default template if you didn't specify it. |
|||
|
|||
### Specify the UI Framework |
|||
|
|||
This template provides multiple UI frameworks: |
|||
|
|||
* `mvc`: ASP.NET Core MVC UI with Razor Pages (default) |
|||
* `blazor`: Blazor UI |
|||
* `blazor-server`: Blazor Server UI |
|||
* `angular`: Angular UI |
|||
|
|||
Use the `-u` or `--ui` option to specify the UI framework: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -u angular |
|||
```` |
|||
|
|||
### Specify the Database Provider |
|||
|
|||
This template supports the following database providers: |
|||
|
|||
- `ef`: Entity Framework Core (default) |
|||
- `mongodb`: MongoDB |
|||
|
|||
Use `-d` (or `--database-provider`) option to specify the database provider: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -d mongodb |
|||
```` |
|||
|
|||
### Specify the Mobile Application Framework |
|||
|
|||
This template supports the following mobile application frameworks: |
|||
|
|||
- `react-native`: React Native (*Available for* ***Team*** *or higher licenses*) |
|||
|
|||
Use the `-m` (or `--mobile`) option to specify the mobile application framework: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -m react-native |
|||
```` |
|||
|
|||
* [The getting started document](../../get-started/layered-web-application.md) explains how to create a new application with this startup template. |
|||
* [The application development tutorial](../../tutorials/book-store/part-01.md) explains step by step application development with this startup template. |
|||
|
|||
## Solution Structure |
|||
|
|||
Based on the options you've specified, you will get a slightly different solution structure. |
|||
|
|||
### Default Structure |
|||
|
|||
If you don't specify any additional options, you will have a solution as shown below: |
|||
|
|||
 |
|||
|
|||
Projects are organized in `src` and `test` folders. `src` folder contains the actual application which is layered based on [DDD](../../framework/architecture/domain-driven-design) principles as mentioned before. |
|||
|
|||
The diagram below shows the layers & project dependencies of the application: |
|||
|
|||
 |
|||
|
|||
Each section below will explain the related project & its dependencies. |
|||
|
|||
#### .Domain.Shared Project |
|||
|
|||
This project contains constants, enums and other objects these are actually a part of the domain layer, but needed to be used by all layers/projects in the solution. |
|||
|
|||
A `BookType` enum and a `BookConsts` class (which may have some constant fields for the `Book` entity, like `MaxNameLength`) are good candidates for this project. |
|||
|
|||
* This project has no dependency on other projects in the solution. All other projects depend on this one directly or indirectly. |
|||
|
|||
#### .Domain Project |
|||
|
|||
This is the domain layer of the solution. It mainly contains [entities, aggregate roots](../../framework/architecture/domain-driven-design/entities.md), [domain services](../../framework/architecture/domain-driven-design/domain-services.md), [value objects](../../framework/architecture/domain-driven-design/value-objects.md), [repository interfaces](../../framework/architecture/domain-driven-design/repositories.md) and other domain objects. |
|||
|
|||
A `Book` entity, a `BookManager` domain service and an `IBookRepository` interface are good candidates for this project. |
|||
|
|||
* Depends on the `.Domain.Shared` because it uses constants, enums and other objects defined in that project. |
|||
|
|||
#### .Application.Contracts Project |
|||
|
|||
This project mainly contains [application service](../../framework/architecture/domain-driven-design/application-services.md) **interfaces** and [Data Transfer Objects](../../framework/architecture/domain-driven-design/data-transfer-objects.md) (DTO) of the application layer. It exists to separate the interface & implementation of the application layer. In this way, the interface project can be shared to the clients as a contract package. |
|||
|
|||
An `IBookAppService` interface and a `BookCreationDto` class are good candidates for this project. |
|||
|
|||
* Depends on the `.Domain.Shared` because it may use constants, enums and other shared objects of this project in the application service interfaces and DTOs. |
|||
|
|||
#### .Application Project |
|||
|
|||
This project contains the [application service](../../framework/architecture/domain-driven-design/application-services.md) **implementations** of the interfaces defined in the `.Application.Contracts` project. |
|||
|
|||
A `BookAppService` class is a good candidate for this project. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to implement the interfaces and use the DTOs. |
|||
* Depends on the `.Domain` project to be able to use domain objects (entities, repository interfaces... etc.) to perform the application logic. |
|||
|
|||
#### .EntityFrameworkCore Project |
|||
|
|||
This is the integration project for the EF Core. It defines the `DbContext` and implements repository interfaces defined in the `.Domain` project. |
|||
|
|||
* Depends on the `.Domain` project to be able to reference to entities and repository interfaces. |
|||
|
|||
> This project is available only if you are using EF Core as the database provider. If you select another database provider, its name will be different. |
|||
|
|||
#### .DbMigrator Project |
|||
|
|||
This is a console application that simplifies the execution of database migrations on development and production environments. When you run this application, it: |
|||
|
|||
* Creates the database if necessary. |
|||
* Applies the pending database migrations. |
|||
* Seeds initial data if needed. |
|||
|
|||
> This project has its own `appsettings.json` file. So, if you want to change the database connection string, remember to change this file too. |
|||
|
|||
Especially, seeding initial data is important at this point. ABP has a modular data seed infrastructure. See [its documentation](../../framework/infrastructure/data-seeding.md) for more about the data seeding. |
|||
|
|||
While creating database & applying migrations seem only necessary for relational databases, this project comes even if you choose a NoSQL database provider (like MongoDB). In that case, it still seeds the initial data which is necessary for the application. |
|||
|
|||
* Depends on the `.EntityFrameworkCore` project (for EF Core) since it needs to access to the migrations. |
|||
* Depends on the `.Application.Contracts` project to be able to access permission definitions, because the initial data seeder grants all permissions to the admin role by default. |
|||
|
|||
#### .HttpApi Project |
|||
|
|||
This project is used to define your API Controllers. |
|||
|
|||
Most of the time you don't need to manually define API Controllers since ABP's [Auto API Controllers](../../framework/api-development/auto-controllers.md) feature creates them automagically based on your application layer. However, in case of you need to write API controllers, this is the best place to do it. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to inject the application service interfaces. |
|||
|
|||
#### .HttpApi.Client Project |
|||
|
|||
This is a project that defines C# client proxies to use the HTTP APIs of the solution. You can share this library to 3rd-party clients, so they can easily consume your HTTP APIs in their Dotnet applications (For other types of applications, they can still use your APIs, either manually or using a tool in their own platform) |
|||
|
|||
Most of the time you don't need to manually create C# client proxies, thanks to ABP's [Dynamic C# API Clients](../../framework/api-development/dynamic-csharp-clients.md) feature. |
|||
|
|||
`.HttpApi.Client.ConsoleTestApp` project is a console application created to demonstrate the usage of the client proxies. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to share the same application service interfaces and DTOs with the remote service. |
|||
|
|||
> You can delete this project & dependencies if you don't need to create C# client proxies for your APIs. |
|||
|
|||
#### .Web Project |
|||
|
|||
This project contains the User Interface (UI) of the application if you are using ASP.NET Core MVC UI. It contains Razor pages, JavaScript files, CSS files, images and so on... |
|||
|
|||
This project contains the main `appsettings.json` file that contains the connection string and other configurations of the application. |
|||
|
|||
* Depends on the `.HttpApi` project since the UI layer needs to use APIs and the application service interfaces of the solution. |
|||
|
|||
> If you check the source code of the `.Web.csproj` file, you will see the references to the `.Application` and the `.EntityFrameworkCore` projects. |
|||
> |
|||
> These references are actually not needed while coding your UI layer, because the UI layer normally doesn't depend on the EF Core or the Application layer's implementation. These startup templates are ready for tiered deployment, where the API layer is hosted on a separate server than the UI layer. |
|||
> |
|||
> However, if you don't choose the `--tiered` option, these references will be in the .Web project to be able to host the Web, API and application layers in a single application endpoint. |
|||
> |
|||
> This gives you the ability to use domain entities & repositories in your presentation layer. However, this is considered as a bad practice according to DDD. |
|||
|
|||
#### Test Projects |
|||
|
|||
The solution has multiple test projects, one for each layer: |
|||
|
|||
* `.Domain.Tests` is used to test the domain layer. |
|||
* `.Application.Tests` is used to test the application layer. |
|||
* `.EntityFrameworkCore.Tests` is used to test EF Core configuration and custom repositories. |
|||
* `.Web.Tests` is used to test the UI (if you are using ASP.NET Core MVC UI). |
|||
* `.TestBase` is a base (shared) project for all tests. |
|||
|
|||
In addition, `.HttpApi.Client.ConsoleTestApp` is a console application (not an automated test project) which demonstrate the usage of HTTP APIs from a .NET application. |
|||
|
|||
Test projects are prepared for integration testing; |
|||
|
|||
* It is fully integrated into the ABP and all services in your application. |
|||
* It uses SQLite in-memory database for EF Core. For MongoDB, it uses the [EphemeralMongo](https://github.com/asimmon/ephemeral-mongo) library. |
|||
* Authorization is disabled, so any application service can be easily used in tests. |
|||
|
|||
You can still create unit tests for your classes which will be harder to write (because you will need to prepare mock/fake objects), but faster to run (because it only tests a single class and skips all the initialization processes). |
|||
|
|||
#### How to Run? |
|||
|
|||
Set `.Web` as the startup project and run the application. The default username is `admin` and the password is `1q2w3E*`. |
|||
|
|||
See [Getting Started With the ASP.NET Core MVC Template](../../get-started/layered-web-application.md) for more information. |
|||
|
|||
### Tiered Structure |
|||
|
|||
If you have selected the ASP.NET Core UI and specified the `--tiered` option, the solution created will be a tiered solution. The purpose of the tiered structure is to be able to **deploy Web applications and HTTP API to different servers**: |
|||
|
|||
 |
|||
|
|||
* Browser runs your UI by executing HTML, CSS & JavaScript. |
|||
* Web servers host static UI files (CSS, JavaScript, image... etc.) & dynamic components (e.g. Razor pages). It performs HTTP requests to the API server to execute the business logic of the application. |
|||
* The API Server hosts the HTTP APIs which then use the application & domain layers of the application to perform the business logic. |
|||
* Finally, database server hosts your database. |
|||
|
|||
So, the resulting solution allows a 4-tiered deployment, by comparing to 3-tiered deployment of the default structure explained before. |
|||
|
|||
> Unless you actually need such a 4-tiered deployment, it's suggested to go with the default structure which is simpler to develop, deploy and maintain. |
|||
|
|||
The solution structure is shown below: |
|||
|
|||
 |
|||
|
|||
As different from the default structure, two new projects come into play: `.AuthServer` & `.HttpApi.Host`. |
|||
|
|||
#### .AuthServer Project |
|||
|
|||
This project is used as an authentication server for other projects. `.Web` project uses OpenId Connect Authentication to get identity and access tokens for the current user from the AuthServer. Then uses the access token to call the HTTP API server. HTTP API server uses bearer token authentication to obtain claims from the access token to authorize the current user. |
|||
|
|||
 |
|||
|
|||
ABP uses the [OpenIddict Module](../../modules/openiddict.md) that uses the open-source [OpenIddict-core](https://github.com/openiddict/openiddict-core) library for the authentication between applications. See [OpenIddict documentation](https://documentation.openiddict.com/) for details about the OpenIddict and OpenID Connect protocol. |
|||
|
|||
It has its own `appsettings.json` that contains database connection and other configurations. |
|||
|
|||
#### .HttpApi.Host Project |
|||
|
|||
This project is an application that hosts the API of the solution. It has its own `appsettings.json` that contains database connection and other configurations. |
|||
|
|||
#### .Web Project |
|||
|
|||
Just like the default structure, this project contains the User Interface (UI) of the application. It contains razor pages, JavaScript files, style files, images and so on... |
|||
|
|||
This project contains an `appsettings.json` file, but this time it does not have a connection string because it never connects to the database. Instead, it mainly contains the endpoint of the remote API server and the authentication server. |
|||
|
|||
#### Pre-requirements |
|||
|
|||
* [Redis](https://redis.io/): The applications use Redis as a distributed cache. So, you need to have Redis installed & running. |
|||
|
|||
#### How to Run? |
|||
|
|||
You should run the application with the given order: |
|||
|
|||
* First, run the `.AuthServer` since other applications depend on it. |
|||
* Then run the `.HttpApi.Host` since it is used by the `.Web` application. |
|||
* Finally, you can run the `.Web` project and login to the application (using `admin` as the username and `1q2w3E*` as the password). |
|||
|
|||
### Blazor UI |
|||
If you choose `Blazor` as the UI Framework (using the `-u blazor` or `-u blazor-server` option), the solution will have a project named `.Blazor`. This project contains the Blazor UI application. According to your choice, it will be a Blazor WebAssembly or Blazor Server application. If Blazor WebAssembly is selected, the solution will also have a `.HttpApi.Host`. This project is an ASP.NET Core application that hosts the backend application for the Blazor single page application. |
|||
|
|||
#### .Blazor Project (Server) |
|||
The Blazor Server project is similar to the ASP.NET Core MVC project. It replaces `.Web` project with `.Blazor` in the solution structure above. It has the same folder structure and the same application flow. Since it's an ASP.NET Core application, it can contain **.cshtml** files and **.razor** components at the same time. If routing matches a razor component, the Blazor UI will be used. Otherwise, the request will be handled by the MVC framework. |
|||
|
|||
 |
|||
|
|||
#### .Blazor Project (WebAssembly) |
|||
The Blazor WebAssembly project is a single page application that runs on the browser. You'll see it as `.Blazor` project in the solution. It uses the `.HttpApi.Host` project to communicate with the backend. It can't be used without the backend application. It contains only **.razor** components. It's a pure client-side application. It doesn't have any server-side code. Everything in this layer will be for the client side. |
|||
|
|||
 |
|||
|
|||
### Angular UI |
|||
|
|||
If you choose `Angular` as the UI framework (using the `-u angular` option), the solution is being separated into two folders: |
|||
|
|||
* `angular` folder contains the Angular UI application, the client-side code. |
|||
* `aspnet-core` folder contains the ASP.NET Core solution, the server-side code. |
|||
|
|||
The server-side is similar to the solution described above. `*.HttpApi.Host` project serves the API, so the `Angular` application consumes it. |
|||
|
|||
Angular application folder structure looks like below: |
|||
|
|||
 |
|||
|
|||
|
|||
Each of ABP modules is an NPM package. Some ABP modules are added as a dependency in `package.json`. These modules install with their dependencies. To see all ABP packages, you can run the following command in the `angular` folder: |
|||
|
|||
```bash |
|||
yarn list --pattern abp |
|||
``` |
|||
|
|||
Angular application module structure: |
|||
|
|||
 |
|||
|
|||
#### AppModule |
|||
|
|||
`AppModule` is the root module of the application. Some of the ABP modules and some essential modules are imported to `AppModule`. |
|||
|
|||
ABP Config modules have also been imported to `AppModule` for initial requirements of the lazy-loadable ABP modules. |
|||
|
|||
#### AppRoutingModule |
|||
|
|||
There are lazy-loadable ABP modules in the `AppRoutingModule` as routes. |
|||
|
|||
> Paths of ABP Modules should not be changed. |
|||
|
|||
You should add `routes` property in the `data` object to add a link on the menu to redirect to your custom pages. |
|||
|
|||
```js |
|||
{ |
|||
path: 'dashboard', |
|||
loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule), |
|||
canActivate: [authGuard, permissionGuard], |
|||
data: { |
|||
routes: { |
|||
name: 'ProjectName::Menu:Dashboard', |
|||
order: 2, |
|||
iconClass: 'fa fa-dashboard', |
|||
requiredPolicy: 'ProjectName.Dashboard.Host' |
|||
} as ABP.Route |
|||
} |
|||
} |
|||
``` |
|||
In the above example; |
|||
* If the user is not logged in, authGuard blocks access and redirects to the login page. |
|||
* permissionGuard checks the user's permission with the `requiredPolicy` property of the `routes` object. If the user is not authorized to access the page, the 403 page appears. |
|||
* The `name` property of `routes` is the menu link label. A localization key can be defined. |
|||
* The `iconClass` property of the `routes` object is the menu link icon class. |
|||
* The `requiredPolicy` property of the `routes` object is the required policy key to access the page. |
|||
|
|||
After the above `routes` definition, if the user is authorized, the dashboard link will appear on the menu. |
|||
|
|||
#### Shared Module |
|||
|
|||
The modules that may be required for all modules have been imported to the `SharedModule`. You should import `SharedModule` to all modules. |
|||
|
|||
See the [Sharing Modules](https://angular.io/guide/sharing-ngmodules) document. |
|||
|
|||
#### Environments |
|||
|
|||
The files under the `src/environments` folder have the essential configuration of the application. |
|||
|
|||
#### Home Module |
|||
|
|||
Home module is an example lazy-loadable module that loads on the root address of the application. |
|||
|
|||
#### Styles |
|||
|
|||
The required style files are added to the `styles` array in `angular.json`. `AppComponent` loads some style files lazily via `LazyLoadService` after the main bundle is loaded to shorten the first rendering time. |
|||
|
|||
#### Testing |
|||
|
|||
You should create your tests in the same folder as the file you want to test. |
|||
|
|||
See the [testing document](https://angular.io/guide/testing). |
|||
|
|||
#### Depended Packages |
|||
|
|||
* [NG Bootstrap](https://ng-bootstrap.github.io/) is used as UI component library. |
|||
* [NGXS](https://www.ngxs.io/) is used as state management library. |
|||
* [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc) is used to support for OAuth 2 and OpenId Connect (OIDC). |
|||
* [Chart.js](https://www.chartjs.org/) is used to create widgets. |
|||
* [ngx-validate](https://github.com/ng-turkey/ngx-validate) is used for dynamic validation of reactive forms. |
|||
|
|||
### React Native |
|||
|
|||
If the `-m react-native` option is specified in the new project command, the solution includes the [React Native](https://reactnative.dev/) application in the `react-native` folder. |
|||
|
|||
The server-side is similar to the solution described above. `*.HttpApi.Host` project serves the API, so the React Native application consumes it. |
|||
|
|||
The React Native application was generated with [Expo](https://expo.io/). Expo is a set of tools built around React Native to help you quickly start an app and, while it has many features. |
|||
|
|||
React Native application folder structure as like below: |
|||
|
|||
 |
|||
|
|||
* `App.js` is the bootstrap component of the application. |
|||
* `Environment.js` file has the essential configuration of the application. `prod` and `dev` configurations are defined in this file. |
|||
* [Contexts](https://reactjs.org/docs/context.html) are created in the `src/contexts` folder. |
|||
* [Higher order components](https://reactjs.org/docs/higher-order-components.html) are created in the `src/hocs` folder. |
|||
* [Custom hooks](https://reactjs.org/docs/hooks-custom.html#extracting-a-custom-hook) are created in `src/hooks`. |
|||
* [Axios interceptors](https://github.com/axios/axios#interceptors) are created in the `src/interceptors` folder. |
|||
* Utility functions are exported from `src/utils` folder. |
|||
|
|||
#### Components |
|||
|
|||
Components that can be used on all screens are created in the `src/components` folder. All components have been created as a function that is able to use [hooks](https://reactjs.org/docs/hooks-intro.html). |
|||
|
|||
#### Screens |
|||
|
|||
 |
|||
|
|||
Screens are created by creating folders that separate their names in the `src/screens` folder. Certain parts of some screens can be split into components. |
|||
|
|||
Each screen is used in a navigator in the `src/navigators` folder. |
|||
|
|||
#### Navigation |
|||
|
|||
[React Navigation](https://reactnavigation.org/) is used as a navigation library. Navigators are created in the `src/navigators`. A [drawer](https://reactnavigation.org/docs/drawer-based-navigation/) navigator and several [stack](https://reactnavigation.org/docs/hello-react-navigation/#installing-the-stack-navigator-library) navigators have been created in this folder. See the [above diagram](#screens) for the navigation structure. |
|||
|
|||
#### State Management |
|||
|
|||
[Redux](https://redux.js.org/) is used as a state management library. [Redux Toolkit](https://redux-toolkit.js.org/) library is used as a toolset for efficient Redux development. |
|||
|
|||
Actions, reducers, sagas and selectors are created in the `src/store` folder. Store folder is as below: |
|||
|
|||
 |
|||
|
|||
* [**Store**](https://redux.js.org/basics/store) is defined in the `src/store/index.js` file. |
|||
* [**Actions**](https://redux.js.org/basics/actions/) are payloads of information that send data from your application to your store. |
|||
* [**Reducers**](https://redux.js.org/basics/reducers) specify how the application's state changes in response to actions sent to the store. |
|||
* [**Redux-Saga**](https://redux-saga.js.org/) is a library that aims to make application side effects (i.e. asynchronous things like data fetching and impure things like accessing the browser cache) easier to manage. Sagas are created in the `src/store/sagas` folder. |
|||
* [**Reselect**](https://github.com/reduxjs/reselect) library is used to create memoized selectors. Selectors are created in the `src/store/selectors` folder. |
|||
|
|||
#### APIs |
|||
|
|||
[Axios](https://github.com/axios/axios) is used as an HTTP client library. An Axios instance has exported from `src/api/API.js` file to make HTTP calls with the same config. `src/api` folder also has the API files that have been created for API calls. |
|||
|
|||
#### Theming |
|||
|
|||
[Native Base](https://nativebase.io/) is used as UI components library. Native Base components can customize easily. See the [Native Base customize](https://docs.nativebase.io/customizing-components) documentation. We followed the same way. |
|||
|
|||
* Native Base theme variables are in the `src/theme/variables` folder. |
|||
* Native Base component styles are in the `src/theme/components` folder. These files have been generated with Native Base's `ejectTheme` script. |
|||
* Styles of components override with the files under the `src/theme/overrides` folder. |
|||
|
|||
#### Testing |
|||
|
|||
Unit tests will be created. |
|||
|
|||
See the [Testing Overview](https://reactjs.org/docs/testing.html) document. |
|||
|
|||
#### Depended Libraries |
|||
|
|||
* [Native Base](https://nativebase.io/) is used as UI components library. |
|||
* [React Navigation](https://reactnavigation.org/) is used as navigation library. |
|||
* [Axios](https://github.com/axios/axios) is used as an HTTP client library. |
|||
* [Redux](https://redux.js.org/) is used as state management library. |
|||
* [Redux Toolkit](https://redux-toolkit.js.org/) library is used as a toolset for efficient Redux development. |
|||
* [Redux-Saga](https://redux-saga.js.org/) is used to manage asynchronous processes. |
|||
* [Redux Persist](https://github.com/rt2zz/redux-persist) is used as state persistence. |
|||
* [Reselect](https://github.com/reduxjs/reselect) is used to create memoized selectors. |
|||
* [i18n-js](https://github.com/fnando/i18n-js) is used as i18n library. |
|||
* [expo-font](https://docs.expo.io/versions/latest/sdk/font/) library allows loading fonts easily. |
|||
* [Formik](https://github.com/jaredpalmer/formik) is used to build forms. |
|||
* [Yup](https://github.com/jquense/yup) is used for form validations. |
|||
|
|||
## Social / External Logins |
|||
|
|||
If you want to configure social/external logins for your application, please follow the [Social/External Logins](../../social-external-logins.md) document. |
|||
|
|||
## What's Next? |
|||
|
|||
- [The getting started document](../../get-started) explains how to create a new application in a few minutes. |
|||
- [The application development tutorial](../../tutorials/book-store/part-01.md) explains step by step application development. |
|||
|
|||
## See Also |
|||
* [Video tutorial](https://abp.io/video-courses/essentials/app-template) |
|||
@ -0,0 +1,56 @@ |
|||
# Layered Solution: Authentication |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Built-In Features", |
|||
"Path": "solution-templates/layered-web-application/built-in-features" |
|||
}, |
|||
"Next": { |
|||
"Name": "Database configurations in the Layered solution", |
|||
"Path": "solution-templates/layered-web-application/database-configurations" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
|||
|
|||
The [Layered solution template](index.md) is fully configured for authentication. All the services and applications are configured to use the [OpenIddict](https://documentation.openiddict.com) library for authentication. They are configured in a common way for authentication. This document explains that common authentication structure. |
|||
|
|||
If you choose the *Tiered* option while [creating](../../get-started/layered-web-application.md#creating-a-new-solution) the solution, the solution will have the `*.AuthServer` project. |
|||
|
|||
## OpenIddict |
|||
|
|||
[OpenIddict](https://documentation.openiddict.com) is an open-source library that provides a simple and easy way to implement an OpenID Connect server in your application. ABP has built-in modules ([OpenIddict](../../modules/openiddict.md), [OpenIddict UI **\***](../../modules/openiddict-pro.md)) to integrate OpenIddict into the solution. |
|||
|
|||
## Domain Layer |
|||
|
|||
The layered solution template *Domain* layer is the responsible for the OpenIddict definitions (Applications, Scopes, etc.). Also, it provides the *OpenIddictDataSeedContributor* class to seed the initial data. It creates the default clients (applications) and scopes for the solution. |
|||
|
|||
The [OpenIddict UI **\***](../../modules/openiddict-pro.md) module is added only if you choose the OpenIddict UI module while creating the solution. |
|||
|
|||
 |
|||
|
|||
The OpenIddict UI **\*** module provides a user interface to manage the OpenIddict entities such as applications, scopes, etc. You can manage these entities from the application UI. |
|||
|
|||
 |
|||
|
|||
## The Authentication Application |
|||
|
|||
The solution may include an external authentication server (`auth-server`) application if you select the *Tiered* option during solution creation. Otherwise, the authentication server is integrated into one of the [Web Applications](web-applications.md). |
|||
|
|||
The authentication server handles token generation, validation, and user account management (e.g., login, registration). It uses the [Account](../../modules/account.md) or [Account Pro **\***](../../modules/account-pro.md) module. The [Account Pro **\***](../../modules/account-pro.md) module additionally supports [social logins](../../modules/account-pro.md#social--external-logins) (e.g., Google, Facebook). Social logins can be enabled, disabled, and configured directly from the application's user interface. |
|||
|
|||
 |
|||
|
|||
## Authentication Flows |
|||
|
|||
Applications in the solution use different authentication flows depending on the application type: |
|||
|
|||
- **MVC UI Web Application**: |
|||
Uses the [Hybrid Flow](https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth) (OpenID Connect Authentication) for user authentication. |
|||
- **SPA and Swagger Applications**: |
|||
Use the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) to authenticate users. |
|||
|
|||
Once a user logs into the system and obtains a token from the authentication server, the `*.HttpApi.Host` application use [JWT Bearer Authentication](https://jwt.io/introduction/) to authorize the user's actions. |
|||
@ -0,0 +1,49 @@ |
|||
# Layered Solution: BLOB Storing |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Multi-Tenancy", |
|||
"Path": "solution-templates/layered-web-application/multi-tenancy" |
|||
}, |
|||
"Next": { |
|||
"Name": "CORS Configuration", |
|||
"Path": "solution-templates/layered-web-application/cors-configuration" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
|||
|
|||
This document explains how to store BLOBs (Binary Large Objects) in a layered solution. It is common to store files, images, videos, and other large objects in a distributed system. You can learn more about BLOB storage in the [BLOB Storing System](../../framework/infrastructure/blob-storing/index.md) documentation. |
|||
|
|||
In the layered solution template, the [Database Provider](../../framework/infrastructure/blob-storing/database.md) is used to store BLOBs in the database. The `Volo.Abp.BlobStoring.Database.EntityFrameworkCore` or `Volo.Abp.BlobStoring.Database.MongoDB` package provides the necessary implementations to store and retrieve BLOBs in the database. This setup is integrated into the layered solution template and is used in all related projects. You can change the database configuration in the `appsettings.json` file of the related project. |
|||
|
|||
You can use the `IBlobContainer` or `IBlobContainer<T>` service to store and retrieve BLOBs. Here is an example of storing a BLOB: |
|||
|
|||
```csharp |
|||
public class MyService : ITransientDependency |
|||
{ |
|||
private readonly IBlobContainer _blobContainer; |
|||
|
|||
public MyService(IBlobContainer blobContainer) |
|||
{ |
|||
_blobContainer = blobContainer; |
|||
} |
|||
|
|||
public async Task SaveBytesAsync(byte[] bytes) |
|||
{ |
|||
await _blobContainer.SaveAsync("my-blob-1", bytes); |
|||
} |
|||
|
|||
public async Task<byte[]> GetBytesAsync() |
|||
{ |
|||
return await _blobContainer.GetAllBytesOrNullAsync("my-blob-1"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The *File Management* module is optional and can be added to the solution during the creation process. It provides a user interface to manage folders and files. You can learn more about the module in the [File Management *](../../modules/file-management.md) document. |
|||
|
|||
 |
|||
@ -0,0 +1,25 @@ |
|||
# Layered Solution: Built-In Features |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Mobile Applications", |
|||
"Path": "solution-templates/layered-web-application/mobile-applications" |
|||
}, |
|||
"Next": { |
|||
"Name": "Authentication", |
|||
"Path": "solution-templates/layered-web-application/authentication" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The Layered solution template includes several built-in features to help you get started with your layered web application. These features are designed to provide a solid foundation for your application and help you focus on your business logic. This document provides an overview of the built-in features included in the Layered solution template. The following documents explains these features in details: |
|||
|
|||
* [Authentication](authentication.md) |
|||
* [Database configurations](database-configurations.md) |
|||
* [Logging (with Serilog)](logging.md) |
|||
* [Swagger integration](swagger-integration.md) |
|||
* [Multi-Tenancy](multi-tenancy.md) |
|||
* [BLOB storing](blob-storing.md) |
|||
* [CORS configuration](cors-configuration.md) |
|||
@ -0,0 +1,36 @@ |
|||
# Layered Solution: CORS Configuration |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "BLOB Storing", |
|||
"Path": "solution-templates/layered-web-application/blob-storing" |
|||
}, |
|||
"Next": { |
|||
"Name": "Helm Charts and Kubernetes", |
|||
"Path": "solution-templates/layered-web-application/helm-charts-and-kubernetes" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Cross-Origin Resource Sharing (CORS) is a security feature that allows web applications to make requests to a different domain than the one that served the web page. |
|||
|
|||
In the layered solution template, CORS configuration is applied in the following cases: |
|||
- If you select the [Tiered solution](solution-structure.md#tiered-structure-). |
|||
- If you choose [Angular](web-applications.md#angular) as the web application type. |
|||
- If you choose [No UI](web-applications.md#no-ui) as the web application type. |
|||
|
|||
The CORS settings are configured in the `appsettings.json` file of the corresponding project. Typically, the web application serves as the entry point for front-end applications, so it must be configured to accept requests from different origins. |
|||
|
|||
The default configuration in `appsettings.json` is as follows: |
|||
|
|||
```json |
|||
{ |
|||
"App": { |
|||
"CorsOrigins": "https://*.MyProjectName.com" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can modify the `CorsOrigins` property to include additional domains or wildcard subdomains as required by your application. |
|||
@ -0,0 +1,266 @@ |
|||
# Layered Solution: Database configurations |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Authentication", |
|||
"Path": "solution-templates/layered-web-application/authentication" |
|||
}, |
|||
"Next": { |
|||
"Name": "Logging (with Serilog)", |
|||
"Path": "solution-templates/layered-web-application/logging" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
|||
|
|||
ABP Studio's Layered Solution Template includes pre-configured database settings. This document explains how to manage database configurations in your solution. |
|||
|
|||
## Connection Strings |
|||
|
|||
Connection strings are stored in the `appsettings.json` file. You can customize them for different environments by modifying the respective `appsettings.json` files. The `*.DbMigrator` project and one of the [Web Application](web-applications.md) projects use the `Default` connection string by default. |
|||
|
|||
To change the connection string for the `Default` key, update the `appsettings.json` file in your project. Connection strings are defined under the `ConnectionStrings` section, as shown below: |
|||
|
|||
```json |
|||
{ |
|||
"ConnectionStrings": { |
|||
"Default": "Server=(LocalDb)\\MSSQLLocalDB;Database=Bookstore;Trusted_Connection=True;TrustServerCertificate=true" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### The DbContext Class |
|||
|
|||
In the `*.EntityFrameworkCore` project, the `DbContext` class is defined. The `DbContext` class is derived from the `AbpDbContext` class, which is a part of the ABP Framework. |
|||
|
|||
```csharp |
|||
[ReplaceDbContext(typeof(IIdentityProDbContext))] |
|||
[ReplaceDbContext(typeof(ISaasDbContext))] |
|||
[ConnectionStringName("Default")] |
|||
public class BookstoreDbContext : |
|||
AbpDbContext<BookstoreDbContext>, |
|||
ISaasDbContext, |
|||
IIdentityProDbContext |
|||
{ |
|||
#region Entities from the modules |
|||
|
|||
// Identity |
|||
public DbSet<IdentityUser> Users { get; set; } |
|||
public DbSet<IdentityRole> Roles { get; set; } |
|||
public DbSet<IdentityClaimType> ClaimTypes { get; set; } |
|||
public DbSet<OrganizationUnit> OrganizationUnits { get; set; } |
|||
public DbSet<IdentitySecurityLog> SecurityLogs { get; set; } |
|||
public DbSet<IdentityLinkUser> LinkUsers { get; set; } |
|||
public DbSet<IdentityUserDelegation> UserDelegations { get; set; } |
|||
public DbSet<IdentitySession> Sessions { get; set; } |
|||
|
|||
// SaaS |
|||
public DbSet<Tenant> Tenants { get; set; } |
|||
public DbSet<Edition> Editions { get; set; } |
|||
public DbSet<TenantConnectionString> TenantConnectionStrings { get; set; } |
|||
|
|||
#endregion |
|||
|
|||
public BookstoreDbContext(DbContextOptions<BookstoreDbContext> options) |
|||
: base(options) |
|||
{ |
|||
|
|||
} |
|||
|
|||
protected override void OnModelCreating(ModelBuilder builder) |
|||
{ |
|||
base.OnModelCreating(builder); |
|||
|
|||
builder.ConfigurePermissionManagement(); |
|||
builder.ConfigureSettingManagement(); |
|||
builder.ConfigureBackgroundJobs(); |
|||
builder.ConfigureAuditLogging(); |
|||
builder.ConfigureFeatureManagement(); |
|||
builder.ConfigureIdentityPro(); |
|||
builder.ConfigureOpenIddictPro(); |
|||
builder.ConfigureLanguageManagement(); |
|||
builder.ConfigureSaas(); |
|||
builder.ConfigureTextTemplateManagement(); |
|||
builder.ConfigureGdpr(); |
|||
builder.ConfigureCmsKit(); |
|||
builder.ConfigureCmsKitPro(); |
|||
builder.ConfigureBlobStoring(); |
|||
|
|||
/* Configure your own tables/entities inside here */ |
|||
|
|||
//builder.Entity<YourEntity>(b => |
|||
//{ |
|||
// b.ToTable(BookstoreConsts.DbTablePrefix + "YourEntities", BookstoreConsts.DbSchema); |
|||
// b.ConfigureByConvention(); //auto configure for the base class props |
|||
// //... |
|||
//}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### ConnectionStringName Attribute |
|||
|
|||
We're using the *Default* connection string in the `BookstoreDbContext` class. You can change the connection string name by updating the `ConnectionStringName` attribute. |
|||
|
|||
```csharp |
|||
[ConnectionStringName("Default")] |
|||
``` |
|||
|
|||
[The `ConnectionStringName` attribute](../../framework/fundamentals/connection-strings.md#set-the-connection-string-name) defines the unique name of the connection string that is being used by that `DbContext` class. It matches with the connection string defined in the `appsettings.json` file. That name is also used in database migrations to distinguish different database schemas, and used as the key while storing tenant connection strings for a multi-tenant system. |
|||
|
|||
#### ReplaceDbContext Attribute |
|||
|
|||
```csharp |
|||
[ReplaceDbContext(typeof(IIdentityProDbContext))] |
|||
[ReplaceDbContext(typeof(ISaasDbContext))] |
|||
``` |
|||
|
|||
The application DbContext utilizes the [Identity](../../modules/identity.md) and [Saas **\***](../../modules/saas.md) modules and creates a single database that contains these modules database schemas. These modules define their own `DbContext` class normally. But [the `ReplaceDbContext` attribute](../../framework/data/entity-framework-core/index.md#replace-other-dbcontextes) tells to ABP to use this (`BookstoreDbContext`) `DbContext` class instead of the `DbContext` classes defined by these modules. Technically, it replaces the given `DbContext` classes on runtime. We are doing that to ensure that we have a single (merged) database schema, single database migration path and a single database transaction operation when we work these multiple modules. When we replace a `DbContext`, we should implement its interface as done with the `BookstoreDbContext` class: |
|||
|
|||
````csharp |
|||
public class BookstoreDbContext : |
|||
AbpDbContext<BookstoreDbContext>, |
|||
ISaasDbContext, |
|||
IIdentityProDbContext |
|||
```` |
|||
|
|||
* That class implements `ISaasDbContext` and `IIdentityProDbContext`, so these modules can use it. |
|||
|
|||
As the next part, the `BookstoreDbContext` class defines the following properties those are forced by the implemented interfaces: |
|||
|
|||
```csharp |
|||
// Identity |
|||
public DbSet<IdentityUser> Users { get; set; } |
|||
public DbSet<IdentityRole> Roles { get; set; } |
|||
public DbSet<IdentityClaimType> ClaimTypes { get; set; } |
|||
public DbSet<OrganizationUnit> OrganizationUnits { get; set; } |
|||
public DbSet<IdentitySecurityLog> SecurityLogs { get; set; } |
|||
public DbSet<IdentityLinkUser> LinkUsers { get; set; } |
|||
public DbSet<IdentityUserDelegation> UserDelegations { get; set; } |
|||
public DbSet<IdentitySession> Sessions { get; set; } |
|||
|
|||
// SaaS |
|||
public DbSet<Tenant> Tenants { get; set; } |
|||
public DbSet<Edition> Editions { get; set; } |
|||
public DbSet<TenantConnectionString> TenantConnectionStrings { get; set; } |
|||
``` |
|||
|
|||
#### OnModelCreating Method |
|||
|
|||
The `OnModelCreating` method is used to configure the database schema. It calls the `Configure*` methods of the ABP Framework to configure the database schema for the modules. You can also configure your own tables/entities inside this method. |
|||
|
|||
```csharp |
|||
protected override void OnModelCreating(ModelBuilder builder) |
|||
{ |
|||
base.OnModelCreating(builder); |
|||
|
|||
builder.ConfigurePermissionManagement(); |
|||
builder.ConfigureSettingManagement(); |
|||
builder.ConfigureBackgroundJobs(); |
|||
builder.ConfigureAuditLogging(); |
|||
builder.ConfigureFeatureManagement(); |
|||
builder.ConfigureIdentityPro(); |
|||
builder.ConfigureOpenIddictPro(); |
|||
builder.ConfigureLanguageManagement(); |
|||
builder.ConfigureSaas(); |
|||
builder.ConfigureTextTemplateManagement(); |
|||
builder.ConfigureGdpr(); |
|||
builder.ConfigureCmsKit(); |
|||
builder.ConfigureCmsKitPro(); |
|||
builder.ConfigureBlobStoring(); |
|||
|
|||
/* Configure your own tables/entities inside here */ |
|||
|
|||
//builder.Entity<YourEntity>(b => |
|||
//{ |
|||
// b.ToTable(BookstoreConsts.DbTablePrefix + "YourEntities", BookstoreConsts.DbSchema); |
|||
// b.ConfigureByConvention(); //auto configure for the base class props |
|||
// //... |
|||
//}); |
|||
} |
|||
``` |
|||
|
|||
> The `Configure*` methods are extension methods defined in each module's `EntityFrameworkCore` project. These methods are used to configure the database schema for their respective modules. At runtime, the `DbContext` class is replaced by the `BookstoreDbContext` class only for the `DbContext` classes that use the `ReplaceDbContext` attribute. For other modules, their own dedicated `DbContext` classes are used without replacement. |
|||
|
|||
### The `IDesignTimeDbContextFactory` Implementation |
|||
|
|||
The `IDesignTimeDbContextFactory` interface is used to create a `DbContext` instance at design time. It is used by EF Core tools to create migrations and update the database. The `BookstoreDbContextFactory` class implements the `IDesignTimeDbContextFactory` interface to create a `BookstoreMigrationsDbContext` instance. |
|||
|
|||
```csharp |
|||
public class BookstoreDbContextFactory : IDesignTimeDbContextFactory<BookstoreDbContext> |
|||
{ |
|||
public BookstoreDbContext CreateDbContext(string[] args) |
|||
{ |
|||
var configuration = BuildConfiguration(); |
|||
|
|||
BookstoreEfCoreEntityExtensionMappings.Configure(); |
|||
|
|||
var builder = new DbContextOptionsBuilder<BookstoreDbContext>() |
|||
.UseSqlServer(configuration.GetConnectionString("Default")); |
|||
|
|||
return new BookstoreDbContext(builder.Options); |
|||
} |
|||
|
|||
private static IConfigurationRoot BuildConfiguration() |
|||
{ |
|||
var builder = new ConfigurationBuilder() |
|||
.SetBasePath(Path.Combine(Directory.GetCurrentDirectory(), "../Acme.Bookstore.DbMigrator/")) |
|||
.AddJsonFile("appsettings.json", optional: false); |
|||
|
|||
return builder.Build(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Configuration |
|||
|
|||
In the `*.EntityFrameworkCore` project, the `BookstoreEntityFrameworkCoreModule` class is used to configure the database context. |
|||
|
|||
```csharp |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.AddAbpDbContext<BookstoreDbContext>(options => |
|||
{ |
|||
/* Remove "includeAllEntities: true" to create |
|||
* default repositories only for aggregate roots */ |
|||
options.AddDefaultRepositories(includeAllEntities: true); |
|||
}); |
|||
|
|||
Configure<AbpDbContextOptions>(options => |
|||
{ |
|||
/* The main point to change your DBMS. |
|||
* See also BookstoreDbContextFactory for EF Core tooling. */ |
|||
options.UseSqlServer(); |
|||
}); |
|||
|
|||
} |
|||
``` |
|||
|
|||
We are basically setting the SQL Server as the default DBMS for this application. and registering the `BookstoreDbContext` class to the [dependency injection](../../framework/fundamentals/dependency-injection.md) system. |
|||
|
|||
### SaaS Module: The Tenant Management UI **\*** |
|||
|
|||
SaaS module provides the necessary UI to set and change connection string for tenants and trigger the database migrations. |
|||
|
|||
#### The Connection String Management Modal |
|||
|
|||
You can click to the *Database Connection Strings* command in the *Actions* dropdown button for a tenant in the *Tenants* page of the SaaS module: |
|||
|
|||
 |
|||
|
|||
It opens the *Database Connection Strings* modal as shown below: |
|||
|
|||
 |
|||
|
|||
Here, we can set a *Default connection string* for the tenant. |
|||
|
|||
When you make the changes and save the dialog, the database is automatically created and migrated. If you later update the connection string (for example if you change the database name), it will also trigger the database migration process again. |
|||
|
|||
#### Manually Applying the Database Migrations |
|||
|
|||
If you need to manually trigger the database migrations for a specific tenant, click the *Actions* dropdown for the related tenant and select the *Apply Database Migrations* command on the *Tenant Management* page of the SaaS module: |
|||
|
|||
 |
|||
@ -0,0 +1,41 @@ |
|||
# Layered Solution: Db Migrator |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Web Applications", |
|||
"Path": "solution-templates/layered-web-application/web-applications" |
|||
}, |
|||
"Next": { |
|||
"Name": "Mobile Applications", |
|||
"Path": "solution-templates/layered-web-application/mobile-applications" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
## Db Migrator Project |
|||
|
|||
The Db Migrator project is a console application designed to handle database schema migrations and seed data population. It operates as a standalone application that can be executed on-demand or integrated into a CI/CD pipeline. |
|||
|
|||
### Usage |
|||
|
|||
You can run the Db Migrator application: |
|||
- From the command line. |
|||
- Directly from Visual Studio. |
|||
|
|||
### Configuration |
|||
|
|||
The Db Migrator project maintains its own configuration, separate from the main application. If you need to update the database connection string or any related settings, ensure that changes are applied consistently to both the main application and the Db Migrator to avoid discrepancies. |
|||
|
|||
## Folder Structure |
|||
|
|||
In the `*.DbMigrator` project, you will find the `DbMigratorHostedService` class, which is responsible for executing database migrations and seeding data. This class is registered in the `Program` class and starts running when the application is launched. |
|||
|
|||
### Layers and Responsibilities |
|||
|
|||
- **`*.Domain` Layer**: |
|||
Contains the `Data` folder, which holds the necessary classes for managing database migrations and seed data. However, since the `*.Domain` layer does not reference the `EntityFrameworkCore` package, it only defines the abstraction for data migration. |
|||
|
|||
- **`*.EntityFrameworkCore` Layer**: |
|||
This layer is responsible for implementing database schema migrations. It includes the `EntityFrameworkCore[ProjectName]DbSchemaMigrator` class, which handles the actual migration logic using the `EntityFrameworkCore` package. |
|||
@ -0,0 +1,65 @@ |
|||
# Layered Solution: Helm Charts and Kubernetes |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "CORS configuration", |
|||
"Path": "solution-templates/layered-web-application/cors-configuration" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
> You must have an ABP Business or a higher license to be able to use the Kubernetes features. |
|||
|
|||
This document explains how to deploy the layered solution to a Kubernetes cluster using [Helm](https://helm.sh/) charts. The layered solution template includes Helm charts for each application and infrastructure (Redis, RabbitMQ, etc). You can use these charts to deploy the solution to a Kubernetes cluster. You can see the Helm charts in the `etc/helm` folder of the solution. |
|||
|
|||
## Folder Structure |
|||
|
|||
The folder structure of the Helm charts is as follows: |
|||
|
|||
 |
|||
|
|||
> You might have different charts based on the solution template options you selected while creating the solution. |
|||
|
|||
* **bookstore**: The Helm chart for the `Bookstore` solution. The folder name should be the same as your project name. |
|||
* **charts**: The sub-charts of the solution. Each application and infrastructure has its own chart. |
|||
* **templates**: The templates of the solution. It includes the ingress host URLs. |
|||
* **Chart.yaml**: The chart metadata. |
|||
* **values.bookstore-local.yaml**: The override values file for the [Kubernetes profile](../../studio/kubernetes.md#profile). It should follow the naming convention for your project name. |
|||
* **values.yaml**: The default values file for the chart. |
|||
* **build-all-images.ps1**: A PowerShell script to build all Docker images of the solution. |
|||
* **build-image.ps1**: A PowerShell script to build a Docker image of a specified project. |
|||
* **create-tls-secrets.ps1**: A PowerShell script to create local TLS secrets for the ingress controller. It's important when you try to [intercept a service](../../studio/kubernetes.md#intercept-a-service) and run it locally. |
|||
* **install.ps1**: A PowerShell script to install the solution to a Kubernetes cluster. You can override the default argument values. |
|||
* **uninstall.ps1**: A PowerShell script to uninstall the solution from a Kubernetes cluster. You can override the default argument values. |
|||
|
|||
## Installing the Helm Charts |
|||
|
|||
You can install the solution to a Kubernetes cluster using the `install.ps1` script. The script has the following arguments: |
|||
|
|||
* **ChartName**: Default value is the project name. You can create different charts and specify the chart name. In ABP Studio [Kubernetes Main Chart](../../studio/kubernetes.md#main-chart) *Install Chart(s)* command automatically sets the chart name. |
|||
* **Namespace**: The namespace to install the Kubernetes resources. Default value is the project name with the `-local` suffix. |
|||
* **ReleaseName**: The release name of the Helm chart. Default value is the project name with the `-local` suffix. |
|||
* **DotnetEnvironment**: The environment to run the application. Default value is `Staging`. |
|||
* **User**: The user responsible for installing the Kubernetes resources. The application will automatically set the user name if you configure it under [Specify the User](../../studio/kubernetes.md#specify-the-user). |
|||
|
|||
Before running the script, you need to build the Docker images of the solution. You can use the `build-all-images.ps1` script to build all Docker images of the solution. Afterwards, make sure that you have a Kubernetes TLS secret for the ingress controller. It is automatically created when you create the solution; however, if you clone the solution from a repository, you need to create it manually. You can use the `create-tls-secrets.ps1` script to create the TLS secret. Then you can run the `install.ps1` script to install the solution to a Kubernetes cluster. |
|||
|
|||
## Uninstalling the Helm Charts |
|||
|
|||
You can uninstall the solution from a Kubernetes cluster using the `uninstall.ps1` script. The script has the following arguments: |
|||
|
|||
* **Namespace**: The namespace to uninstall the helm chart. Default value is the project name with the `-local` suffix. |
|||
* **ReleaseName**: The release name of the Helm chart. Default value is the project name with the `-local` suffix. |
|||
* **User**: The user responsible for uninstalling the Kubernetes resources. The application will automatically set the user name if you configure it under [Specify the User](../../studio/kubernetes.md#specify-the-user). |
|||
|
|||
You can run the `uninstall.ps1` script to uninstall the solution from a Kubernetes cluster. |
|||
|
|||
```bash |
|||
./uninstall.ps1 |
|||
``` |
|||
|
|||
Additionally, in ABP Studio [Kubernetes](../../studio/kubernetes.md) feature, you can do the same operations more easily. You can use the Install Chart(s) and Uninstall Chart(s) commands to install and uninstall the solution to a Kubernetes cluster. Also, use the Build Docker Image(s) command to build the Docker images of the solution. |
|||
|
|||
 |
|||
|
After Width: | Height: | Size: 58 KiB |
|
After Width: | Height: | Size: 79 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 88 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 59 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 35 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 84 KiB |
|
After Width: | Height: | Size: 96 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
After Width: | Height: | Size: 103 KiB |
|
After Width: | Height: | Size: 40 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 95 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 42 KiB |
|
After Width: | Height: | Size: 7.1 KiB |
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 183 KiB |
@ -1,465 +1,35 @@ |
|||
# Layered Application Solution Template |
|||
# ABP Studio: Layered Solution Template |
|||
|
|||
This template provides a layered application structure based on the [Domain Driven Design](../../framework/architecture/domain-driven-design) (DDD) practices. |
|||
|
|||
## Getting Started |
|||
|
|||
This document explains **the solution structure** and projects in details. If you want to start quickly, follow the guides below: |
|||
|
|||
* [The getting started document](../../get-started/layered-web-application.md) explains how to create a new application in a few minutes. |
|||
* [The application development tutorial](../../tutorials/book-store/part-01.md) explains step by step application development. |
|||
|
|||
## How to Start With? |
|||
|
|||
You can use the [ABP CLI](../../cli) to create a new project using this startup template. Alternatively, you can generate a CLI command from the [Get Started](https://abp.io/get-started) page. CLI approach is used here. |
|||
|
|||
First, install the ABP CLI if you haven't installed it before: |
|||
|
|||
````bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
```` |
|||
|
|||
Then use the `abp new` command in an empty folder to create a new solution: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -t app |
|||
```` |
|||
|
|||
* `Acme.BookStore` is the solution name, like *YourCompany.YourProduct*. You can use single-level, two-level or three-level naming. |
|||
* This example specified the template name (`-t` or `--template` option). However, `app` is already the default template if you didn't specify it. |
|||
|
|||
### Specify the UI Framework |
|||
|
|||
This template provides multiple UI frameworks: |
|||
|
|||
* `mvc`: ASP.NET Core MVC UI with Razor Pages (default) |
|||
* `blazor`: Blazor UI |
|||
* `blazor-server`: Blazor Server UI |
|||
* `angular`: Angular UI |
|||
|
|||
Use the `-u` or `--ui` option to specify the UI framework: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -u angular |
|||
```` |
|||
|
|||
### Specify the Database Provider |
|||
|
|||
This template supports the following database providers: |
|||
|
|||
- `ef`: Entity Framework Core (default) |
|||
- `mongodb`: MongoDB |
|||
|
|||
Use `-d` (or `--database-provider`) option to specify the database provider: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -d mongodb |
|||
```` |
|||
|
|||
### Specify the Mobile Application Framework |
|||
|
|||
This template supports the following mobile application frameworks: |
|||
|
|||
- `react-native`: React Native (*Available for* ***Team*** *or higher licenses*) |
|||
|
|||
Use the `-m` (or `--mobile`) option to specify the mobile application framework: |
|||
|
|||
````bash |
|||
abp new Acme.BookStore -m react-native |
|||
```` |
|||
|
|||
* [The getting started document](../../get-started/layered-web-application.md) explains how to create a new application with this startup template. |
|||
* [The application development tutorial](../../tutorials/book-store/part-01.md) explains step by step application development with this startup template. |
|||
|
|||
## Solution Structure |
|||
|
|||
Based on the options you've specified, you will get a slightly different solution structure. |
|||
|
|||
### Default Structure |
|||
|
|||
If you don't specify any additional options, you will have a solution as shown below: |
|||
|
|||
 |
|||
|
|||
Projects are organized in `src` and `test` folders. `src` folder contains the actual application which is layered based on [DDD](../../framework/architecture/domain-driven-design) principles as mentioned before. |
|||
|
|||
The diagram below shows the layers & project dependencies of the application: |
|||
|
|||
 |
|||
|
|||
Each section below will explain the related project & its dependencies. |
|||
|
|||
#### .Domain.Shared Project |
|||
|
|||
This project contains constants, enums and other objects these are actually a part of the domain layer, but needed to be used by all layers/projects in the solution. |
|||
|
|||
A `BookType` enum and a `BookConsts` class (which may have some constant fields for the `Book` entity, like `MaxNameLength`) are good candidates for this project. |
|||
|
|||
* This project has no dependency on other projects in the solution. All other projects depend on this one directly or indirectly. |
|||
|
|||
#### .Domain Project |
|||
|
|||
This is the domain layer of the solution. It mainly contains [entities, aggregate roots](../../framework/architecture/domain-driven-design/entities.md), [domain services](../../framework/architecture/domain-driven-design/domain-services.md), [value objects](../../framework/architecture/domain-driven-design/value-objects.md), [repository interfaces](../../framework/architecture/domain-driven-design/repositories.md) and other domain objects. |
|||
|
|||
A `Book` entity, a `BookManager` domain service and an `IBookRepository` interface are good candidates for this project. |
|||
|
|||
* Depends on the `.Domain.Shared` because it uses constants, enums and other objects defined in that project. |
|||
|
|||
#### .Application.Contracts Project |
|||
|
|||
This project mainly contains [application service](../../framework/architecture/domain-driven-design/application-services.md) **interfaces** and [Data Transfer Objects](../../framework/architecture/domain-driven-design/data-transfer-objects.md) (DTO) of the application layer. It exists to separate the interface & implementation of the application layer. In this way, the interface project can be shared to the clients as a contract package. |
|||
|
|||
An `IBookAppService` interface and a `BookCreationDto` class are good candidates for this project. |
|||
|
|||
* Depends on the `.Domain.Shared` because it may use constants, enums and other shared objects of this project in the application service interfaces and DTOs. |
|||
|
|||
#### .Application Project |
|||
|
|||
This project contains the [application service](../../framework/architecture/domain-driven-design/application-services.md) **implementations** of the interfaces defined in the `.Application.Contracts` project. |
|||
|
|||
A `BookAppService` class is a good candidate for this project. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to implement the interfaces and use the DTOs. |
|||
* Depends on the `.Domain` project to be able to use domain objects (entities, repository interfaces... etc.) to perform the application logic. |
|||
|
|||
#### .EntityFrameworkCore Project |
|||
|
|||
This is the integration project for the EF Core. It defines the `DbContext` and implements repository interfaces defined in the `.Domain` project. |
|||
|
|||
* Depends on the `.Domain` project to be able to reference to entities and repository interfaces. |
|||
|
|||
> This project is available only if you are using EF Core as the database provider. If you select another database provider, its name will be different. |
|||
|
|||
#### .DbMigrator Project |
|||
|
|||
This is a console application that simplifies the execution of database migrations on development and production environments. When you run this application, it: |
|||
|
|||
* Creates the database if necessary. |
|||
* Applies the pending database migrations. |
|||
* Seeds initial data if needed. |
|||
|
|||
> This project has its own `appsettings.json` file. So, if you want to change the database connection string, remember to change this file too. |
|||
|
|||
Especially, seeding initial data is important at this point. ABP has a modular data seed infrastructure. See [its documentation](../../framework/infrastructure/data-seeding.md) for more about the data seeding. |
|||
|
|||
While creating database & applying migrations seem only necessary for relational databases, this project comes even if you choose a NoSQL database provider (like MongoDB). In that case, it still seeds the initial data which is necessary for the application. |
|||
|
|||
* Depends on the `.EntityFrameworkCore` project (for EF Core) since it needs to access to the migrations. |
|||
* Depends on the `.Application.Contracts` project to be able to access permission definitions, because the initial data seeder grants all permissions to the admin role by default. |
|||
|
|||
#### .HttpApi Project |
|||
|
|||
This project is used to define your API Controllers. |
|||
|
|||
Most of the time you don't need to manually define API Controllers since ABP's [Auto API Controllers](../../framework/api-development/auto-controllers.md) feature creates them automagically based on your application layer. However, in case of you need to write API controllers, this is the best place to do it. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to inject the application service interfaces. |
|||
|
|||
#### .HttpApi.Client Project |
|||
|
|||
This is a project that defines C# client proxies to use the HTTP APIs of the solution. You can share this library to 3rd-party clients, so they can easily consume your HTTP APIs in their Dotnet applications (For other types of applications, they can still use your APIs, either manually or using a tool in their own platform) |
|||
|
|||
Most of the time you don't need to manually create C# client proxies, thanks to ABP's [Dynamic C# API Clients](../../framework/api-development/dynamic-csharp-clients.md) feature. |
|||
|
|||
`.HttpApi.Client.ConsoleTestApp` project is a console application created to demonstrate the usage of the client proxies. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to share the same application service interfaces and DTOs with the remote service. |
|||
|
|||
> You can delete this project & dependencies if you don't need to create C# client proxies for your APIs. |
|||
|
|||
#### .Web Project |
|||
|
|||
This project contains the User Interface (UI) of the application if you are using ASP.NET Core MVC UI. It contains Razor pages, JavaScript files, CSS files, images and so on... |
|||
|
|||
This project contains the main `appsettings.json` file that contains the connection string and other configurations of the application. |
|||
|
|||
* Depends on the `.HttpApi` project since the UI layer needs to use APIs and the application service interfaces of the solution. |
|||
|
|||
> If you check the source code of the `.Web.csproj` file, you will see the references to the `.Application` and the `.EntityFrameworkCore` projects. |
|||
> |
|||
> These references are actually not needed while coding your UI layer, because the UI layer normally doesn't depend on the EF Core or the Application layer's implementation. These startup templates are ready for tiered deployment, where the API layer is hosted on a separate server than the UI layer. |
|||
> |
|||
> However, if you don't choose the `--tiered` option, these references will be in the .Web project to be able to host the Web, API and application layers in a single application endpoint. |
|||
> |
|||
> This gives you the ability to use domain entities & repositories in your presentation layer. However, this is considered as a bad practice according to DDD. |
|||
|
|||
#### Test Projects |
|||
|
|||
The solution has multiple test projects, one for each layer: |
|||
|
|||
* `.Domain.Tests` is used to test the domain layer. |
|||
* `.Application.Tests` is used to test the application layer. |
|||
* `.EntityFrameworkCore.Tests` is used to test EF Core configuration and custom repositories. |
|||
* `.Web.Tests` is used to test the UI (if you are using ASP.NET Core MVC UI). |
|||
* `.TestBase` is a base (shared) project for all tests. |
|||
|
|||
In addition, `.HttpApi.Client.ConsoleTestApp` is a console application (not an automated test project) which demonstrate the usage of HTTP APIs from a .NET application. |
|||
|
|||
Test projects are prepared for integration testing; |
|||
|
|||
* It is fully integrated into the ABP and all services in your application. |
|||
* It uses SQLite in-memory database for EF Core. For MongoDB, it uses the [EphemeralMongo](https://github.com/asimmon/ephemeral-mongo) library. |
|||
* Authorization is disabled, so any application service can be easily used in tests. |
|||
|
|||
You can still create unit tests for your classes which will be harder to write (because you will need to prepare mock/fake objects), but faster to run (because it only tests a single class and skips all the initialization processes). |
|||
|
|||
#### How to Run? |
|||
|
|||
Set `.Web` as the startup project and run the application. The default username is `admin` and the password is `1q2w3E*`. |
|||
|
|||
See [Getting Started With the ASP.NET Core MVC Template](../../get-started/layered-web-application.md) for more information. |
|||
|
|||
### Tiered Structure |
|||
|
|||
If you have selected the ASP.NET Core UI and specified the `--tiered` option, the solution created will be a tiered solution. The purpose of the tiered structure is to be able to **deploy Web applications and HTTP API to different servers**: |
|||
|
|||
 |
|||
|
|||
* Browser runs your UI by executing HTML, CSS & JavaScript. |
|||
* Web servers host static UI files (CSS, JavaScript, image... etc.) & dynamic components (e.g. Razor pages). It performs HTTP requests to the API server to execute the business logic of the application. |
|||
* The API Server hosts the HTTP APIs which then use the application & domain layers of the application to perform the business logic. |
|||
* Finally, database server hosts your database. |
|||
|
|||
So, the resulting solution allows a 4-tiered deployment, by comparing to 3-tiered deployment of the default structure explained before. |
|||
|
|||
> Unless you actually need such a 4-tiered deployment, it's suggested to go with the default structure which is simpler to develop, deploy and maintain. |
|||
|
|||
The solution structure is shown below: |
|||
|
|||
 |
|||
|
|||
As different from the default structure, two new projects come into play: `.AuthServer` & `.HttpApi.Host`. |
|||
|
|||
#### .AuthServer Project |
|||
|
|||
This project is used as an authentication server for other projects. `.Web` project uses OpenId Connect Authentication to get identity and access tokens for the current user from the AuthServer. Then uses the access token to call the HTTP API server. HTTP API server uses bearer token authentication to obtain claims from the access token to authorize the current user. |
|||
|
|||
 |
|||
|
|||
ABP uses the [OpenIddict Module](../../modules/openiddict.md) that uses the open-source [OpenIddict-core](https://github.com/openiddict/openiddict-core) library for the authentication between applications. See [OpenIddict documentation](https://documentation.openiddict.com/) for details about the OpenIddict and OpenID Connect protocol. |
|||
|
|||
It has its own `appsettings.json` that contains database connection and other configurations. |
|||
|
|||
#### .HttpApi.Host Project |
|||
|
|||
This project is an application that hosts the API of the solution. It has its own `appsettings.json` that contains database connection and other configurations. |
|||
|
|||
#### .Web Project |
|||
|
|||
Just like the default structure, this project contains the User Interface (UI) of the application. It contains razor pages, JavaScript files, style files, images and so on... |
|||
|
|||
This project contains an `appsettings.json` file, but this time it does not have a connection string because it never connects to the database. Instead, it mainly contains the endpoint of the remote API server and the authentication server. |
|||
|
|||
#### Pre-requirements |
|||
|
|||
* [Redis](https://redis.io/): The applications use Redis as a distributed cache. So, you need to have Redis installed & running. |
|||
|
|||
#### How to Run? |
|||
|
|||
You should run the application with the given order: |
|||
|
|||
* First, run the `.AuthServer` since other applications depend on it. |
|||
* Then run the `.HttpApi.Host` since it is used by the `.Web` application. |
|||
* Finally, you can run the `.Web` project and login to the application (using `admin` as the username and `1q2w3E*` as the password). |
|||
|
|||
### Blazor UI |
|||
If you choose `Blazor` as the UI Framework (using the `-u blazor` or `-u blazor-server` option), the solution will have a project named `.Blazor`. This project contains the Blazor UI application. According to your choice, it will be a Blazor WebAssembly or Blazor Server application. If Blazor WebAssembly is selected, the solution will also have a `.HttpApi.Host`. This project is an ASP.NET Core application that hosts the backend application for the Blazor single page application. |
|||
|
|||
#### .Blazor Project (Server) |
|||
The Blazor Server project is similar to the ASP.NET Core MVC project. It replaces `.Web` project with `.Blazor` in the solution structure above. It has the same folder structure and the same application flow. Since it's an ASP.NET Core application, it can contain **.cshtml** files and **.razor** components at the same time. If routing matches a razor component, the Blazor UI will be used. Otherwise, the request will be handled by the MVC framework. |
|||
|
|||
 |
|||
|
|||
#### .Blazor Project (WebAssembly) |
|||
The Blazor WebAssembly project is a single page application that runs on the browser. You'll see it as `.Blazor` project in the solution. It uses the `.HttpApi.Host` project to communicate with the backend. It can't be used without the backend application. It contains only **.razor** components. It's a pure client-side application. It doesn't have any server-side code. Everything in this layer will be for the client side. |
|||
|
|||
 |
|||
|
|||
### Angular UI |
|||
|
|||
If you choose `Angular` as the UI framework (using the `-u angular` option), the solution is being separated into two folders: |
|||
|
|||
* `angular` folder contains the Angular UI application, the client-side code. |
|||
* `aspnet-core` folder contains the ASP.NET Core solution, the server-side code. |
|||
|
|||
The server-side is similar to the solution described above. `*.HttpApi.Host` project serves the API, so the `Angular` application consumes it. |
|||
|
|||
Angular application folder structure looks like below: |
|||
|
|||
 |
|||
|
|||
|
|||
Each of ABP modules is an NPM package. Some ABP modules are added as a dependency in `package.json`. These modules install with their dependencies. To see all ABP packages, you can run the following command in the `angular` folder: |
|||
|
|||
```bash |
|||
yarn list --pattern abp |
|||
``` |
|||
|
|||
Angular application module structure: |
|||
|
|||
 |
|||
|
|||
#### AppModule |
|||
|
|||
`AppModule` is the root module of the application. Some of the ABP modules and some essential modules are imported to `AppModule`. |
|||
|
|||
ABP Config modules have also been imported to `AppModule` for initial requirements of the lazy-loadable ABP modules. |
|||
|
|||
#### AppRoutingModule |
|||
|
|||
There are lazy-loadable ABP modules in the `AppRoutingModule` as routes. |
|||
|
|||
> Paths of ABP Modules should not be changed. |
|||
|
|||
You should add `routes` property in the `data` object to add a link on the menu to redirect to your custom pages. |
|||
|
|||
```js |
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
path: 'dashboard', |
|||
loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule), |
|||
canActivate: [authGuard, permissionGuard], |
|||
data: { |
|||
routes: { |
|||
name: 'ProjectName::Menu:Dashboard', |
|||
order: 2, |
|||
iconClass: 'fa fa-dashboard', |
|||
requiredPolicy: 'ProjectName.Dashboard.Host' |
|||
} as ABP.Route |
|||
} |
|||
"Next": { |
|||
"Name": "Overview", |
|||
"Path": "solution-templates/layered-web-application/overview" |
|||
} |
|||
} |
|||
``` |
|||
In the above example; |
|||
* If the user is not logged in, authGuard blocks access and redirects to the login page. |
|||
* permissionGuard checks the user's permission with the `requiredPolicy` property of the `routes` object. If the user is not authorized to access the page, the 403 page appears. |
|||
* The `name` property of `routes` is the menu link label. A localization key can be defined. |
|||
* The `iconClass` property of the `routes` object is the menu link icon class. |
|||
* The `requiredPolicy` property of the `routes` object is the required policy key to access the page. |
|||
|
|||
After the above `routes` definition, if the user is authorized, the dashboard link will appear on the menu. |
|||
|
|||
#### Shared Module |
|||
|
|||
The modules that may be required for all modules have been imported to the `SharedModule`. You should import `SharedModule` to all modules. |
|||
|
|||
See the [Sharing Modules](https://angular.io/guide/sharing-ngmodules) document. |
|||
|
|||
#### Environments |
|||
|
|||
The files under the `src/environments` folder have the essential configuration of the application. |
|||
|
|||
#### Home Module |
|||
|
|||
Home module is an example lazy-loadable module that loads on the root address of the application. |
|||
|
|||
#### Styles |
|||
|
|||
The required style files are added to the `styles` array in `angular.json`. `AppComponent` loads some style files lazily via `LazyLoadService` after the main bundle is loaded to shorten the first rendering time. |
|||
|
|||
#### Testing |
|||
|
|||
You should create your tests in the same folder as the file you want to test. |
|||
|
|||
See the [testing document](https://angular.io/guide/testing). |
|||
|
|||
#### Depended Packages |
|||
|
|||
* [NG Bootstrap](https://ng-bootstrap.github.io/) is used as UI component library. |
|||
* [NGXS](https://www.ngxs.io/) is used as state management library. |
|||
* [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc) is used to support for OAuth 2 and OpenId Connect (OIDC). |
|||
* [Chart.js](https://www.chartjs.org/) is used to create widgets. |
|||
* [ngx-validate](https://github.com/ng-turkey/ngx-validate) is used for dynamic validation of reactive forms. |
|||
|
|||
### React Native |
|||
|
|||
If the `-m react-native` option is specified in the new project command, the solution includes the [React Native](https://reactnative.dev/) application in the `react-native` folder. |
|||
|
|||
The server-side is similar to the solution described above. `*.HttpApi.Host` project serves the API, so the React Native application consumes it. |
|||
|
|||
The React Native application was generated with [Expo](https://expo.io/). Expo is a set of tools built around React Native to help you quickly start an app and, while it has many features. |
|||
|
|||
React Native application folder structure as like below: |
|||
|
|||
 |
|||
|
|||
* `App.js` is the bootstrap component of the application. |
|||
* `Environment.js` file has the essential configuration of the application. `prod` and `dev` configurations are defined in this file. |
|||
* [Contexts](https://reactjs.org/docs/context.html) are created in the `src/contexts` folder. |
|||
* [Higher order components](https://reactjs.org/docs/higher-order-components.html) are created in the `src/hocs` folder. |
|||
* [Custom hooks](https://reactjs.org/docs/hooks-custom.html#extracting-a-custom-hook) are created in `src/hooks`. |
|||
* [Axios interceptors](https://github.com/axios/axios#interceptors) are created in the `src/interceptors` folder. |
|||
* Utility functions are exported from `src/utils` folder. |
|||
|
|||
#### Components |
|||
|
|||
Components that can be used on all screens are created in the `src/components` folder. All components have been created as a function that is able to use [hooks](https://reactjs.org/docs/hooks-intro.html). |
|||
|
|||
#### Screens |
|||
|
|||
 |
|||
|
|||
Screens are created by creating folders that separate their names in the `src/screens` folder. Certain parts of some screens can be split into components. |
|||
|
|||
Each screen is used in a navigator in the `src/navigators` folder. |
|||
|
|||
#### Navigation |
|||
|
|||
[React Navigation](https://reactnavigation.org/) is used as a navigation library. Navigators are created in the `src/navigators`. A [drawer](https://reactnavigation.org/docs/drawer-based-navigation/) navigator and several [stack](https://reactnavigation.org/docs/hello-react-navigation/#installing-the-stack-navigator-library) navigators have been created in this folder. See the [above diagram](#screens) for the navigation structure. |
|||
|
|||
#### State Management |
|||
|
|||
[Redux](https://redux.js.org/) is used as a state management library. [Redux Toolkit](https://redux-toolkit.js.org/) library is used as a toolset for efficient Redux development. |
|||
|
|||
Actions, reducers, sagas and selectors are created in the `src/store` folder. Store folder is as below: |
|||
|
|||
 |
|||
|
|||
* [**Store**](https://redux.js.org/basics/store) is defined in the `src/store/index.js` file. |
|||
* [**Actions**](https://redux.js.org/basics/actions/) are payloads of information that send data from your application to your store. |
|||
* [**Reducers**](https://redux.js.org/basics/reducers) specify how the application's state changes in response to actions sent to the store. |
|||
* [**Redux-Saga**](https://redux-saga.js.org/) is a library that aims to make application side effects (i.e. asynchronous things like data fetching and impure things like accessing the browser cache) easier to manage. Sagas are created in the `src/store/sagas` folder. |
|||
* [**Reselect**](https://github.com/reduxjs/reselect) library is used to create memoized selectors. Selectors are created in the `src/store/selectors` folder. |
|||
|
|||
#### APIs |
|||
|
|||
[Axios](https://github.com/axios/axios) is used as an HTTP client library. An Axios instance has exported from `src/api/API.js` file to make HTTP calls with the same config. `src/api` folder also has the API files that have been created for API calls. |
|||
|
|||
#### Theming |
|||
|
|||
[Native Base](https://nativebase.io/) is used as UI components library. Native Base components can customize easily. See the [Native Base customize](https://docs.nativebase.io/customizing-components) documentation. We followed the same way. |
|||
|
|||
* Native Base theme variables are in the `src/theme/variables` folder. |
|||
* Native Base component styles are in the `src/theme/components` folder. These files have been generated with Native Base's `ejectTheme` script. |
|||
* Styles of components override with the files under the `src/theme/overrides` folder. |
|||
|
|||
#### Testing |
|||
|
|||
Unit tests will be created. |
|||
|
|||
See the [Testing Overview](https://reactjs.org/docs/testing.html) document. |
|||
|
|||
#### Depended Libraries |
|||
|
|||
* [Native Base](https://nativebase.io/) is used as UI components library. |
|||
* [React Navigation](https://reactnavigation.org/) is used as navigation library. |
|||
* [Axios](https://github.com/axios/axios) is used as an HTTP client library. |
|||
* [Redux](https://redux.js.org/) is used as state management library. |
|||
* [Redux Toolkit](https://redux-toolkit.js.org/) library is used as a toolset for efficient Redux development. |
|||
* [Redux-Saga](https://redux-saga.js.org/) is used to manage asynchronous processes. |
|||
* [Redux Persist](https://github.com/rt2zz/redux-persist) is used as state persistence. |
|||
* [Reselect](https://github.com/reduxjs/reselect) is used to create memoized selectors. |
|||
* [i18n-js](https://github.com/fnando/i18n-js) is used as i18n library. |
|||
* [expo-font](https://docs.expo.io/versions/latest/sdk/font/) library allows loading fonts easily. |
|||
* [Formik](https://github.com/jaredpalmer/formik) is used to build forms. |
|||
* [Yup](https://github.com/jquense/yup) is used for form validations. |
|||
|
|||
## Social / External Logins |
|||
|
|||
If you want to configure social/external logins for your application, please follow the [Social/External Logins](../../social-external-logins.md) document. |
|||
|
|||
## What's Next? |
|||
|
|||
- [The getting started document](../../get-started) explains how to create a new application in a few minutes. |
|||
- [The application development tutorial](../../tutorials/book-store/part-01.md) explains step by step application development. |
|||
```` |
|||
|
|||
## See Also |
|||
* [Video tutorial](https://abp.io/video-courses/essentials/app-template) |
|||
ABP Studio provides pre-architected, production-ready templates to jump-start a new solution. One of these templates is the Layered solution template. It is designed for building monolithic layered systems that follow common application patterns based on [Domain-Driven Design](../../framework/architecture/domain-driven-design) (DDD) principles. The template includes multiple layers, integrates existing modules, and provides host applications based on your selections, making it an excellent foundation for your layered system. |
|||
|
|||
> **This document explains the Layered solution template in detail. It is a reference document to fully understand the solution and refer to when you have trouble.** |
|||
|
|||
> **If you want to quickly create a layered solution, please refer to *[Quick Start: Creating a Layered Web Application with ABP Studio](../../get-started/layered-web-application.md)* document.** |
|||
|
|||
## Contents |
|||
|
|||
* [Overview](overview.md) |
|||
* [Solution structure](solution-structure.md) |
|||
* [Main Components](main-components.md) |
|||
* [Web Applications](web-applications.md) |
|||
* [Db Migrator](db-migrator.md) |
|||
* [Mobile Applications](mobile-applications.md) |
|||
* [Built-In Features](built-in-features.md) |
|||
* [Authentication](authentication.md) |
|||
* [Database configurations](database-configurations.md) |
|||
* [Logging (with Serilog)](logging.md) |
|||
* [Swagger integration](swagger-integration.md) |
|||
* [Multi-Tenancy](multi-tenancy.md) |
|||
* [BLOB storing](blob-storing.md) |
|||
* [CORS configuration](cors-configuration.md) |
|||
* [Helm Charts and Kubernetes](helm-charts-and-kubernetes.md) |
|||
|
|||
@ -0,0 +1,35 @@ |
|||
# Layered Solution: Logging |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Database configurations", |
|||
"Path": "solution-templates/layered-web-application/database-configurations" |
|||
}, |
|||
"Next": { |
|||
"Name": "Swagger integration", |
|||
"Path": "solution-templates/layered-web-application/swagger-integration" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The ABP Studio [layered solution template](index.md) is fully configured for [logging](../../framework/fundamentals/logging.md). All the applications are configured to use the [Serilog](https://serilog.net/) library for structured logging. They are configured in a common way for logging. This document explains that common logging structure. |
|||
|
|||
## The Serilog Sinks |
|||
|
|||
The Serilog library is configured so it writes the logs to the following targets (a.k.a. [sinks](https://github.com/serilog/serilog/wiki/Provided-Sinks)) in parallel: |
|||
|
|||
* **[Console](https://github.com/serilog/serilog-sinks-console)**: Logs are written to the standard output of the executing application. Logging to console is useful when you want to see logs easily while it is running in a container. |
|||
* **[File](https://github.com/serilog/serilog-sinks-file)**: Logs are written to a file named `logs.txt` located under the `Logs` folder of the executing application. File logging is useful when you run the application on your local computer. You can check logs easily when you have a trouble. This sinks is only configured for DEBUG mode. It won't be available in your production environment (you can change the behavior in your `Program.cs` file). |
|||
* **ABP Studio**: This is a Sink provided by ABP Studio. It sends all logs to ABP Studio, so you can easily monitor your logs in real-time on your ABP Studio Application Monitoring panel. |
|||
|
|||
The solution can work with [any sink](https://github.com/serilog/serilog/wiki/Provided-Sinks) supported by Serilog. You can add more sinks, remove pre-installed sinks or fine tune their configuration for your solution. |
|||
|
|||
## Program.cs |
|||
|
|||
The `Program.cs` file is the main point that configures the logging system. It is done here, because we want to initialize and start the logging in the very beginning of the application. |
|||
|
|||
## Additional Information |
|||
|
|||
We are using ABP Serilog Enrichers in the module class of the application. It is done by the `app.UseAbpSerilogEnrichers();` line in the `OnApplicationInitialization` method of your module class. That ASP.NET Core middleware adds current [tenant](../../framework/architecture/multi-tenancy/index.md), [user](../../framework/infrastructure/current-user.md), client and correlation id information to the log records. |
|||
@ -0,0 +1,21 @@ |
|||
# Layered Solution: Main Components |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Solution structure", |
|||
"Path": "solution-templates/layered-web-application/solution-structure" |
|||
}, |
|||
"Next": { |
|||
"Name": "Web Applications", |
|||
"Path": "solution-templates/layered-web-application/web-applications" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
The solution consists of various applications; web applications, mobile applications, and a database migrator application. These applications are the main components of the solution and are designed to work together to provide a complete solution. The following documents explains these components in details: |
|||
|
|||
* [Web Applications](web-applications.md) |
|||
* [Db Migrator](db-migrator.md) |
|||
* [Mobile Applications](mobile-applications.md) |
|||
@ -0,0 +1,122 @@ |
|||
# Layered Solution: Mobile Applications |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Db Migrator", |
|||
"Path": "solution-templates/layered-web-application/db-migrator" |
|||
}, |
|||
"Next": { |
|||
"Name": "Built-In Features", |
|||
"Path": "solution-templates/layered-web-application/built-in-features" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> You must have an ABP Team or a higher license to be able to create a mobile application project with ABP Studio. |
|||
|
|||
Mobile applications are an essential part of modern software solutions. They provide a user-friendly interface to the end-users and allow them to access the system from anywhere. ABP Studio allows you to create mobile applications for your layered solution. You can create a new mobile application project, configure it, and run it on your device. |
|||
|
|||
## Mobile Application Types |
|||
|
|||
ABP Studio supports the following mobile application types: |
|||
|
|||
- **None**: No mobile application project is created. It is the default option. |
|||
- **MAUI**: Cross-platform mobile applications with .NET MAUI (Multi-platform App UI). You can create MAUI projects with ABP Studio. |
|||
- **React Native**: Cross-platform mobile applications that share code between iOS and Android platforms. You can create React Native projects with ABP Studio. |
|||
|
|||
You can select the mobile application type when creating a new layered application project during the *Mobile Framework* step. |
|||
|
|||
 |
|||
|
|||
### The MAUI Application |
|||
|
|||
This is the mobile application that is built based on Microsoft's [MAUI framework](https://learn.microsoft.com/en-us/dotnet/maui). It will be in the solution only if you've selected the MAUI as your mobile application option. |
|||
|
|||
#### Project Structure |
|||
Entire MAUI application is built on the AppShell pattern of MAUI. You can find the AppShell class in the `Acme.Bookstore.Maui` project. It is the entry point of the application. It is responsible for initializing the application and registering the services. You find all the pages and routing information in the `AppShell.xaml` file. |
|||
|
|||
- **Pages**: Pages are located in the `Pages` folder of the project. Each page has a XAML & C# file. XAML file is responsible for the UI and C# file is responsible for the initialization of the page. |
|||
|
|||
- **ViewModels**: ViewModels are located in the `ViewModels` folder of the project. Each ViewModel has a C# file. ViewModels are responsible for the business logic of the pages. |
|||
|
|||
- **Oidc**: Oidc folder contains the logic for the authentication of the application. It contains the `MauiAuthenticationBrowser` class which manages the authentication process of the application. |
|||
|
|||
- **Localization**: Localization folder contains the localization logic of the application. It contains regular ABP Localization logic and the `LocalizationResourceManager` class which is wrapper for the ABP localization logic on MAUI. |
|||
|
|||
- **Messages**: Messages folder contains the message data for the communication inside application. Messages are used to send data between pages and viewmodels. It's designed on the [MVVM Toolkit Messenger](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/messenger) feature. |
|||
|
|||
- **Storage**: Storage folder contains the storage logic of the application. It contains the `IStorage` class which is wrapper for the [SecureStorage](https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/storage/secure-storage) feature. It is used to store the authentication data of the user and preferences of the application. |
|||
|
|||
_Rest of the folders are MAUI default folders. You can check the [.NET MAUI single project documentatipon](https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/single-project?view=net-maui-8.0) for more information._ |
|||
|
|||
#### Running the application |
|||
Before running the MAUI Application, rest of the applications in the solution must be running. Such as AuthServer, MobileGateway and the microservices. |
|||
|
|||
Make sure that you prepared devices for debugging. You can check the following documentation for each platform. |
|||
|
|||
- [Android](https://learn.microsoft.com/en-us/dotnet/maui/android/emulator/) |
|||
- [iOS](https://learn.microsoft.com/en-us/dotnet/maui/ios/pair-to-mac) |
|||
- [MacCatalyst](https://learn.microsoft.com/en-us/dotnet/maui/mac-catalyst/cli) |
|||
- [Windows](https://learn.microsoft.com/en-us/dotnet/maui/windows/setup) |
|||
|
|||
##### Network |
|||
|
|||
All the platforms including iOS, MacCataylst and Windows, runs the applications in the same network of the host. So, you can use the `localhost` address to connect to the applications. |
|||
|
|||
But in the **Android Emulator**, you need to use the `adb reverse` command to connect to the applications. You can use the following command to connect to the AuthServer application: |
|||
|
|||
```bash |
|||
adb reverse tcp:44300 tcp:44300 |
|||
``` |
|||
|
|||
> `44300` is an example port. You need to change it based on the port of the AuthServer & MobileGateway application. |
|||
|
|||
> You need to run the command for a running emulator. If you run the emulator after running the command, you need to run the command again. |
|||
|
|||
|
|||
##### Target Framework |
|||
|
|||
Since MAUI Applications have multiple target frameworks, you need to select the target framework before running the application. You can select the target framework from the context menu of the Solution Runner. |
|||
|
|||
 |
|||
|
|||
##### Running with ABP Studio |
|||
You can start the MAUI application with the solution runner. You can click the start button of the MAUI application in the solution runner tree. It will start the application on the selected target framework. Since they're not running on a process and they're running on a device, you can't see them as running state in the solution runner. After the application is deployed, it'll be opened on the device and it'll be shown as stopped in the solution runner. |
|||
|
|||
#### Development on MAUI Application |
|||
|
|||
You can follow [Mobile Application Development Tutorial - MAUI](../../tutorials/mobile/maui/index.md) to learn how to develop on MAUI Application. |
|||
|
|||
### The React Native Application |
|||
|
|||
This is the mobile application that is built based on Facebook's [React Native framework](https://reactnative.dev/) and [Expo](https://expo.dev/). It will be in the solution only if you've selected React Native as your mobile application option. |
|||
|
|||
#### Project Structure |
|||
- **Environment.js**: file using for provide application level variables like `apiUrl`, `oAuthConfig` and etc. |
|||
|
|||
- **api**: The `api` folder contains HTTP request files that simplify API management in the React Native starter template |
|||
- `API.js:` exports **axiosInstance**. It provides axios instance filled api url |
|||
|
|||
- **components**: In the `components` folder you can reach built in react native components that you can use in your app. These components **facilitates** your list, select and etc. operations |
|||
|
|||
- **contexts**: `contexts` folder contains [react context](https://react.dev/reference/react/createContext). You can expots your contexts in this folder. `Localization context provided in here` |
|||
|
|||
- **navigators**: folder contains [react-native stacks](https://reactnavigation.org/docs/stack-navigator/). After create new *FeatureName*Navigator we need to provide in `DrawerNavigator.js` file as `Drawer.Screen` |
|||
|
|||
- **screens**: is the content of navigated page. We'll pass as component property to [Stack.Screen](https://reactnavigation.org/docs/native-stack-navigator/) |
|||
|
|||
- **store**: folder manages state-management operations. We will define `actions`, `reducers`, `sagas` and `selectors` here. |
|||
|
|||
- **styles**: folder contains app styles. `system-style.js` comes built in template we can also add new styles. |
|||
|
|||
- **utils**: folder contains helper functions that we can use in application |
|||
|
|||
#### Running the Application |
|||
|
|||
React Native applications can't be run with the solution runner. You need to run them with the React Native CLI. You can check the [React Native documentation](https://reactnative.dev/docs/environment-setup) to learn how to setup the environment for React Native development. |
|||
|
|||
Before running the React Native application, rest of the applications in the solution must be running. Such as AuthServer, MobileGateway and the microservices. |
|||
|
|||
Then you can run the React Native application by following this documentation: [Getting Started with the React Native](../../framework/ui/react-native/index.md). |
|||
@ -0,0 +1,74 @@ |
|||
# Layered Solution: Multi-Tenancy |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Swagger integration", |
|||
"Path": "solution-templates/layered-web-application/swagger-integration" |
|||
}, |
|||
"Next": { |
|||
"Name": "BLOB storing", |
|||
"Path": "solution-templates/layered-web-application/blob-storing" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
|||
|
|||
Multi-tenancy is a software architecture where a single instance(codebase) of software runs on a server and serves multiple tenants. Tenants are isolated from each other and can have their own data, configurations, and users. This document explains how the multi-tenancy mechanism works in the layered solution template. You can learn more about multi-tenancy in the [Multi-Tenancy](../../framework/architecture/multi-tenancy/index.md), [Tenant Management](../../modules/tenant-management.md) and [SaaS **\***](../../modules/saas.md) documents. |
|||
|
|||
## Multi-Tenancy in Layered Solutions |
|||
|
|||
The layered solution templates use the *Multi-Tenancy* architecture only if you *Enable Multi-Tenancy **\**** option while creating the solution. |
|||
|
|||
 |
|||
|
|||
You can use different databases for each tenant or a shared database for all tenants. In the *SaaS **\*** module, you can specify the database connection strings in the [Connection Strings Management Modal](../../modules/saas.md#connection-string). All cached data is isolated by tenant. Each event, background job, and other data is stored with the tenant id. |
|||
|
|||
You can use the `ICurrentTenant` service to get the current tenant information in your application. |
|||
|
|||
```csharp |
|||
public class MyService : ITransientDependency |
|||
{ |
|||
private readonly ICurrentTenant _currentTenant; |
|||
|
|||
public MyService(ICurrentTenant currentTenant) |
|||
{ |
|||
_currentTenant = currentTenant; |
|||
} |
|||
|
|||
public void MyMethod() |
|||
{ |
|||
var tenantId = _currentTenant.Id; |
|||
var tenantName = _currentTenant.Name; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Additionally, you can use the [DataFilter](../../framework/infrastructure/data-filtering.md#idatafilter-service-enabledisable-data-filters) system to disable the tenant filter and list all data in the same database. |
|||
|
|||
```csharp |
|||
public class MyBookService : ITransientDependency |
|||
{ |
|||
private readonly IDataFilter<IMultiTenant> _multiTenantFilter; |
|||
private readonly IRepository<Book, Guid> _bookRepository; |
|||
|
|||
public MyBookService( |
|||
IDataFilter<IMultiTenant> multiTenantFilter, |
|||
IRepository<Book, Guid> bookRepository) |
|||
{ |
|||
_multiTenantFilter = multiTenantFilter; |
|||
_bookRepository = bookRepository; |
|||
} |
|||
|
|||
public async Task<List<Book>> GetAllBooksIncludingDeletedAsync() |
|||
{ |
|||
//Temporary disable the IMultiTenant filter |
|||
using (_multiTenantFilter.Disable()) |
|||
{ |
|||
return await _bookRepository.GetListAsync(); |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
@ -0,0 +1,108 @@ |
|||
# Layered Solution: Overview |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Index", |
|||
"Path": "solution-templates/layered-web-application/index" |
|||
}, |
|||
"Next": { |
|||
"Name": "Solution Structure", |
|||
"Path": "solution-templates/layered-web-application/solution-structure" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
|||
|
|||
|
|||
In this document, you will learn what the Layered solution template offers to you. |
|||
|
|||
## Pre-Installed Libraries & Services |
|||
|
|||
The following **libraries and services** come **pre-installed** and **configured** for both **development** and **production** environments. After creating your solution, you can **modify** or **remove** most of them as needed. |
|||
|
|||
* **[Autofac](https://autofac.org/)** for [Dependency Injection](../../framework/fundamentals/dependency-injection.md). |
|||
* **[Serilog](https://serilog.net/)** with File and Console [logging](../../framework/fundamentals/logging.md) providers. |
|||
* **[Redis](https://redis.io/)** for [distributed caching](../../framework/fundamentals/caching.md). Redis is used for distributed caching if you select the *Public Website* **\*** or *Tiered* **\*** option. |
|||
* **[Swagger](https://swagger.io/)** for exploring and testing HTTP APIs. |
|||
* **[OpenIddict](https://github.com/openiddict/openiddict-core)** as the built-in authentication server. |
|||
|
|||
## Pre-Configured Features |
|||
|
|||
The following features are built and pre-configured for you in the solution. |
|||
|
|||
* **Authentication** is fully configured based on best practices. |
|||
* **[Permission](../../framework/fundamentals/authorization.md)** (authorization), **[setting](../../framework/infrastructure/settings.md)**, **[feature](../../framework/infrastructure/features.md)** and the **[localization](../../framework/fundamentals/localization.md)** management systems are pre-configured and ready to use. |
|||
* **[Background job system](../../framework/infrastructure/background-jobs/index.md)**. |
|||
* **[BLOB storge](../../framework/infrastructure/blob-storing/index.md)** system is installed with the [database provider](../../framework/infrastructure/blob-storing/database.md). |
|||
* **On-the-fly database migration** system (services automatically migrated their database schema when you deploy a new version). **\*** |
|||
* **[Helm](https://helm.sh/)** charts are included to deploy the solution to **[Kubernetes](https://kubernetes.io/)**. **\*** |
|||
* **[Swagger](https://swagger.io/)** authentication is configured to test the authorized HTTP APIs. |
|||
|
|||
## Fundamental Modules |
|||
|
|||
The following modules are pre-installed and configured for the solution: |
|||
|
|||
* **[Account](../../modules/account.md)** to authenticate users (login, register, two factor auth **\***, etc) |
|||
* **[Identity](../../modules/identity.md)** to manage roles and users |
|||
* **[OpenIddict](../../modules/openiddict.md)** (the core part) to implement the OAuth authentication flows |
|||
|
|||
In addition these, [Feature Management](../../modules/feature-management.md), [Permission Management](../../modules/permission-management.md) and [Setting Management](../../modules/setting-management.md) modules are pre-installed as they are the fundamental feature modules of the ABP. |
|||
|
|||
## Optional Modules |
|||
|
|||
The following modules are optionally included in the solution, so you can select the ones you need: |
|||
|
|||
* **[Audit Logging](../../modules/audit-logging.md)** |
|||
* **[Chat](../../modules/chat.md)** **\*** |
|||
* **[File Management](../../modules/file-management.md)** **\*** |
|||
* **[GDPR](../../modules/gdpr.md)** **\*** |
|||
* **[Language Management](../../modules/language-management.md)** **\*** |
|||
* **[OpenIddict (Management UI)](../../modules/openiddict.md)** **\*** |
|||
* **[Tenant Management](../../modules/tenant-management.md) (Multi-Tenancy) or [SaaS](../../modules/saas.md)** **\*** |
|||
* **[Text Template Management](../../modules/text-template-management.md)** **\*** |
|||
|
|||
## UI Theme |
|||
|
|||
The **[LeptonX Lite](../../ui-themes/lepton-x-lite/index.md) or [LeptonX theme](https://leptontheme.com/)** **\*** is pre-configured for the solution. You can select one of the color palettes (System, Light or Dark) as default, while the end-user dynamically change it on the fly. |
|||
|
|||
## Other Options |
|||
|
|||
Layered startup template asks for some preferences while creating your solution. |
|||
|
|||
### Database Providers |
|||
|
|||
There are two database provider options are provided on a new solution creation: |
|||
|
|||
* **[Entity Framework Core](../../framework/data/entity-framework-core/index.md)** with SQL Server, MySQL and PostgreSQL DBMS options. You can [switch to anther DBMS](../../framework/data/entity-framework-core/other-dbms.md) manually after creating your solution. |
|||
* **[MongoDB](../../framework/data/mongodb/index.md)** |
|||
|
|||
### UI Frameworks |
|||
|
|||
The solution comes with a main web application with the following UI Framework options: |
|||
|
|||
* **None** (doesn't include a web application to the solution) |
|||
* **Angular** |
|||
* **MVC / Razor Pages UI** |
|||
* **Blazor WebAssembly** |
|||
* **Blazor Server** |
|||
* **Blazor WebApp** |
|||
* **MAUI with Blazor (Hybrid)** **\*** |
|||
|
|||
### The Mobile Application |
|||
|
|||
If you prefer, the solution includes a mobile application. The mobile application is fully integrated to the system, implements authentication (login) and other ABP features, and includes a few screens that you can use and take as example. The following options are available: |
|||
|
|||
* **None** (doesn't include a mobile application to the solution) |
|||
* **MAUI** **\*** |
|||
* **React Native** **\*** |
|||
|
|||
### Multi-Tenancy & SaaS Module **\*** |
|||
|
|||
The **[SaaS module](../../modules/saas.md)** is included as an option. When you select it, the **[multi-tenancy](../../framework/architecture/multi-tenancy/index.md)** system is automatically configured. Otherwise, the system will not include any multi-tenancy overhead. |
|||
|
|||
## See Also |
|||
|
|||
* [Quick Start: Creating a Layered Web Application with ABP Studio](../../get-started/layered-web-application.md) |
|||
@ -0,0 +1,222 @@ |
|||
# Layered Solution: The Structure |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Overview", |
|||
"Path": "solution-templates/layered-web-application/overview" |
|||
}, |
|||
"Next": { |
|||
"Name": "Main Components", |
|||
"Path": "solution-templates/layered-web-application/main-components" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
|||
|
|||
This document explains the solution and folder structure of ABP Studio's [layered solution template](index.md). |
|||
|
|||
> This document assumes that you've created a new layered solution by following the *[Quick Start: Creating a Layered Web Application with ABP Studio](../../get-started/layered-web-application.md)* guide. (Choose the *Entity Framework Core* as the database provider.) |
|||
|
|||
## Understanding the ABP Solution Structure |
|||
|
|||
When you create a new layered solution, you will see a tree structure similar to the one below in the *Solution Explorer* panel: |
|||
|
|||
 |
|||
|
|||
`Acme.Bookstore` is the main **ABP Studio module** of the solution. It includes two folders: `src` and `test`, as shown in the image above. The `src` folder contains the source code of the solution, which is structured according to [DDD](../../framework/architecture/domain-driven-design/index.md) principles, while the `test` folder holds the unit and integration tests. |
|||
|
|||
> Refer to the *[Concepts](../../studio/concepts.md)* document for a comprehensive definition of ABP Studio solution, module, and package terms. |
|||
|
|||
## Exploring the Folder Structure |
|||
|
|||
You can right-click the root item in the solution explorer (`Acme.Bookstore` for this example) and select the *Open with* -> *Explorer* command to open the folder containing the solution in your file system: |
|||
|
|||
 |
|||
|
|||
The root folder of the solution will be similar to the following: |
|||
|
|||
 |
|||
|
|||
* `.abpstudio` folder stores your personal preferences for this solution and is excluded from source control (Git ignored). It is created and used by ABP Studio. |
|||
* `etc` folder contains additional files for the solution, organized into the following sub-folders: |
|||
* `abp-studio` folder holds settings managed by ABP Studio. This folder is included in source control and shared among developers. |
|||
* `docker` folder provides docker-compose configurations to easily run infrastructure dependencies (e.g., RabbitMQ, Redis) for the solution on your local machine. |
|||
* `helm` folder contains Helm charts and related scripts for deploying the solution to Kubernetes. **\*** |
|||
* `src` folder contains the solution's source code, structured according to [DDD](../../framework/architecture/domain-driven-design/index.md) principles. It also includes database migrations and, depending on your project creation options, may include mobile and web application projects. |
|||
* `test` folder contains unit and integration tests for the solution. |
|||
|
|||
## Understanding the Layered Solution Structure |
|||
|
|||
The diagram below illustrates the application's layers and project dependencies: |
|||
|
|||
 |
|||
|
|||
### .Domain.Shared Project |
|||
|
|||
This project contains constants, enums and other objects these are actually a part of the domain layer, but needed to be used by all layers/projects in the solution. |
|||
|
|||
A `BookType` enum and a `BookConsts` class (which may have some constant fields for the `Book` entity, like `MaxNameLength`) are good candidates for this project. |
|||
|
|||
* This project has no dependency on other projects in the solution. All other projects depend on this one directly or indirectly. |
|||
|
|||
### .Domain Project |
|||
|
|||
This is the domain layer of the solution. It mainly contains [entities, aggregate roots](../../framework/architecture/domain-driven-design/entities.md), [domain services](../../framework/architecture/domain-driven-design/domain-services.md), [value objects](../../framework/architecture/domain-driven-design/value-objects.md), [repository interfaces](../../framework/architecture/domain-driven-design/repositories.md) and other domain objects. |
|||
|
|||
A `Book` entity, a `BookManager` domain service and an `IBookRepository` interface are good candidates for this project. |
|||
|
|||
* Depends on the `.Domain.Shared` because it uses constants, enums and other objects defined in that project. |
|||
|
|||
### .Application.Contracts Project |
|||
|
|||
This project mainly contains [application service](../../framework/architecture/domain-driven-design/application-services.md) **interfaces** and [Data Transfer Objects](../../framework/architecture/domain-driven-design/data-transfer-objects.md) (DTO) of the application layer. It exists to separate the interface & implementation of the application layer. In this way, the interface project can be shared to the clients as a contract package. |
|||
|
|||
An `IBookAppService` interface and a `BookCreationDto` class are good candidates for this project. |
|||
|
|||
* Depends on the `.Domain.Shared` because it may use constants, enums and other shared objects of this project in the application service interfaces and DTOs. |
|||
|
|||
### .Application Project |
|||
|
|||
This project contains the [application service](../../framework/architecture/domain-driven-design/application-services.md) **implementations** of the interfaces defined in the `.Application.Contracts` project. |
|||
|
|||
A `BookAppService` class is a good candidate for this project. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to implement the interfaces and use the DTOs. |
|||
* Depends on the `.Domain` project to be able to use domain objects (entities, repository interfaces... etc.) to perform the application logic. |
|||
|
|||
### .EntityFrameworkCore Project |
|||
|
|||
This is the integration project for the EF Core. It defines the `DbContext` and implements repository interfaces defined in the `.Domain` project. |
|||
|
|||
* Depends on the `.Domain` project to be able to reference to entities and repository interfaces. |
|||
|
|||
> This project is available only if you are using EF Core as the database provider. If you select another database provider, its name will be different. |
|||
|
|||
### .DbMigrator Project |
|||
|
|||
This is a console application that simplifies the execution of database migrations on development and production environments. When you run this application, it: |
|||
|
|||
* Creates the database if necessary. |
|||
* Applies the pending database migrations. |
|||
* Seeds initial data if needed. |
|||
|
|||
> This project has its own `appsettings.json` file. So, if you want to change the database connection string, remember to change this file too. |
|||
|
|||
Especially, seeding initial data is important at this point. ABP has a modular data seed infrastructure. See [its documentation](../../framework/infrastructure/data-seeding.md) for more about the data seeding. |
|||
|
|||
While creating database & applying migrations seem only necessary for relational databases, this project comes even if you choose a NoSQL database provider (like MongoDB). In that case, it still seeds the initial data which is necessary for the application. |
|||
|
|||
* Depends on the `.EntityFrameworkCore` project (for EF Core) since it needs to access to the migrations. |
|||
* Depends on the `.Application.Contracts` project to be able to access permission definitions, because the initial data seeder grants all permissions to the admin role by default. |
|||
|
|||
### .HttpApi Project |
|||
|
|||
This project is used to define your API Controllers. |
|||
|
|||
Most of the time you don't need to manually define API Controllers since ABP's [Auto API Controllers](../../framework/api-development/auto-controllers.md) feature creates them automagically based on your application layer. However, in case of you need to write API controllers, this is the best place to do it. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to inject the application service interfaces. |
|||
|
|||
### .HttpApi.Client Project |
|||
|
|||
This is a project that defines C# client proxies to use the HTTP APIs of the solution. You can share this library to 3rd-party clients, so they can easily consume your HTTP APIs in their Dotnet applications (For other types of applications, they can still use your APIs, either manually or using a tool in their own platform) |
|||
|
|||
Most of the time you don't need to manually create C# client proxies, thanks to ABP's [Dynamic C# API Clients](../../framework/api-development/dynamic-csharp-clients.md) feature. |
|||
|
|||
`.HttpApi.Client.ConsoleTestApp` project is a console application created to demonstrate the usage of the client proxies. |
|||
|
|||
* Depends on the `.Application.Contracts` project to be able to share the same application service interfaces and DTOs with the remote service. |
|||
|
|||
> You can delete this project & dependencies if you don't need to create C# client proxies for your APIs. |
|||
|
|||
### .Web Project |
|||
|
|||
This project contains the User Interface (UI) of the application if you are using ASP.NET Core MVC UI. It contains Razor pages, JavaScript files, CSS files, images and so on... |
|||
|
|||
This project contains the main `appsettings.json` file that contains the connection string and other configurations of the application. |
|||
|
|||
* Depends on the `.HttpApi` project since the UI layer needs to use APIs and the application service interfaces of the solution. |
|||
|
|||
> If you check the source code of the `.Web.csproj` file, you will see the references to the `.Application` and the `.EntityFrameworkCore` projects. |
|||
> |
|||
> These references are actually not needed while coding your UI layer, because the UI layer normally doesn't depend on the EF Core or the Application layer's implementation. These startup templates are ready for tiered deployment, where the API layer is hosted on a separate server than the UI layer. |
|||
> |
|||
> However, if you don't choose the `--tiered` option, these references will be in the .Web project to be able to host the Web, API and application layers in a single application endpoint. |
|||
> |
|||
> This gives you the ability to use domain entities & repositories in your presentation layer. However, this is considered as a bad practice according to DDD. |
|||
|
|||
### Test Projects |
|||
|
|||
The solution has multiple test projects, one for each layer: |
|||
|
|||
* `.Domain.Tests` is used to test the domain layer. |
|||
* `.Application.Tests` is used to test the application layer. |
|||
* `.EntityFrameworkCore.Tests` is used to test EF Core configuration and custom repositories. |
|||
* `.Web.Tests` is used to test the UI (if you are using ASP.NET Core MVC UI). |
|||
* `.TestBase` is a base (shared) project for all tests. |
|||
|
|||
In addition, `.HttpApi.Client.ConsoleTestApp` is a console application (not an automated test project) which demonstrate the usage of HTTP APIs from a .NET application. |
|||
|
|||
Test projects are prepared for integration testing; |
|||
|
|||
* It is fully integrated into the ABP and all services in your application. |
|||
* It uses SQLite in-memory database for EF Core. For MongoDB, it uses the [EphemeralMongo](https://github.com/asimmon/ephemeral-mongo) library. |
|||
* Authorization is disabled, so any application service can be easily used in tests. |
|||
|
|||
You can still create unit tests for your classes which will be harder to write (because you will need to prepare mock/fake objects), but faster to run (because it only tests a single class and skips all the initialization processes). |
|||
|
|||
### How to Run? |
|||
|
|||
You can open the [Solution Runner](../../studio/running-applications.md) panel and start the all applications. The default username is `admin` and the password is `1q2w3E*`. |
|||
|
|||
 |
|||
|
|||
See [Getting Started With the ASP.NET Core MVC Template](../../get-started/layered-web-application.md) for more information. |
|||
|
|||
## Tiered Structure **\*** |
|||
|
|||
If you have selected the ASP.NET Core UI and specified the `--tiered` option, the solution created will be a tiered solution. The purpose of the tiered structure is to be able to **deploy Web applications and HTTP API to different servers**: |
|||
|
|||
 |
|||
|
|||
* Browser runs your UI by executing HTML, CSS & JavaScript. |
|||
* Web servers host static UI files (CSS, JavaScript, image... etc.) & dynamic components (e.g. Razor pages). It performs HTTP requests to the API server to execute the business logic of the application. |
|||
* The API Server hosts the HTTP APIs which then use the application & domain layers of the application to perform the business logic. |
|||
* Finally, database server hosts your database. |
|||
|
|||
> Unless you actually need such a 4-tiered deployment, it's suggested to go with the default structure which is simpler to develop, deploy and maintain. |
|||
|
|||
The solution structure is shown below: |
|||
|
|||
 |
|||
|
|||
As different from the default structure, two new projects come into play: `.AuthServer` & `.HttpApi.Host`. |
|||
|
|||
### .AuthServer Project |
|||
|
|||
This project is used as an authentication server for other projects. `.Web` project uses OpenId Connect Authentication to get identity and access tokens for the current user from the AuthServer. Then uses the access token to call the HTTP API server. HTTP API server uses bearer token authentication to obtain claims from the access token to authorize the current user. |
|||
|
|||
 |
|||
|
|||
ABP uses the [OpenIddict Module](../../modules/openiddict.md) that uses the open-source [OpenIddict-core](https://github.com/openiddict/openiddict-core) library for the authentication between applications. See [OpenIddict documentation](https://documentation.openiddict.com/) for details about the OpenIddict and OpenID Connect protocol. |
|||
|
|||
It has its own `appsettings.json` that contains database connection and other configurations. |
|||
|
|||
### .HttpApi.Host Project |
|||
|
|||
This project is an application that hosts the API of the solution. It has its own `appsettings.json` that contains database connection and other configurations. |
|||
|
|||
### .Web Project |
|||
|
|||
Just like the default structure, this project contains the User Interface (UI) of the application. It contains razor pages, JavaScript files, style files, images and so on... |
|||
|
|||
This project contains an `appsettings.json` file, but this time it does not have a connection string because it never connects to the database. Instead, it mainly contains the endpoint of the remote API server and the authentication server. |
|||
|
|||
### How to Run? |
|||
|
|||
You can open the [Solution Runner](../../studio/running-applications.md) panel and start the all applications. The default username is `admin` and the password is `1q2w3E*`. |
|||
|
|||
 |
|||
@ -0,0 +1,19 @@ |
|||
# Layered Solution: Swagger Integration |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Logging (with Serilog)", |
|||
"Path": "solution-templates/layered-web-application/logging" |
|||
}, |
|||
"Next": { |
|||
"Name": "Multi-Tenancy", |
|||
"Path": "solution-templates/layered-web-application/multi-tenancy" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
[Swagger](https://swagger.io/) is a tool that helps to create, document, and consume RESTful web services. It provides a user interface to interact with the APIs and also a way to generate client SDKs for the APIs. |
|||
|
|||
In the [Swagger Integration](../../framework/api-development/swagger.md) document, you can find general information about Swagger integration with ABP Framework. |
|||
@ -0,0 +1,178 @@ |
|||
# Layered Solution: Web Applications |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Main Components", |
|||
"Path": "solution-templates/layered-web-application/main-components" |
|||
}, |
|||
"Next": { |
|||
"Name": "Db Migrator", |
|||
"Path": "solution-templates/layered-web-application/db-migrator" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
|||
|
|||
The web applications are the main user interfaces of the solution. They are the entry points for users to interact with the system. The Layered Solution Template supports the following web applications: |
|||
|
|||
- **MVC / Razor Pages**: This is an ASP.NET Core MVC application. It is a traditional web application that serves HTML pages to users and is suitable for building web applications with server-side rendering. |
|||
- **Angular**: This is an Angular application, a single-page application (SPA) that runs on the client side. It communicates with the server using HTTP requests and is ideal for building modern web applications with rich user interfaces. |
|||
- **Blazor UI**: A flexible framework for building web applications with .NET. It supports various hosting models: |
|||
- **Blazor WebAssembly**: This is a client-side SPA that runs entirely in the user's browser. It communicates with the server using HTTP requests and is suitable for modern web applications with rich interactivity and offline capabilities. |
|||
- **Blazor Server**: This is a server-side SPA that runs on the server and communicates with the client in real time using SignalR. It is ideal for applications requiring constant connectivity and rapid server updates. |
|||
- **Blazor WebApp**: This is a combination of Blazor technologies optimized for building hybrid web applications that can leverage both client-side and server-side capabilities. |
|||
- **Maui Blazor (Hybrid)** **\***: This enables building cross-platform applications that combine Blazor for the UI with .NET MAUI for native device integration. It is suitable for building apps that work across desktop and mobile platforms. |
|||
- **No UI**: This option creates a backend-only solution without a web interface, suitable for scenarios like API-only applications or headless services. |
|||
|
|||
You can select the web application type that fits your requirements during the solution creation process in the *UI Framework* step. The Layered Solution Template generates the selected web applications with the necessary configurations and integrations. |
|||
|
|||
 |
|||
|
|||
## MVC / Razor Pages |
|||
|
|||
MVC (Model-View-Controller) is a design pattern commonly used for building web applications. Razor Pages, on the other hand, is a page-based programming model designed to make building web applications simpler and more productive. |
|||
|
|||
When you select the MVC / Razor Pages option in the Layered Solution Template, it generates an ASP.NET Core MVC application named something like `Acme.BookStore.Web`. This application serves as the web interface for your solution, using server-side rendering to deliver dynamic HTML pages to users. |
|||
|
|||
## Angular |
|||
|
|||
Angular is a popular front-end framework for building single-page applications (SPAs). It offers a rich set of features for creating modern web applications with dynamic and interactive user interfaces. |
|||
|
|||
When you select the Angular option in the Layered Solution Template, it generates: |
|||
- An Angular application located under the solution's root folder, typically named `angular`. |
|||
- An ASP.NET Core application, usually named something like `Acme.Bookstore.HttpApi.Host`. |
|||
|
|||
The Angular application runs as a client-side SPA in the user's browser and communicates with the server by sending HTTP requests to the `*.HttpApi.Host` application. |
|||
|
|||
 |
|||
|
|||
Each of ABP modules is an NPM package. Some ABP modules are added as a dependency in `package.json`. These modules install with their dependencies. To see all ABP packages, you can run the following command in the `angular` folder: |
|||
|
|||
```bash |
|||
yarn list --pattern abp |
|||
``` |
|||
|
|||
Angular application module structure: |
|||
|
|||
 |
|||
|
|||
### AppModule |
|||
|
|||
`AppModule` is the root module of the application. Some of the ABP modules and some essential modules are imported to `AppModule`. |
|||
|
|||
ABP Config modules have also been imported to `AppModule` for initial requirements of the lazy-loadable ABP modules. |
|||
|
|||
### AppRoutingModule |
|||
|
|||
There are lazy-loadable ABP modules in the `AppRoutingModule` as routes. |
|||
|
|||
> Paths of ABP Modules should not be changed. |
|||
|
|||
You should add `routes` property in the `data` object to add a link on the menu to redirect to your custom pages. |
|||
|
|||
```js |
|||
{ |
|||
path: 'dashboard', |
|||
loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule), |
|||
canActivate: [authGuard, permissionGuard], |
|||
data: { |
|||
routes: { |
|||
name: 'ProjectName::Menu:Dashboard', |
|||
order: 2, |
|||
iconClass: 'fa fa-dashboard', |
|||
requiredPolicy: 'ProjectName.Dashboard.Host' |
|||
} as ABP.Route |
|||
} |
|||
} |
|||
``` |
|||
In the above example; |
|||
* If the user is not logged in, authGuard blocks access and redirects to the login page. |
|||
* permissionGuard checks the user's permission with the `requiredPolicy` property of the `routes` object. If the user is not authorized to access the page, the 403 page appears. |
|||
* The `name` property of `routes` is the menu link label. A localization key can be defined. |
|||
* The `iconClass` property of the `routes` object is the menu link icon class. |
|||
* The `requiredPolicy` property of the `routes` object is the required policy key to access the page. |
|||
|
|||
After the above `routes` definition, if the user is authorized, the dashboard link will appear on the menu. |
|||
|
|||
### Shared Module |
|||
|
|||
The modules that may be required for all modules have been imported to the `SharedModule`. You should import `SharedModule` to all modules. |
|||
|
|||
See the [Sharing Modules](https://angular.io/guide/sharing-ngmodules) document. |
|||
|
|||
### Environments |
|||
|
|||
The files under the `src/environments` folder have the essential configuration of the application. |
|||
|
|||
### Home Module |
|||
|
|||
Home module is an example lazy-loadable module that loads on the root address of the application. |
|||
|
|||
### Styles |
|||
|
|||
The required style files are added to the `styles` array in `angular.json`. `AppComponent` loads some style files lazily via `LazyLoadService` after the main bundle is loaded to shorten the first rendering time. |
|||
|
|||
### Testing |
|||
|
|||
You should create your tests in the same folder as the file you want to test. |
|||
|
|||
See the [testing document](https://angular.io/guide/testing). |
|||
|
|||
### Depended Packages |
|||
|
|||
* [NG Bootstrap](https://ng-bootstrap.github.io/) is used as UI component library. |
|||
* [NGXS](https://www.ngxs.io/) is used as state management library. |
|||
* [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc) is used to support for OAuth 2 and OpenId Connect (OIDC). |
|||
* [Chart.js](https://www.chartjs.org/) is used to create widgets. |
|||
* [ngx-validate](https://github.com/ng-turkey/ngx-validate) is used for dynamic validation of reactive forms. |
|||
|
|||
## Blazor UI |
|||
|
|||
Blazor is a flexible framework for building web applications with .NET. It supports various hosting models, including Blazor WebAssembly, Blazor Server, Blazor WebApp, and Maui Blazor (Hybrid). |
|||
|
|||
### Blazor WebAssembly |
|||
|
|||
Blazor WebAssembly is a client-side SPA that runs entirely in the user's browser. It communicates with the server using HTTP requests and is suitable for modern web applications with rich interactivity and offline capabilities. |
|||
|
|||
When you select the Blazor WebAssembly option in the Layered Solution Template, it generates: |
|||
- A Blazor application located under the solution's root folder, typically named `*.Blazor`, which serves as the main Blazor host project. |
|||
- A Blazor client application, named `*.Blazor.Client`, where you can write the client-side (UI logic) code. |
|||
- An ASP.NET Core application, named `*.HttpApi.Host`, where the server-side (business logic) code runs. |
|||
|
|||
The Blazor client application communicates with the server by sending HTTP requests to the `*.HttpApi.Host` application. |
|||
|
|||
### Blazor Server |
|||
|
|||
Blazor Server is a server-side SPA that runs on the server and communicates with the client in real time using SignalR. It is ideal for applications requiring constant connectivity and rapid server updates. |
|||
|
|||
When you select the Blazor Server option in the Layered Solution Template, it generates: |
|||
- A Blazor application located under the solution's root folder, typically named `*.Blazor`, which serves as the main Blazor host project. |
|||
|
|||
### Blazor WebApp |
|||
|
|||
Blazor WebApp is a combination of Blazor technologies optimized for building hybrid web applications that can leverage both client-side and server-side capabilities. |
|||
|
|||
When you select the Blazor WebApp option in the Layered Solution Template, it generates: |
|||
- A Blazor application located under the solution's root folder, typically named `*.Blazor`, which serves as the main Blazor host project. |
|||
- A Blazor client application, named `*.Blazor.Client`, where you can write the client-side (UI logic) code. |
|||
|
|||
The Blazor client application communicates with the server by sending HTTP requests to the `*.Blazor` application. |
|||
|
|||
### Maui Blazor (Hybrid) **\*** |
|||
|
|||
Maui Blazor (Hybrid) enables building cross-platform applications that combine Blazor for the UI with .NET MAUI for native device integration. It is suitable for building apps that work across desktop and mobile platforms. |
|||
|
|||
When you select the Maui Blazor (Hybrid) option in the Layered Solution Template, it generates: |
|||
- A Maui Blazor (Hybrid) application located under the solution's root folder, typically named `*.MauiBlazor`, which serves as the main UI host project. |
|||
- An ASP.NET Core application, named `*.HttpApi.Host`, where the server-side (business logic) code runs. |
|||
|
|||
The Maui Blazor (Hybrid) application communicates with the server by sending HTTP requests to the `*.HttpApi.Host` application. |
|||
|
|||
## No UI |
|||
|
|||
This option creates a backend-only solution without a web interface, suitable for scenarios like API-only applications or headless services. |
|||
|
|||
When you select the No UI option in the Layered Solution Template, it generates an ASP.NET Core application named `*.HttpApi.Host` that serves as the backend API for your solution. |
|||
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 13 KiB |
|
Before Width: | Height: | Size: 37 KiB After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 47 KiB After Width: | Height: | Size: 22 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 14 KiB |
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 14 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 9.1 KiB After Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 8.7 KiB After Width: | Height: | Size: 6.5 KiB |
|
Before Width: | Height: | Size: 13 KiB After Width: | Height: | Size: 13 KiB |
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 16 KiB |
@ -0,0 +1 @@ |
|||
Read this document [here](../../framework/ui/mvc-razor-pages/basic-theme.md). |
|||
@ -0,0 +1,10 @@ |
|||
namespace Volo.Abp.AspNetCore.Auditing; |
|||
|
|||
public class AbpAspNetCoreAuditingUrlOptions |
|||
{ |
|||
public bool IncludeSchema { get; set; } |
|||
|
|||
public bool IncludeHost { get; set; } |
|||
|
|||
public bool IncludeQuery { get; set; } |
|||
} |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue