mirror of https://github.com/abpframework/abp.git
SALİH ÖZKARA
2 years ago
154 changed files with 7321 additions and 919 deletions
@ -1,83 +1,72 @@ |
|||
# Blazor UI: Managing Global Scripts & Styles |
|||
|
|||
Some modules may require additional styles or scripts that need to be referenced in **index.html** file. It's not easy to find and update these types of references in Blazor apps. ABP offers a simple, powerful, and modular way to manage global style and scripts in Blazor apps. |
|||
You can add your JavaScript and CSS files from your modules or applications to the Blazor global assets system. All the JavaScript and CSS files will be added to the `global.js` and `global.css` files. You can access these files via the following URL in a Blazor WASM project: |
|||
|
|||
To update script & style references without worrying about dependencies, ordering, etc in a project, you can use the [bundle command](../../../cli#bundle). |
|||
- https://localhost/global.js |
|||
- https://localhost/global.css |
|||
|
|||
You can also add custom styles and scripts and let ABP manage them for you. In your Blazor project, you can create a class implementing `IBundleContributor` interface. |
|||
## Add JavaScript and CSS to the global assets system in the module |
|||
|
|||
`IBundleContributor` interface contains two methods. |
|||
Your module project solution will have two related Blazor projects: |
|||
|
|||
* `AddScripts(...)` |
|||
* `AddStyles(...)` |
|||
* `MyModule.Blazor`：This project includes the JavaScript/CSS files required for your Blazor components. The `MyApp.Blazor.Client (Blazor WASM)` project will reference this project. |
|||
* `MyModule.Blazor.WebAssembly.Bundling`：This project is used to add your JavaScript/CSS files to the Blazor global resources. The `MyModule.Blazor (ASP.NET Core)` project will reference this project. |
|||
|
|||
Both methods get `BundleContext` as a parameter. You can add scripts and styles to the `BundleContext` and run [bundle command](../../../cli#bundle). Bundle command detects custom styles and scripts with module dependencies and updates `index.html` file. |
|||
You need to define JavaScript and CSS contributor classes in the `MyModule.Blazor.WebAssembly.Bundling` project to add the files to the global assets system. |
|||
|
|||
## Example Usage |
|||
```csharp |
|||
namespace MyProject.Blazor |
|||
> Please use `BlazorWebAssemblyStandardBundles.Scripts.Global` and `BlazorWebAssemblyStandardBundles.Styles.Global` for the bundle name. |
|||
|
|||
```cs |
|||
public class MyModuleBundleScriptContributor : BundleContributor |
|||
{ |
|||
public class MyProjectBundleContributor : IBundleContributor |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
public void AddScripts(BundleContext context) |
|||
{ |
|||
context.Add("site.js"); |
|||
} |
|||
|
|||
public void AddStyles(BundleContext context) |
|||
{ |
|||
context.Add("main.css"); |
|||
context.Add("custom-styles.css"); |
|||
} |
|||
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.js"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> There is a BundleContributor class implementing `IBundleContributor` interface coming by default with the startup templates. So, most of the time, you don't need to add it manually. |
|||
|
|||
## Bundling And Minification |
|||
`abp bundle` command offers bundling and minification support for client-side resources(JavaScript and CSS files). `abp bundle` command reads the `appsettings.json` file inside the Blazor project and bundles the resources according to the configuration. You can find the bundle configurations inside `AbpCli.Bundle` element. |
|||
|
|||
Here are the options that you can control inside the `appsettings.json` file. |
|||
|
|||
`Mode`: Bundling and minification mode. Possible values are |
|||
* `BundleAndMinify`: Bundle all the files into a single file and minify the content. |
|||
* `Bundle`: Bundle all files into a single file, but not minify. |
|||
* `None`: Add files individually, do not bundle. |
|||
|
|||
`Name`: Bundle file name. Default value is `global`. |
|||
|
|||
`Parameters`: You can define additional key/value pair parameters inside this section. `abp bundle` command automatically sends these parameters to the bundle contributors, and you can check these parameters inside the bundle contributor, take some actions according to these values. |
|||
|
|||
Let's say that you want to exclude some resources from the bundle and control this action using the bundle parameters. You can add a parameter to the bundle section like below. |
|||
|
|||
```json |
|||
"AbpCli": { |
|||
"Bundle": { |
|||
"Mode": "BundleAndMinify", /* Options: None, Bundle, BundleAndMinify */ |
|||
"Name": "global", |
|||
"Parameters": { |
|||
"ExcludeThemeFromBundle":"true" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can check this parameter and take action like below. |
|||
|
|||
```csharp |
|||
public class MyProjectNameBundleContributor : IBundleContributor |
|||
```cs |
|||
public class MyModuleBundleStyleContributor : BundleContributor |
|||
{ |
|||
public void AddScripts(BundleContext context) |
|||
public override void ConfigureBundle(BundleConfigurationContext context) |
|||
{ |
|||
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/mystyle.css"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
public void AddStyles(BundleContext context) |
|||
```cs |
|||
[DependsOn( |
|||
typeof(AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule) |
|||
)] |
|||
public class MyBlazorWebAssemblyBundlingModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
var excludeThemeFromBundle = bool.Parse(context.Parameters.GetValueOrDefault("ExcludeThemeFromBundle")); |
|||
context.Add("mytheme.css", excludeFromBundle: excludeThemeFromBundle); |
|||
context.Add("main.css"); |
|||
Configure<AbpBundlingOptions>(options => |
|||
{ |
|||
// Add script bundle |
|||
options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global) |
|||
.AddContributors(typeof(MyModuleBundleScriptContributor)); |
|||
|
|||
// Add style bundle |
|||
options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global) |
|||
.AddContributors(typeof(MyModuleBundleStyleContributor)); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Add JavaScript and CSS to the global assets system in the application |
|||
|
|||
This is similar to the module. You need to define JavaScript and CSS contributor classes in the `MyApp.Blazor.Client` project to add the files to the global assets system. |
|||
|
|||
## AbpBundlingGlobalAssetsOptions |
|||
|
|||
You can configure the JavaScript and CSS file names in the `GlobalAssets` property of the `AbpBundlingOptions` class. The default values are `global.js` and `global.css`. |
|||
|
|||
## Reference |
|||
|
|||
- [ASP.NET Core MVC Bundling & Minification](../mvc-razor-pages/bundling-minification#bundle-contributorsg) |
|||
- [ABP Global Assets - New way to bundle JavaScript/CSS files in Blazor WebAssembly app](https://github.com/abpframework/abp/blob/dev/docs/en/Community-Articles/2024-11-25-Global-Assets/POST.md) |
|||
|
|||
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
After Width: | Height: | Size: 70 KiB |
|
After Width: | Height: | Size: 37 KiB |
|
After Width: | Height: | Size: 112 KiB |
|
After Width: | Height: | Size: 44 KiB |
|
After Width: | Height: | Size: 99 KiB |
|
After Width: | Height: | Size: 59 KiB |
@ -1,465 +0,0 @@ |
|||
# 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,59 @@ |
|||
# Single Layer Application Solution Template |
|||
|
|||
This template provides a simple solution structure with a single project. This document explains that solution structure in details. |
|||
|
|||
## Getting Started |
|||
|
|||
* Follow the [Getting Started guide](../../get-started/single-layer-web-application.md) to create a new solution using this startup solution template. |
|||
* Follow the [TODO application tutorial](../../tutorials/todo/single-layer/index.md) to learn how to create a simple application with this startup solution template. |
|||
|
|||
## The Solution Structure |
|||
|
|||
If you created your solution with the default options, you will have a .NET solution as shown below: |
|||
|
|||
 |
|||
|
|||
In the next sections, we will explain the structure based on this example. Your startup solution can be slightly different based on your preferences. |
|||
|
|||
### Folder Structure |
|||
|
|||
Since this template provides a single-project solution, we've separated concerns into folders instead of projects. You can see the pre-defined folders as shown below: |
|||
|
|||
 |
|||
|
|||
* Define your database mappings (for [EF Core](../../framework/data/entity-framework-core) or [MongoDB](../../framework/data/mongodb) and [repositories](../../framework/architecture/domain-driven-design/repositories.md) in the `Data` folder. |
|||
* Define your [entities](../../framework/architecture/domain-driven-design/entities.md) in the `Entities` folder. |
|||
* Define your UI localization keys/values in the `Localization` folder. |
|||
* Define your UI menu items in the `Menus` folder. |
|||
* Define your [object-to-object mapping](../../framework/infrastructure/object-to-object-mapping.md) classes in the `ObjectMapping` folder. |
|||
* Define your UI pages (Razor Pages) in the `Pages` folder (create `Controllers` and `Views` folder yourself if you prefer the MVC pattern). |
|||
* Define your [application services](../../framework/architecture/domain-driven-design/application-services.md) in the `Services` folder. |
|||
|
|||
### How to Run? |
|||
|
|||
Before running the application, you need to create the database and seed the initial data. To do that, you can run the following command in the directory of your project (in the same folder of the `.csproj` file): |
|||
|
|||
```bash |
|||
dotnet run --migrate-database |
|||
``` |
|||
|
|||
This command will create the database and seed the initial data for you. Then you can run the application with any IDE that supports .NET or by running the `dotnet run` command in the directory of your project. The default username is `admin` and the password is `1q2w3E*`. |
|||
|
|||
> While creating a database & applying migrations seem only necessary for relational databases, you should run this command 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. |
|||
|
|||
### The Angular UI |
|||
|
|||
If you choose `Angular` as the UI framework, the solution will be separated into two folders: |
|||
|
|||
* An `angular` folder that contains the Angular UI application, the client-side code. |
|||
* An `aspnet-core` folder that contains the ASP.NET Core solution (a single project), the server-side code. |
|||
|
|||
The server-side is similar to the solution described in the *Solution Structure* section above. This project serves the API, so the Angular application can consume it. |
|||
|
|||
The client-side application consumes the HTTP APIs as mentioned. You can see the folder structure of the Angular project shown below: |
|||
|
|||
 |
|||
|
|||
## See Also |
|||
|
|||
* [Video tutorial](https://abp.io/video-courses/essentials/app-template) |
|||
@ -0,0 +1,52 @@ |
|||
# Single Layer 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 Single-Layer 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 [Single Layer 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. |
|||
|
|||
## 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. |
|||
|
|||
## Initial Data Seeding |
|||
|
|||
The Single Layer solution template includes an initial data seeding mechanism to create default clients (applications) and scopes for the solution, if necessary (e.g., when using an Angular UI). The `OpenIddictDataSeedContributor` class can be found in the `Data` folder of the host project. If authentication is handled by the UI application(e.g., MVC / Razor Pages), this class is not included. |
|||
|
|||
The [OpenIddict UI **\***](../../modules/openiddict-pro.md) module is added only if you select it 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. |
|||
|
|||
 |
|||
|
|||
### External Providers |
|||
|
|||
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. |
|||
|
|||
If the UI is a SPA application (such as an Angular app), the API host uses [JWT Bearer Authentication](https://jwt.io/introduction/) to authorize user actions. |
|||
@ -0,0 +1,51 @@ |
|||
# Single Layer Solution: BLOB Storing |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Multi-Tenancy", |
|||
"Path": "solution-templates/single-layer-web-application/multi-tenancy" |
|||
}, |
|||
"Next": { |
|||
"Name": "CORS Configuration", |
|||
"Path": "solution-templates/single-layer-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 single-layer solution. Storing files, images, videos, and other large objects is common in distributed systems. For more details, refer to the [BLOB Storing System](../../framework/infrastructure/blob-storing/index.md) documentation. |
|||
|
|||
In the single-layer 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 required implementations for storing and retrieving BLOBs in the database. This setup is integrated into the single-layer solution template and is used across all related projects. You can modify the database configuration in the `appsettings.json` file of the API 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"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## File Management Module |
|||
|
|||
The *File Management* module is optional and can be added to the solution during the creation process. It provides a user interface for managing folders and files. For more information, see the [File Management *](../../modules/file-management.md) document. |
|||
|
|||
 |
|||
@ -0,0 +1,25 @@ |
|||
# Single Layer Solution: Built-In Features |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Db Migrator", |
|||
"Path": "solution-templates/single-layer-web-application/db-migrator" |
|||
}, |
|||
"Next": { |
|||
"Name": "Authentication", |
|||
"Path": "solution-templates/single-layer-web-application/authentication" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The Single Layer solution template includes several built-in features to help you get started with your single-layer 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 Single Layer solution template. The following documents explain these features in detail: |
|||
|
|||
* [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,32 @@ |
|||
# Single Layer Solution: CORS Configuration |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "BLOB Storing", |
|||
"Path": "solution-templates/single-layer-web-application/blob-storing" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
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 single-layer solution template, CORS configuration is applied in the following cases: |
|||
- When [Angular](web-applications.md#angular) is selected as the web application type. |
|||
- When [Blazor WebAssembly](web-applications.md#blazor-webassembly) is selected as the web application type. |
|||
- When [No UI](web-applications.md#no-ui) is selected as the web application type. |
|||
|
|||
CORS settings are configured in the `appsettings.json` file of the corresponding project. The web application usually serves as the entry point for front-end applications, so it must be set up 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 needed for your application. |
|||
@ -0,0 +1,190 @@ |
|||
# Single Layer Solution: Database configurations |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Authentication", |
|||
"Path": "solution-templates/single-layer-web-application/authentication" |
|||
}, |
|||
"Next": { |
|||
"Name": "Logging (with Serilog)", |
|||
"Path": "solution-templates/single-layer-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 Single-Layer Solution Template includes pre-configured database settings. This document explains how to manage database configurations in your solution. |
|||
|
|||
## Connection String |
|||
|
|||
Connection strings are stored in the `appsettings.json` file and can be customized for different environments by editing this file. [Web Application](web-applications.md) projects use the `Default` connection string by default. |
|||
|
|||
To update the connection string for the `Default` key, modify 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 Single-Layer Solution Template, the `DbContext` class is defined in the main project. This class manages the database schema and is derived from the `AbpDbContext` class, which offers additional features and configurations. You can customize the `DbContext` class to add new entities, relationships, and configurations. It is located in the `Data` folder of the main project. |
|||
|
|||
```csharp |
|||
public class BookstoreDbContext : AbpDbContext<BookstoreDbContext> |
|||
{ |
|||
|
|||
public const string DbTablePrefix = "App"; |
|||
public const string DbSchema = null; |
|||
|
|||
public BookstoreDbContext(DbContextOptions<BookstoreDbContext> options) |
|||
: base(options) |
|||
{ |
|||
} |
|||
|
|||
protected override void OnModelCreating(ModelBuilder builder) |
|||
{ |
|||
base.OnModelCreating(builder); |
|||
|
|||
/* Include modules to your migration db context */ |
|||
|
|||
builder.ConfigureSettingManagement(); |
|||
builder.ConfigureBackgroundJobs(); |
|||
builder.ConfigureAuditLogging(); |
|||
builder.ConfigureFeatureManagement(); |
|||
builder.ConfigurePermissionManagement(); |
|||
builder.ConfigureBlobStoring(); |
|||
builder.ConfigureIdentityPro(); |
|||
builder.ConfigureOpenIddictPro(); |
|||
builder.ConfigureGdpr(); |
|||
builder.ConfigureLanguageManagement(); |
|||
builder.ConfigureSaas(); |
|||
builder.ConfigureTextTemplateManagement(); |
|||
|
|||
/* Configure your own entities here */ |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 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(DbTablePrefix + "YourEntities", 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. |
|||
|
|||
### Configuration |
|||
|
|||
In the `BookstoreModule` class, the `ConfigureEfCore` method is used to configure the database context. It registers the `BookstoreDbContext` class to the [dependency injection](../../framework/fundamentals/dependency-injection.md) system and sets the SQL Server as the default DBMS for the application. |
|||
|
|||
```csharp |
|||
private void ConfigureEfCore(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.AddAbpDbContext<BookstoreDbContext>(options => |
|||
{ |
|||
/* You can remove "includeAllEntities: true" to create |
|||
* default repositories only for aggregate roots |
|||
* Documentatidon: https://docs.abp.io/en/abp/latest/Entity-Framework-Core#add-default-repositories |
|||
*/ |
|||
options.AddDefaultRepositories(includeAllEntities: true); |
|||
}); |
|||
|
|||
Configure<AbpDbContextOptions>(options => |
|||
{ |
|||
options.Configure(configurationContext => |
|||
{ |
|||
configurationContext.UseSqlServer(); |
|||
}); |
|||
}); |
|||
|
|||
} |
|||
``` |
|||
|
|||
## 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) |
|||
{ |
|||
BookstoreEfCoreEntityExtensionMappings.Configure(); |
|||
var configuration = BuildConfiguration(); |
|||
|
|||
var builder = new DbContextOptionsBuilder<BookstoreDbContext>() |
|||
.UseSqlServer(configuration.GetConnectionString("Default")); |
|||
|
|||
return new BookstoreDbContext(builder.Options); |
|||
} |
|||
|
|||
private static IConfigurationRoot BuildConfiguration() |
|||
{ |
|||
var builder = new ConfigurationBuilder() |
|||
.SetBasePath(Directory.GetCurrentDirectory()) |
|||
.AddJsonFile("appsettings.json", optional: false); |
|||
|
|||
return builder.Build(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## 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,107 @@ |
|||
# Single Layer Solution: Db Migrator |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Web Applications", |
|||
"Path": "solution-templates/single-layer-web-application/web-applications" |
|||
}, |
|||
"Next": { |
|||
"Name": "Built-In Features", |
|||
"Path": "solution-templates/single-layer-web-application/built-in-features" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
Unlike the Layered solution template, the Single Layer solution template does not include a separate database migrator project. Instead, the main application project handles database migration and seed data operations. The `*.DbMigrator` project is excluded from this template. To manage database migrations and seed data, you can use the `migrate-database.ps1` script in the root directory or run the `dotnet run --migrate-database` command from the main application project directory. |
|||
|
|||
 |
|||
|
|||
After the migration completes, a message will appear in the console. You can verify the success of the migration by checking the database. |
|||
|
|||
## Database Migration Service |
|||
|
|||
Under the `Data` folder of the project, the `BookstoreDbMigrationService` class is responsible for database migration and seed data operations. The `MigrateAsync` method is called in the `Program` class to migrate the database when the application starts with the `--migrate-database` argument. |
|||
|
|||
First, it checks if the database is created and applies the pending migrations. Then, it seeds the initial data using the `SeedAsync` method. |
|||
|
|||
```csharp |
|||
public async Task MigrateAsync() |
|||
{ |
|||
var initialMigrationAdded = AddInitialMigrationIfNotExist(); |
|||
|
|||
if (initialMigrationAdded) |
|||
{ |
|||
return; |
|||
} |
|||
|
|||
Logger.LogInformation("Started database migrations..."); |
|||
|
|||
await MigrateDatabaseSchemaAsync(); |
|||
await SeedDataAsync(); |
|||
|
|||
Logger.LogInformation($"Successfully completed host database migrations."); |
|||
|
|||
var tenants = await _tenantRepository.GetListAsync(includeDetails: true); |
|||
|
|||
var migratedDatabaseSchemas = new HashSet<string>(); |
|||
foreach (var tenant in tenants) |
|||
{ |
|||
using (_currentTenant.Change(tenant.Id)) |
|||
{ |
|||
if (tenant.ConnectionStrings.Any()) |
|||
{ |
|||
var tenantConnectionStrings = tenant.ConnectionStrings |
|||
.Select(x => x.Value) |
|||
.ToList(); |
|||
|
|||
if (!migratedDatabaseSchemas.IsSupersetOf(tenantConnectionStrings)) |
|||
{ |
|||
await MigrateDatabaseSchemaAsync(tenant); |
|||
|
|||
migratedDatabaseSchemas.AddIfNotContains(tenantConnectionStrings); |
|||
} |
|||
} |
|||
|
|||
await SeedDataAsync(tenant); |
|||
} |
|||
|
|||
Logger.LogInformation($"Successfully completed {tenant.Name} tenant database migrations."); |
|||
} |
|||
|
|||
Logger.LogInformation("Successfully completed all database migrations."); |
|||
Logger.LogInformation("You can safely end this process..."); |
|||
} |
|||
``` |
|||
|
|||
The `BookstoreDbSchemaMigrator` class is used in the `MigrateDatabaseSchemaAsync` method for the database migration process. It is responsible for applying migrations to the database. |
|||
|
|||
```csharp |
|||
public class BookstoreDbSchemaMigrator : ITransientDependency |
|||
{ |
|||
private readonly IServiceProvider _serviceProvider; |
|||
|
|||
public BookstoreDbSchemaMigrator( |
|||
IServiceProvider serviceProvider) |
|||
{ |
|||
_serviceProvider = serviceProvider; |
|||
} |
|||
|
|||
public async Task MigrateAsync() |
|||
{ |
|||
|
|||
/* We intentionally resolving the BookstoreDbContext |
|||
* from IServiceProvider (instead of directly injecting it) |
|||
* to properly get the connection string of the current tenant in the |
|||
* current scope. |
|||
*/ |
|||
|
|||
await _serviceProvider |
|||
.GetRequiredService<BookstoreDbContext>() |
|||
.Database |
|||
.MigrateAsync(); |
|||
|
|||
} |
|||
} |
|||
``` |
|||
|
After Width: | Height: | Size: 58 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 81 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 64 KiB |
|
After Width: | Height: | Size: 71 KiB |
|
After Width: | Height: | Size: 65 KiB |
|
After Width: | Height: | Size: 114 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 55 KiB |
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 137 KiB |
@ -1,59 +1,33 @@ |
|||
# Single Layer Application Solution Template |
|||
|
|||
This template provides a simple solution structure with a single project. This document explains that solution structure in details. |
|||
|
|||
## Getting Started |
|||
|
|||
* Follow the [Getting Started guide](../../get-started/single-layer-web-application.md) to create a new solution using this startup solution template. |
|||
* Follow the [TODO application tutorial](../../tutorials/todo/single-layer/index.md) to learn how to create a simple application with this startup solution template. |
|||
|
|||
## The Solution Structure |
|||
|
|||
If you created your solution with the default options, you will have a .NET solution as shown below: |
|||
|
|||
 |
|||
|
|||
In the next sections, we will explain the structure based on this example. Your startup solution can be slightly different based on your preferences. |
|||
|
|||
### Folder Structure |
|||
|
|||
Since this template provides a single-project solution, we've separated concerns into folders instead of projects. You can see the pre-defined folders as shown below: |
|||
|
|||
 |
|||
|
|||
* Define your database mappings (for [EF Core](../../framework/data/entity-framework-core) or [MongoDB](../../framework/data/mongodb) and [repositories](../../framework/architecture/domain-driven-design/repositories.md) in the `Data` folder. |
|||
* Define your [entities](../../framework/architecture/domain-driven-design/entities.md) in the `Entities` folder. |
|||
* Define your UI localization keys/values in the `Localization` folder. |
|||
* Define your UI menu items in the `Menus` folder. |
|||
* Define your [object-to-object mapping](../../framework/infrastructure/object-to-object-mapping.md) classes in the `ObjectMapping` folder. |
|||
* Define your UI pages (Razor Pages) in the `Pages` folder (create `Controllers` and `Views` folder yourself if you prefer the MVC pattern). |
|||
* Define your [application services](../../framework/architecture/domain-driven-design/application-services.md) in the `Services` folder. |
|||
|
|||
### How to Run? |
|||
|
|||
Before running the application, you need to create the database and seed the initial data. To do that, you can run the following command in the directory of your project (in the same folder of the `.csproj` file): |
|||
|
|||
```bash |
|||
dotnet run --migrate-database |
|||
``` |
|||
|
|||
This command will create the database and seed the initial data for you. Then you can run the application with any IDE that supports .NET or by running the `dotnet run` command in the directory of your project. The default username is `admin` and the password is `1q2w3E*`. |
|||
|
|||
> While creating a database & applying migrations seem only necessary for relational databases, you should run this command 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. |
|||
|
|||
### The Angular UI |
|||
|
|||
If you choose `Angular` as the UI framework, the solution will be separated into two folders: |
|||
|
|||
* An `angular` folder that contains the Angular UI application, the client-side code. |
|||
* An `aspnet-core` folder that contains the ASP.NET Core solution (a single project), the server-side code. |
|||
|
|||
The server-side is similar to the solution described in the *Solution Structure* section above. This project serves the API, so the Angular application can consume it. |
|||
|
|||
The client-side application consumes the HTTP APIs as mentioned. You can see the folder structure of the Angular project shown below: |
|||
|
|||
 |
|||
|
|||
## See Also |
|||
|
|||
* [Video tutorial](https://abp.io/video-courses/essentials/app-template) |
|||
# ABP Studio: Single Layer Solution Template |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Next": { |
|||
"Name": "Overview", |
|||
"Path": "solution-templates/single-layer-web-application/overview" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
ABP Studio offers pre-architected, production-ready templates to quickly start a new solution. One of these is the Single Layer solution template, designed for building monolithic systems with minimal layers. It follows [Domain-Driven Design](../../framework/architecture/domain-driven-design) (DDD) principles and common application patterns. The template includes a single project, integrates existing modules, and provides host applications based on your selections, making it a solid foundation for your system. |
|||
|
|||
> **This document explains the Single Layer 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 single-layer solution, please refer to *[Quick Start: Creating a Single Layer Web Application with ABP Studio](../../get-started/single-layer-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) |
|||
* [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) |
|||
@ -0,0 +1,35 @@ |
|||
# Single Layer Solution: Logging |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Database configurations", |
|||
"Path": "solution-templates/single-layer-web-application/database-configurations" |
|||
}, |
|||
"Next": { |
|||
"Name": "Swagger integration", |
|||
"Path": "solution-templates/single-layer-web-application/swagger-integration" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The ABP Studio [single-layer 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,20 @@ |
|||
# Single Layer Solution: Main Components |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Solution structure", |
|||
"Path": "solution-templates/single-layer-web-application/solution-structure" |
|||
}, |
|||
"Next": { |
|||
"Name": "Web Applications", |
|||
"Path": "solution-templates/single-layer-web-application/web-applications" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
The single-layer solution template is a single project containing all the essential components for building a monolithic application. It supports the `--migrate-database` command-line argument to create the database and seed initial data. The main components of the solution are: |
|||
|
|||
* [Web Applications](web-applications.md) |
|||
* [Db Migrator](db-migrator.md) |
|||
@ -0,0 +1,74 @@ |
|||
# Single Layer Solution: Multi-Tenancy |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Swagger integration", |
|||
"Path": "solution-templates/single-layer-web-application/swagger-integration" |
|||
}, |
|||
"Next": { |
|||
"Name": "BLOB storing", |
|||
"Path": "solution-templates/single-layer-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 single-layer 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 Single Layer Solutions |
|||
|
|||
The single-layer 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 some 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,95 @@ |
|||
# Single Layer Solution: Overview |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Index", |
|||
"Path": "solution-templates/single-layer-web-application/index" |
|||
}, |
|||
"Next": { |
|||
"Name": "Solution Structure", |
|||
"Path": "solution-templates/single-layer-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. |
|||
|
|||
This document explains what the Single-Layer solution template offers. |
|||
|
|||
## 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. |
|||
* **[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 solution comes with the following built-in and pre-configured features: |
|||
|
|||
* **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). **\*** |
|||
* **[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, [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 |
|||
|
|||
Single-layer 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 another 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 UI application to the solution) |
|||
* **Angular** |
|||
* **MVC / Razor Pages UI** |
|||
* **Blazor WebAssembly** |
|||
* **Blazor Server** |
|||
|
|||
### 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 Single Layer Web Application with ABP Studio](../../get-started/single-layer-web-application.md) |
|||
@ -0,0 +1,71 @@ |
|||
# Single Layer Solution: The Structure |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Overview", |
|||
"Path": "solution-templates/single-layer-web-application/overview" |
|||
}, |
|||
"Next": { |
|||
"Name": "Main Components", |
|||
"Path": "solution-templates/single-layer-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 [single layer solution template](index.md). |
|||
|
|||
> This document assumes that you've created a new single-layer solution by following the *[Quick Start: Creating a Single Layer Web Application with ABP Studio](../../get-started/single-layer-web-application.md)* guide. (Choose the *Entity Framework Core* as the database provider.) |
|||
|
|||
## Understanding the ABP Solution Structure |
|||
|
|||
The single-layer solution template is designed to be simple and easy to understand. It includes a single project that contains all the necessary components to build a monolithic application. The solution structure is as follows: |
|||
|
|||
 |
|||
|
|||
`Acme.Bookstore` is the main **ABP Studio module** in the solution. It also includes the **ABP Studio package** `Acme.Bookstore` as the host application. |
|||
|
|||
> Refer to the *[Concepts](../../studio/concepts.md)* document for a comprehensive definition of ABP Studio solution, module, and package terms. |
|||
|
|||
## The Solution Structure |
|||
|
|||
If you create the solution based on *[Quick Start: Creating a Single Layer Web Application with ABP Studio](../../get-started/single-layer-web-application.md)* guide, the solution structure will be as follows: |
|||
|
|||
 |
|||
|
|||
### Folder Structure |
|||
|
|||
This template uses a single-project structure, with concerns separated into folders instead of projects. The pre-defined folders are shown below: |
|||
|
|||
 |
|||
|
|||
* **Data**: Define your database mappings (for [EF Core](../../framework/data/entity-framework-core) or [MongoDB](../../framework/data/mongodb) and [repositories](../../framework/architecture/domain-driven-design/repositories.md)) in this folder. |
|||
* **Entities**: Define your [entities](../../framework/architecture/domain-driven-design/entities.md) in this folder. |
|||
* **Localization**: Define your UI localization keys/values in this folder. |
|||
* **Menus**: Define your UI menu items in this folder. |
|||
* **Migrations**: Contains the database migration files. It is created automatically by EF Core. |
|||
* **ObjectMapping**: Define your [object-to-object mapping](../../framework/infrastructure/object-to-object-mapping.md) classes in this folder. |
|||
* **Pages**: Define your UI pages (Razor Pages) in this folder (create `Controllers` and `Views` folders yourself if you prefer the MVC pattern). |
|||
* **Permissions**: Define your [permissions](../../framework/fundamentals/authorization.md) in this folder. |
|||
* **Services**: Define your [application services](../../framework/architecture/domain-driven-design/application-services.md) in this folder. |
|||
|
|||
### How to Run? |
|||
|
|||
When you create a new solution it automatically creates initial migration and run database migrator for you (unless you uncheck these options). However, you can run the following command in the directory of your project (in the same folder of the `.csproj` file) to create the database and seed the initial data: |
|||
|
|||
```bash |
|||
dotnet run --migrate-database |
|||
``` |
|||
|
|||
This command will create the database and seed the initial data for you. Then you can run the application with the ABP Studio [Solution Runner](../../studio/running-applications.md). The default username is `admin` and the password is `1q2w3E*`. |
|||
|
|||
 |
|||
|
|||
> While creating a database & applying migrations seem only necessary for relational databases, you should run this command 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. |
|||
|
|||
## See Also |
|||
|
|||
* [Video tutorial](https://abp.io/video-courses/essentials/app-template) |
|||
@ -0,0 +1,19 @@ |
|||
# Single Layer Solution: Swagger Integration |
|||
|
|||
```json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Logging (with Serilog)", |
|||
"Path": "solution-templates/single-layer-web-application/logging" |
|||
}, |
|||
"Next": { |
|||
"Name": "Multi-Tenancy", |
|||
"Path": "solution-templates/single-layer-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,72 @@ |
|||
# Single Layer Solution: Web Applications |
|||
|
|||
````json |
|||
//[doc-nav] |
|||
{ |
|||
"Previous": { |
|||
"Name": "Main Components", |
|||
"Path": "solution-templates/single-layer-web-application/main-components" |
|||
}, |
|||
"Next": { |
|||
"Name": "Db Migrator", |
|||
"Path": "solution-templates/single-layer-web-application/db-migrator" |
|||
} |
|||
} |
|||
```` |
|||
|
|||
The single-layer solution template includes a web application project that acts as the main application. This ASP.NET Core application hosts the API endpoints and may also serve the user interface, depending on the selected UI framework. |
|||
|
|||
- **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. |
|||
- **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 single-layer 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 single-layer solution template, it generates an ASP.NET Core MVC application named something like `Acme.BookStore`. 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 single-layer 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`. |
|||
|
|||
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 ASP.NET Core host application. |
|||
|
|||
## 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. |
|||
|
|||
## 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. |
|||
|
After Width: | Height: | Size: 14 KiB |
@ -0,0 +1,26 @@ |
|||
# Mobile Application Development Tutorial: Book Store Application |
|||
|
|||
> You must have an ABP Team or a higher license to be able to create a mobile application. |
|||
|
|||
Mobile application development tutorials are designed for developers who have completed [the web development part of the tutorial](../book-store/index.md) and wish to continue building the mobile version of the application. |
|||
|
|||
## Tutorials |
|||
|
|||
You can choose between two mobile applications: [**.NET MAUI**](../../framework/ui/maui/index.md) or [**React Native**](../../framework/ui/react-native/index.md). Choose your framework and continue building your mobile application! |
|||
|
|||
- Both guides assume you have completed the web development section of the tutorial and have the necessary backend APIs in place. |
|||
- Each guide is self-contained and provides step-by-step instructions to build the mobile app. |
|||
|
|||
### .NET MAUI |
|||
|
|||
The .NET MAUI tutorial walks you through creating a mobile version of your bookstore app using .NET technologies. |
|||
|
|||
* [.NET MAUI - Mobile Application Tutorial](./maui/index.md) |
|||
* [Source Code](https://abp.io/Account/Login?returnUrl=/api/download/samples/bookstore-maui-efcore-mobile) |
|||
|
|||
### React Native |
|||
|
|||
The React Native tutorial provides instructions for building the bookstore app using JavaScript. |
|||
|
|||
* [React Native - Mobile Application Tutorial](./react-native/index.md) |
|||
* [Source Code](https://abp.io/Account/Login?returnUrl=/api/download/samples/bookstore-react-native-mongodb) |
|||
@ -0,0 +1,17 @@ |
|||
using System; |
|||
using Volo.Abp.Data; |
|||
|
|||
namespace Volo.Abp.EventBus.Distributed; |
|||
|
|||
public interface IIncomingEventInfo : IHasExtraProperties |
|||
{ |
|||
Guid Id { get; } |
|||
|
|||
string MessageId { get; } |
|||
|
|||
string EventName { get; } |
|||
|
|||
byte[] EventData { get; } |
|||
|
|||
DateTime CreationTime { get; } |
|||
} |
|||
@ -0,0 +1,15 @@ |
|||
using System; |
|||
using Volo.Abp.Data; |
|||
|
|||
namespace Volo.Abp.EventBus.Distributed; |
|||
|
|||
public interface IOutgoingEventInfo : IHasExtraProperties |
|||
{ |
|||
Guid Id { get; } |
|||
|
|||
string EventName { get; } |
|||
|
|||
byte[] EventData { get; } |
|||
|
|||
DateTime CreationTime { get; } |
|||
} |
|||
@ -0,0 +1,38 @@ |
|||
using System; |
|||
using System.Linq.Expressions; |
|||
|
|||
namespace Volo.Abp.EventBus.Distributed; |
|||
|
|||
public static class InboxOutboxFilterExpressionTransformer |
|||
{ |
|||
public static Expression<Func<TTarget, bool>> Transform<TOriginal, TTarget>(Expression<Func<TOriginal, bool>> originalExpression) |
|||
{ |
|||
var originalParam = originalExpression.Parameters[0]; |
|||
var newParam = Expression.Parameter(typeof(TTarget), originalParam.Name); |
|||
var body = ReplaceParameter(originalExpression.Body, originalParam, newParam); |
|||
return Expression.Lambda<Func<TTarget, bool>>(body, newParam); |
|||
} |
|||
|
|||
private static Expression ReplaceParameter(Expression body, ParameterExpression oldParam, ParameterExpression newParam) |
|||
{ |
|||
var visitor = new ParameterReplacer(oldParam, newParam); |
|||
return visitor.Visit(body); |
|||
} |
|||
|
|||
private class ParameterReplacer : ExpressionVisitor |
|||
{ |
|||
private readonly ParameterExpression _oldParam; |
|||
private readonly ParameterExpression _newParam; |
|||
|
|||
public ParameterReplacer(ParameterExpression oldParam, ParameterExpression newParam) |
|||
{ |
|||
_oldParam = oldParam; |
|||
_newParam = newParam; |
|||
} |
|||
|
|||
protected override Expression VisitParameter(ParameterExpression node) |
|||
{ |
|||
return node == _oldParam ? _newParam : base.VisitParameter(node); |
|||
} |
|||
} |
|||
} |
|||
@ -1,39 +0,0 @@ |
|||
using System; |
|||
using Microsoft.AspNetCore.Builder; |
|||
using Microsoft.AspNetCore.Hosting; |
|||
using Microsoft.Extensions.DependencyInjection; |
|||
using Microsoft.Extensions.Logging; |
|||
using Volo.Abp; |
|||
using Volo.Abp.Localization; |
|||
|
|||
namespace Volo.BloggingTestApp |
|||
{ |
|||
public class Startup |
|||
{ |
|||
public void ConfigureServices(IServiceCollection services) |
|||
{ |
|||
services.AddApplication<BloggingTestAppModule>(); |
|||
|
|||
services.Configure<AbpLocalizationOptions>(options => |
|||
{ |
|||
options.Languages.Add(new LanguageInfo("ar", "ar", "العربية")); |
|||
options.Languages.Add(new LanguageInfo("en", "en", "English")); |
|||
options.Languages.Add(new LanguageInfo("cs", "cs", "Čeština")); |
|||
options.Languages.Add(new LanguageInfo("fi", "fi", "Finnish")); |
|||
options.Languages.Add(new LanguageInfo("fr", "fr", "Français")); |
|||
options.Languages.Add(new LanguageInfo("sk", "sk", "Slovak")); |
|||
options.Languages.Add(new LanguageInfo("hi", "hi", "Hindi")); |
|||
options.Languages.Add(new LanguageInfo("it", "it", "Italiano")); |
|||
options.Languages.Add(new LanguageInfo("tr", "tr", "Türkçe")); |
|||
options.Languages.Add(new LanguageInfo("pt-BR", "pt-BR", "Português")); |
|||
options.Languages.Add(new LanguageInfo("zh-Hans", "zh-Hans", "简体中文")); |
|||
options.Languages.Add(new LanguageInfo("zh-Hant", "zh-Hant", "繁体中文")); |
|||
}); |
|||
} |
|||
|
|||
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILoggerFactory loggerFactory) |
|||
{ |
|||
app.InitializeApplication(); |
|||
} |
|||
} |
|||
} |
|||
@ -0,0 +1,80 @@ |
|||
using System; |
|||
using System.Threading.Tasks; |
|||
using Asp.Versioning; |
|||
using Microsoft.AspNetCore.Mvc; |
|||
using Volo.Abp; |
|||
using Volo.Abp.AspNetCore.Mvc; |
|||
using Volo.Docs.Areas.Models.DocumentNavigation; |
|||
using Volo.Docs.Documents; |
|||
using Volo.Docs.Utils; |
|||
|
|||
namespace Volo.Docs.Areas.Documents; |
|||
|
|||
[RemoteService(Name = DocsRemoteServiceConsts.RemoteServiceName)] |
|||
[Area(DocsRemoteServiceConsts.ModuleName)] |
|||
[ControllerName("DocumentNavigation")] |
|||
[Route("/docs/document-navigation")] |
|||
public class DocumentNavigationController : AbpController |
|||
{ |
|||
private readonly IDocumentAppService _documentAppService; |
|||
private readonly IDocsLinkGenerator _docsLinkGenerator; |
|||
|
|||
public DocumentNavigationController(IDocumentAppService documentAppService, IDocsLinkGenerator docsLinkGenerator) |
|||
{ |
|||
_documentAppService = documentAppService; |
|||
_docsLinkGenerator = docsLinkGenerator; |
|||
} |
|||
|
|||
[HttpGet] |
|||
[Route("")] |
|||
public virtual async Task<NavigationNode> GetNavigationAsync(GetNavigationNodeWithLinkModel input) |
|||
{ |
|||
var navigationNode = await _documentAppService.GetNavigationAsync(new GetNavigationDocumentInput |
|||
{ |
|||
LanguageCode = input.LanguageCode, |
|||
Version = input.Version, |
|||
ProjectId = input.ProjectId |
|||
}); |
|||
|
|||
NormalPath(navigationNode, input); |
|||
|
|||
return navigationNode; |
|||
} |
|||
|
|||
protected virtual void NormalPath(NavigationNode node, GetNavigationNodeWithLinkModel input) |
|||
{ |
|||
if (node.HasChildItems) |
|||
{ |
|||
foreach (var item in node.Items) |
|||
{ |
|||
NormalPath(item, input); |
|||
} |
|||
} |
|||
|
|||
if (UrlHelper.IsExternalLink(node.Path)) |
|||
{ |
|||
return; |
|||
} |
|||
|
|||
node.Path = RemoveFileExtensionFromPath(node.Path, input.ProjectFormat); |
|||
if (node.Path.IsNullOrWhiteSpace()) |
|||
{ |
|||
node.Path = "javascript:;"; |
|||
return; |
|||
} |
|||
|
|||
node.Path = _docsLinkGenerator.GenerateLink(input.ProjectName, input.LanguageCode, input.RouteVersion, node.Path); |
|||
} |
|||
|
|||
private string RemoveFileExtensionFromPath(string path, string projectFormat) |
|||
{ |
|||
if (path == null) |
|||
{ |
|||
return null; |
|||
} |
|||
|
|||
return path.EndsWith("." + projectFormat) |
|||
? path.Left(path.Length - projectFormat.Length - 1) |
|||
: path; |
|||
} |
|||
} |
|||
@ -0,0 +1,28 @@ |
|||
using System; |
|||
using System.ComponentModel.DataAnnotations; |
|||
using Volo.Abp.Validation; |
|||
using Volo.Docs.Language; |
|||
using Volo.Docs.Projects; |
|||
|
|||
namespace Volo.Docs.Areas.Models.DocumentNavigation; |
|||
|
|||
public class GetNavigationNodeWithLinkModel |
|||
{ |
|||
public Guid ProjectId { get; set; } |
|||
|
|||
[DynamicStringLength(typeof(ProjectConsts), nameof(ProjectConsts.MaxVersionNameLength))] |
|||
public string Version { get; set; } |
|||
|
|||
[Required] |
|||
[DynamicStringLength(typeof(LanguageConsts), nameof(LanguageConsts.MaxLanguageCodeLength))] |
|||
public string LanguageCode { get; set; } |
|||
|
|||
[Required] |
|||
public string ProjectName { get; set; } |
|||
|
|||
[Required] |
|||
public string ProjectFormat { get; set; } |
|||
|
|||
[Required] |
|||
public string RouteVersion { get; set; } |
|||
} |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue