mirror of https://github.com/abpframework/abp.git
SALİH ÖZKARA
2 years ago
591 changed files with 12648 additions and 3377 deletions
@ -0,0 +1,67 @@ |
|||||
|
# ABP Studio Goes AOT: Faster Startups with Ready-to-Run (R2R) Publishing |
||||
|
|
||||
|
We're excited that [ABP Studio](https://abp.io/studio) now supports [Ready-to-Run (R2R) publishing](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) (starting from v0.9.16+), a hybrid form of ahead-of-time (AOT) compilation. This enhancement significantly improves the startup time and overall performance of ABP Studio, making it faster and more performant than ever before. |
||||
|
|
||||
|
Let's dive into what R2R publishing is, how it works, and the benefits it brings to ABP Studio. |
||||
|
|
||||
|
## What is Ready-to-Run (R2R) Publishing? |
||||
|
|
||||
|
Ready-to-Run (R2R) is a form of AOT compilation available in the .NET ecosystem. Unlike traditional just-in-time (JIT) compilation, R2R precompiles parts of your application to native code before deployment. This precompiled code helps reduce the startup time by minimizing the work needed during runtime. |
||||
|
|
||||
|
However, R2R isn't a complete AOT compilation. Instead, it's a hybrid approach because it stores both: |
||||
|
|
||||
|
* **Native code for precompiled methods** (to improve startup time and performance) |
||||
|
|
||||
|
* **Intermediate Language (IL) code** for methods that may need further JIT compilation |
||||
|
|
||||
|
This hybrid nature is why R2R binaries are typically larger. For ABP Studio, the storage size increased by ~150 MB with R2R enabled, but the trade-off is well worth it for the performance and startup-time gains. |
||||
|
|
||||
|
## How R2R (Ready-to-Run) Improves ABP Studio |
||||
|
|
||||
|
### Faster Startup Time 🚀 |
||||
|
|
||||
|
One of the biggest advantages of R2R publishing is its impact on startup times. In our local tests, enabling R2R resulted in startup times being **reduced by 2.5x** ⬇️. |
||||
|
|
||||
|
This means you can get to work faster, without waiting for the application to being startup from the beginning. Whether you're launching ABP Studio to manage projects, generate code, or deploy applications, the improved responsiveness is noticeable. |
||||
|
|
||||
|
### Performance Enhancements 📈 |
||||
|
|
||||
|
In addition to faster startups, R2R publishing contributes to overall performance improvements. By precompiling frequently used methods, R2R reduces the workload on the JIT compiler during execution, leading to smoother and more efficient operations. |
||||
|
|
||||
|
### Trade-offs: Increased Storage Size 🆙 |
||||
|
|
||||
|
With great performance comes a slight trade-off: storage size. R2R binaries include both **native** and **IL code**, which increases the file size. In the case of ABP Studio, the storage footprint increased by ~150 MB. However, the substantial improvements in speed and responsiveness make this a worthwhile investment. |
||||
|
|
||||
|
## How to Enable R2R Publishing in Your Applications? |
||||
|
|
||||
|
If you're developing applications and want to benefit from R2R, here's a quick guide on how to enable it in your .NET projects: |
||||
|
|
||||
|
1. You can add the following configuration to your final project's `.csproj` file: |
||||
|
|
||||
|
```xml |
||||
|
<PropertyGroup> |
||||
|
<PublishReadyToRun>true</PublishReadyToRun> |
||||
|
</PropertyGroup> |
||||
|
``` |
||||
|
|
||||
|
2. Then, publish your application with the `dotnet publish` command: |
||||
|
|
||||
|
```bash |
||||
|
dotnet publish -c Release |
||||
|
``` |
||||
|
|
||||
|
Alternatively, you can specify the _PublishReadyToRun_ flag directly to the `dotnet publish` command as follows: |
||||
|
|
||||
|
```bash |
||||
|
dotnet publish -c Release -r win-x64 -p:PublishReadyToRun=true |
||||
|
``` |
||||
|
|
||||
|
That's it! Your application will now include precompiled native code for faster startup and great performance benefits. |
||||
|
|
||||
|
> Please refer to the [official documentation](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) before publishing your application with R2R. |
||||
|
|
||||
|
## Conclusion |
||||
|
|
||||
|
As ABP team, we're always looking for ways to improve the developer experience. By adopting **Ready-to-Run (R2R) publishing** for ABP Studio, we're aiming to deliver a faster and more efficient tool for your development needs. |
||||
|
|
||||
|
Stay tuned for more updates and enhancements as we continue to optimize ABP Studio and please provide us with your invaluable feedback. |
||||
@ -0,0 +1,309 @@ |
|||||
|
# ABP Global Assets - New way to bundle JavaScript/CSS files in Blazor WebAssembly app |
||||
|
|
||||
|
We have introduced a new feature in the ABP framework to bundle the `JavaScript/CSS` files in the Blazor wasm app. This feature is called `Global Assets`. |
||||
|
With this feature, you don't need to run the `abp bundle` command to manually create/maintain the `global.js` and `global.css` files in your Blazor wasm app. |
||||
|
|
||||
|
## How Global Assets works? |
||||
|
|
||||
|
The new `Blazor wasm app` has two projects: |
||||
|
|
||||
|
1. `MyProjectName` (ASP.NET Core app) |
||||
|
2. `MyProjectName.Client` (Blazor wasm app) |
||||
|
|
||||
|
The `MyProjectName` reference the `MyProjectName.Client` project, and will be the entry point of the application, which means the `MyProjectName` project will be the `host` project of the `MyProjectName.Client` project. |
||||
|
|
||||
|
The static/virtual files of `MyProjectName` can be accessed by the `MyProjectName.Client` project, so we can create dynamic global assets in the `MyProjectName` project and use them in the `MyProjectName.Client` project. |
||||
|
|
||||
|
## How it works in ABP? |
||||
|
|
||||
|
We have created a new package `WebAssembly.Theme.Bundling` for the theme `WebAssembly` module and used the `Volo.Abp.AspNetCore.Mvc.UI.Bundling.BundleContributor` to add `JavaScript/CSS` files to the bundling system. |
||||
|
|
||||
|
* LeptonXLiteTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule` |
||||
|
* LeptonXTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` |
||||
|
* LeptonTheme: `AbpAspNetCoreComponentsWebAssemblyLeptonThemeBundlingModule` |
||||
|
* BasicTheme: `AbpAspNetCoreComponentsWebAssemblyBasicThemeBundlingModule` |
||||
|
|
||||
|
The new `ThemeBundlingModule` only depends on `AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule(new package)`. It's an `abstractions module`, which only depends on `AbpAspNetCoreMvcUiBundlingAbstractionsModule`. |
||||
|
|
||||
|
We will get all `JavaScript/CSS` files on `OnApplicationInitializationAsync` method of `AbpAspNetCoreMvcUiBundlingModule` from bundling system and add them to `IDynamicFileProvider` service. After that, we can access the `JavaScript/CSS` files in the Blazor wasm app. |
||||
|
|
||||
|
## Add the Global Assets in the module |
||||
|
|
||||
|
If your module has `JavaScript/CSS` files that need to the bundling system, You have to create a new project(`YourModuleName.Blazor.WebAssembly.Bundling`) to your module solution, and reference the new project in the `MyProjectName` project and module dependencies. |
||||
|
|
||||
|
The new project should **only** depend on the `AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule` and define `BundleContributor` classes to contribute the `JavaScript/CSS` files. |
||||
|
|
||||
|
> Q: The new project(`YourModuleName.Blazor.WebAssembly.Bundling`) doesn't have the `libs/myscript.js` and `libs/myscript.css` files why the files can be added to the bundling system? |
||||
|
|
||||
|
> A: Because the `MyProjectName.Client` will depend on the `MyBlazorModule(YourModuleName.Blazor)` that contains the `JavaScript/CSS` files, The `MyProjectName` is referencing the `MyProjectName.Client` project, so the `MyProjectName` project can access the `JavaScript/CSS` files in the `MyProjectName.Client` project and add them to the bundling system. |
||||
|
|
||||
|
```csharp |
||||
|
[DependsOn( |
||||
|
typeof(AbpAspNetCoreComponentsWebAssemblyThemingBundlingModule) |
||||
|
)] |
||||
|
public class MyBlazorWebAssemblyBundlingModule : AbpModule |
||||
|
{ |
||||
|
public override void ConfigureServices(ServiceConfigurationContext context) |
||||
|
{ |
||||
|
Configure<AbpBundlingOptions>(options => |
||||
|
{ |
||||
|
// Script Bundles |
||||
|
options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global).AddContributors(typeof(MyModuleBundleScriptContributor)); |
||||
|
|
||||
|
// Style Bundles |
||||
|
options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global).AddContributors(typeof(MyModuleBundleStyleBundleContributor)); |
||||
|
}); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
```csharp |
||||
|
public class MyModuleBundleScriptContributor : BundleContributor |
||||
|
{ |
||||
|
public override void ConfigureBundle(BundleConfigurationContext context) |
||||
|
{ |
||||
|
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.js"); |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
public class MyModuleBundleStyleBundleContributor : BundleContributor |
||||
|
{ |
||||
|
public override void ConfigureBundle(BundleConfigurationContext context) |
||||
|
{ |
||||
|
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.css"); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
## Use the Global Assets in the Blazor WASM |
||||
|
|
||||
|
### MyCompanyName.MyProjectName.Blazor |
||||
|
|
||||
|
Convert your `MyCompanyName.MyProjectName.Blazor` project to integrate the `ABP module` system and depend on the `AbpAspNetCoreMvcUiBundlingModule` and `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule`: |
||||
|
|
||||
|
* The `AbpAspNetCoreMvcUiBundlingModule` uses to create the `JavaScript/CSS` files to virtual files. |
||||
|
* The `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` uses to add theme `JavaScript/CSS` to the bundling system. |
||||
|
|
||||
|
Here is how your project files look like: |
||||
|
|
||||
|
**`Program.cs`:** |
||||
|
|
||||
|
```csharp |
||||
|
public class Program |
||||
|
{ |
||||
|
public async static Task<int> Main(string[] args) |
||||
|
{ |
||||
|
//... |
||||
|
|
||||
|
var builder = WebApplication.CreateBuilder(args); |
||||
|
builder.Host.AddAppSettingsSecretsJson() |
||||
|
.UseAutofac() |
||||
|
.UseSerilog(); |
||||
|
await builder.AddApplicationAsync<MyProjectNameBlazorModule>(); |
||||
|
var app = builder.Build(); |
||||
|
await app.InitializeApplicationAsync(); |
||||
|
await app.RunAsync(); |
||||
|
return 0; |
||||
|
|
||||
|
//... |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
**`MyProjectNameBlazorModule.cs`:** |
||||
|
|
||||
|
```csharp |
||||
|
[DependsOn( |
||||
|
typeof(AbpAutofacModule), |
||||
|
typeof(AbpAspNetCoreMvcUiBundlingModule), |
||||
|
typeof(AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule) //Should be added! |
||||
|
)] |
||||
|
public class MyProjectNameBlazorModule : AbpModule |
||||
|
{ |
||||
|
public override void ConfigureServices(ServiceConfigurationContext context) |
||||
|
{ |
||||
|
//https://github.com/dotnet/aspnetcore/issues/52530 |
||||
|
Configure<RouteOptions>(options => |
||||
|
{ |
||||
|
options.SuppressCheckForUnhandledSecurityMetadata = true; |
||||
|
}); |
||||
|
|
||||
|
// Add services to the container. |
||||
|
context.Services.AddRazorComponents() |
||||
|
.AddInteractiveWebAssemblyComponents(); |
||||
|
} |
||||
|
|
||||
|
public override void OnApplicationInitialization(ApplicationInitializationContext context) |
||||
|
{ |
||||
|
var env = context.GetEnvironment(); |
||||
|
var app = context.GetApplicationBuilder(); |
||||
|
|
||||
|
// Configure the HTTP request pipeline. |
||||
|
if (env.IsDevelopment()) |
||||
|
{ |
||||
|
app.UseWebAssemblyDebugging(); |
||||
|
} |
||||
|
else |
||||
|
{ |
||||
|
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts. |
||||
|
app.UseHsts(); |
||||
|
} |
||||
|
|
||||
|
app.UseHttpsRedirection(); |
||||
|
app.MapAbpStaticAssets(); |
||||
|
app.UseRouting(); |
||||
|
app.UseAntiforgery(); |
||||
|
|
||||
|
app.UseConfiguredEndpoints(builder => |
||||
|
{ |
||||
|
builder.MapRazorComponents<App>() |
||||
|
.AddInteractiveWebAssemblyRenderMode() |
||||
|
.AddAdditionalAssemblies(WebAppAdditionalAssembliesHelper.GetAssemblies<MyProjectNameBlazorClientModule>()); |
||||
|
}); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
**`MyCompanyName.MyProjectName.Blazor.csproj`:** |
||||
|
|
||||
|
```xml |
||||
|
<ItemGroup> |
||||
|
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.Server" Version="9.0.0.0" /> |
||||
|
<PackageReference Include="Volo.Abp.Autofac" Version="9.0.0" /> |
||||
|
<PackageReference Include="Volo.Abp.AspNetCore.Mvc.UI.Bundling" Version="9.0.0" /> |
||||
|
<PackageReference Include="Volo.Abp.AspNetCore.Components.WebAssembly.LeptonXLiteTheme.Bundling" Version="9.0.0" /> |
||||
|
<!-- <PackageReference Include="Volo.Abp.AspNetCore.Components.WebAssembly.LeptonXTheme.Bundling" Version="9.0.0" /> --> if you're using LeptonXTheme |
||||
|
<ProjectReference Include="..\MyProjectName.Blazor.Client\MyProjectName.Blazor.Client.csproj" /> |
||||
|
</ItemGroup> |
||||
|
``` |
||||
|
|
||||
|
### BlazorWebAssemblyBundlingModule in the ABP commercial |
||||
|
|
||||
|
Here is the list of `Bundling Modules` in the ABP commercial. If you're using the pro template, you should add them to the `MyCompanyName.MyProjectName.Blazor` project. |
||||
|
|
||||
|
| BundlingModules | Nuget Package | |
||||
|
|---------------------------------------------|-----------------------------------------------------| |
||||
|
| AbpAuditLoggingBlazorWebAssemblyBundlingModule | Volo.Abp.AuditLogging.Blazor.WebAssembly.Bundling | |
||||
|
| FileManagementBlazorWebAssemblyBundlingModule | Volo.FileManagement.Blazor.WebAssembly.Bundling | |
||||
|
| SaasHostBlazorWebAssemblyBundlingModule | Volo.Saas.Host.Blazor.WebAssembly.Bundling | |
||||
|
| ChatBlazorWebAssemblyBundlingModule | Volo.Chat.Blazor.WebAssembly.Bundling | |
||||
|
| CmsKitProAdminBlazorWebAssemblyBundlingModule | Volo.CmsKit.Pro.Admin.Blazor.WebAssembly.Bundling | |
||||
|
|
||||
|
|
||||
|
### MyCompanyName.MyProjectName.Blazor.Client |
||||
|
|
||||
|
1. Remove the `global.JavaScript/CSS` files from the `MyCompanyName.MyProjectName.Blazor`'s `wwwroot` folder. |
||||
|
2. Remove the `AbpCli:Bundle` section from the `appsettings.json` file. |
||||
|
3. Remove all BundleContributor classes that inherit from IBundleContributor. Then, create `MyProjectNameStyleBundleContributor` and `MyProjectNameScriptBundleContributor` classes to add your style and JavaScript files. Finally, add them to `AbpBundlingOptions`. |
||||
|
|
||||
|
|
||||
|
```cs |
||||
|
public class MyProjectNameStyleBundleContributor : BundleContributor |
||||
|
{ |
||||
|
public override void ConfigureBundle(BundleConfigurationContext context) |
||||
|
{ |
||||
|
context.Files.Add(new BundleFile("main.css", true)); |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
|
||||
|
public class MyProjectNameScriptBundleContributor : BundleContributor |
||||
|
{ |
||||
|
public override void ConfigureBundle(BundleConfigurationContext context) |
||||
|
{ |
||||
|
context.Files.Add(new BundleFile("main.js", true)); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
```cs |
||||
|
Configure<AbpBundlingOptions>(options => |
||||
|
{ |
||||
|
var globalStyles = options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global); |
||||
|
globalStyles.AddContributors(typeof(MyProjectNameStyleBundleContributor)); |
||||
|
|
||||
|
var globalScripts = options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global); |
||||
|
globalScripts.AddContributors(typeof(MyProjectNameScriptBundleContributor)); |
||||
|
}); |
||||
|
``` |
||||
|
|
||||
|
## Use the Global Assets in the Blazor WebApp |
||||
|
|
||||
|
### MyCompanyName.MyProjectName.Blazor.WebApp |
||||
|
|
||||
|
Depending on the `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` in your `MyCompanyName.MyProjectName.Blazor.WebApp` project. |
||||
|
|
||||
|
* The `AbpAspNetCoreComponentsWebAssemblyLeptonXLiteThemeBundlingModule/AbpAspNetCoreComponentsWebAssemblyLeptonXThemeBundlingModule` uses to add theme `JavaScript/CSS` to the bundling system. |
||||
|
|
||||
|
|
||||
|
### BlazorWebAssemblyBundlingModule in the ABP commercial |
||||
|
|
||||
|
Here is the list of `Bundling Modules` in the ABP commercial. If you're using the pro template, you should add them to the `MyCompanyName.MyProjectName.Blazor.WebApp` project. |
||||
|
|
||||
|
| BundlingModules | Nuget Package | |
||||
|
|---------------------------------------------|-----------------------------------------------------| |
||||
|
| AbpAuditLoggingBlazorWebAssemblyBundlingModule | Volo.Abp.AuditLogging.Blazor.WebAssembly.Bundling | |
||||
|
| FileManagementBlazorWebAssemblyBundlingModule | Volo.FileManagement.Blazor.WebAssembly.Bundling | |
||||
|
| SaasHostBlazorWebAssemblyBundlingModule | Volo.Saas.Host.Blazor.WebAssembly.Bundling | |
||||
|
| ChatBlazorWebAssemblyBundlingModule | Volo.Chat.Blazor.WebAssembly.Bundling | |
||||
|
| CmsKitProAdminBlazorWebAssemblyBundlingModule | Volo.CmsKit.Pro.Admin.Blazor.WebAssembly.Bundling | |
||||
|
|
||||
|
|
||||
|
### MyCompanyName.MyProjectName.Blazor.WebApp.Client |
||||
|
|
||||
|
1. Remove the `global.JavaScript/CSS` files from the `MyCompanyName.MyProjectName.Blazor.WebApp.Client`'s `wwwroot` folder. |
||||
|
2. Remove the `AbpCli:Bundle` section from the `appsettings.json` file. |
||||
|
3. Remove all BundleContributor classes that inherit from IBundleContributor. Then, create `MyProjectNameStyleBundleContributor` and `MyProjectNameScriptBundleContributor` classes to add your style and JavaScript files. Finally, add them to `AbpBundlingOptions`. |
||||
|
|
||||
|
```cs |
||||
|
public class MyProjectNameStyleBundleContributor : BundleContributor |
||||
|
{ |
||||
|
public override void ConfigureBundle(BundleConfigurationContext context) |
||||
|
{ |
||||
|
context.Files.Add(new BundleFile("main.css", true)); |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
|
||||
|
public class MyProjectNameScriptBundleContributor : BundleContributor |
||||
|
{ |
||||
|
public override void ConfigureBundle(BundleConfigurationContext context) |
||||
|
{ |
||||
|
context.Files.Add(new BundleFile("main.js", true)); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
```cs |
||||
|
Configure<AbpBundlingOptions>(options => |
||||
|
{ |
||||
|
var globalStyles = options.StyleBundles.Get(BlazorWebAssemblyStandardBundles.Styles.Global); |
||||
|
globalStyles.AddContributors(typeof(MyProjectNameStyleBundleContributor)); |
||||
|
|
||||
|
var globalScripts = options.ScriptBundles.Get(BlazorWebAssemblyStandardBundles.Scripts.Global); |
||||
|
globalScripts.AddContributors(typeof(MyProjectNameScriptBundleContributor)); |
||||
|
}); |
||||
|
``` |
||||
|
|
||||
|
### Check the Global Assets |
||||
|
|
||||
|
Run the `MyProject` project and check the `https://localhost/global.js` and `https://localhost/global.css` files. You should be able to see the `JavaScript/CSS` files content from the Bundling system: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
## GlobalAssets(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`. |
||||
|
|
||||
|
## Conclusion |
||||
|
|
||||
|
With the new `Global Assets` feature, you can easily bundle the `JavaScript/CSS` files in the Blazor wasm app. This feature is very useful for the Blazor wasm app, and it will save you a lot of time and effort. We hope you will enjoy this feature and use it in your projects. |
||||
|
|
||||
|
## References |
||||
|
|
||||
|
* [Virtual Files](https://docs.abp.io/en/abp/latest/Virtual-Files) |
||||
|
* [Bundle Contributors](https://abp.io/docs/latest/framework/ui/mvc-razor-pages/bundling-minification#bundle-contributors) |
||||
|
* [Global Assets Pull Request](https://github.com/abpframework/abp/pull/19968) |
||||
|
|
||||
|
After Width: | Height: | Size: 360 KiB |
@ -1,83 +1,72 @@ |
|||||
# Blazor UI: Managing Global Scripts & Styles |
# 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(...)` |
* `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. |
||||
* `AddStyles(...)` |
* `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 |
> Please use `BlazorWebAssemblyStandardBundles.Scripts.Global` and `BlazorWebAssemblyStandardBundles.Styles.Global` for the bundle name. |
||||
```csharp |
|
||||
namespace MyProject.Blazor |
```cs |
||||
|
public class MyModuleBundleScriptContributor : BundleContributor |
||||
{ |
{ |
||||
public class MyProjectBundleContributor : IBundleContributor |
public override void ConfigureBundle(BundleConfigurationContext context) |
||||
{ |
{ |
||||
public void AddScripts(BundleContext context) |
context.Files.AddIfNotContains("_content/MyModule.Blazor/libs/myscript.js"); |
||||
{ |
|
||||
context.Add("site.js"); |
|
||||
} |
|
||||
|
|
||||
public void AddStyles(BundleContext context) |
|
||||
{ |
|
||||
context.Add("main.css"); |
|
||||
context.Add("custom-styles.css"); |
|
||||
} |
|
||||
} |
} |
||||
} |
} |
||||
``` |
``` |
||||
|
|
||||
> 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. |
```cs |
||||
|
public class MyModuleBundleStyleContributor : BundleContributor |
||||
## 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 |
|
||||
{ |
{ |
||||
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")); |
Configure<AbpBundlingOptions>(options => |
||||
context.Add("mytheme.css", excludeFromBundle: excludeThemeFromBundle); |
{ |
||||
context.Add("main.css"); |
// 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) |
||||
|
|||||
@ -0,0 +1,107 @@ |
|||||
|
# Prerequisites for Developing ABP Applications |
||||
|
|
||||
|
This document will guide you through preparing your development environment for ABP based application development. |
||||
|
|
||||
|
## Notices |
||||
|
|
||||
|
The prerequisites mentioned in this document are not necessary for every project type; |
||||
|
|
||||
|
* You don't need to install the EF Core CLI if your application uses MongoDB instead of EF Core. |
||||
|
* You don't need to install Helm, NGINX Ingress, or mkcert if you are developing a non-microservice application. |
||||
|
|
||||
|
`README.MD` files in new solutions contain specific requirements for your solution. Please refer to the `README.MD` file of your solution. |
||||
|
|
||||
|
## IDE |
||||
|
|
||||
|
You need to use an IDE that supports .NET development. The following IDEs are the most popular ones for .NET development. |
||||
|
|
||||
|
### Visual Studio |
||||
|
|
||||
|
Visual Studio is Microsoft's IDE and is the de facto tool for developing .NET projects. You can download Visual Studio from the [Visual Studio official website](https://visualstudio.microsoft.com/). It also has a **free Community edition** which is more than enough for ABP projects. |
||||
|
|
||||
|
### Visual Studio Code |
||||
|
|
||||
|
Visual Studio Code is a **free and cross-platform** lightweight code editor that supports .NET development. You can [download from here](https://code.visualstudio.com/download). |
||||
|
|
||||
|
### JetBrains Rider |
||||
|
|
||||
|
[JetBrains Rider](https://www.jetbrains.com/rider/download) is a cross-platform IDE by [JetBrains](https://www.jetbrains.com/) that supports .NET development. It is **[free for non-commercial use](https://blog.jetbrains.com/blog/2024/10/24/webstorm-and-rider-are-now-free-for-non-commercial-use/)**. |
||||
|
|
||||
|
## .NET SDK |
||||
|
|
||||
|
ABP is based on NET, so you need to install the .NET SDK. You can download the .NET SDK from the [.NET official website](https://dotnet.microsoft.com/en-us/download/dotnet/9.0). |
||||
|
|
||||
|
> Installing Visual Studio or JetBrains Rider may automatically install the .NET SDK. |
||||
|
|
||||
|
### EF Core CLI |
||||
|
|
||||
|
If you are using [Entity Framework Core](https://learn.microsoft.com/en-us/ef/core/) as your database access provider, you need to install the [EF Core CLI](https://learn.microsoft.com/en-us/ef/core/cli/dotnet). You can install it by running the following command: |
||||
|
|
||||
|
```bash |
||||
|
dotnet tool install --global dotnet-ef |
||||
|
``` |
||||
|
|
||||
|
If you have already installed the `EF Core CLI`, you can update it by running the following command: |
||||
|
|
||||
|
```bash |
||||
|
dotnet tool update --global dotnet-ef |
||||
|
``` |
||||
|
|
||||
|
## Node.js and Yarn |
||||
|
|
||||
|
ABP projects include some frontend resource packages, so you need to install Node.js and Yarn to manage these resource packages. You can download Node.js from the [official Node.js website](https://nodejs.org/). We recommend installing version v20.11+. |
||||
|
|
||||
|
Using Yarn (classic) to manage frontend resource packages is faster and more stable than using npm. You can download `Yarn` from the [Yarn official website](https://classic.yarnpkg.com/en/docs/install). We recommend installing Yarn v1.22+ (make sure to install the Classic version, not v2+). |
||||
|
|
||||
|
To install Yarn using npm, run the following command: |
||||
|
|
||||
|
```bash |
||||
|
npm install --global yarn |
||||
|
``` |
||||
|
|
||||
|
## Docker Engine or Docker Desktop |
||||
|
|
||||
|
ABP's [Layered Solution](../solution-templates/layered-web-application/index.md) and [Microservice Solution](../solution-templates/microservice/index.md) use Docker to run infrastructure services (e.g. SQL Server, Redis, RabbitMQ) required by your application. You can install Docker Engine or Docker Desktop (recommended) on Windows, macOS and Linux. |
||||
|
|
||||
|
* [Docker Desktop](https://www.docker.com/products/docker-desktop/) (recommended) |
||||
|
* [Docker Engine](https://docs.docker.com/engine/install/) |
||||
|
|
||||
|
### Is Docker Engine or Docker Desktop Free? |
||||
|
|
||||
|
Docker Engine is an open-source and free containerization technology for building and containerizing your applications. [`Docker Engine` follows the Apache License 2.0](https://docs.docker.com/engine/#licensing). |
||||
|
|
||||
|
Docker Desktop is free [for small businesses (fewer than 250 employees and less than $10 million in annual revenue), personal use, education, and non-commercial open-source projects](https://docs.docker.com/subscription/desktop-license/). |
||||
|
|
||||
|
## PowerShell |
||||
|
|
||||
|
ABP startup solution templates and tools use some PowerShell scripts (`*.ps1`) to perform certain tasks. You can refer to the [PowerShell documentation](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) for guidance on how to install PowerShell on Windows, macOS, and Linux. |
||||
|
|
||||
|
* [Install PowerShell on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) |
||||
|
* [Install PowerShell on macOS](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-macos) |
||||
|
* [Install PowerShell on Linux](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux) |
||||
|
|
||||
|
## MicroService Solution |
||||
|
|
||||
|
The following tools are only required to develop ABP's [microservice solution](../solution-templates/microservice/index.md) |
||||
|
|
||||
|
### Helm |
||||
|
|
||||
|
[Helm](https://helm.sh/) is a package manager for Kubernetes. You can install Helm by following the [Helm installation guide](https://helm.sh/docs/intro/install/). |
||||
|
|
||||
|
See [Helm Deployment on Local Kubernetes Cluster](../solution-templates/microservice/helm-charts-and-kubernetes.md) for more information. |
||||
|
|
||||
|
### NGINX Ingress or NGINX Ingress using Helm |
||||
|
|
||||
|
[NGINX Ingress](https://kubernetes.github.io/ingress-nginx/deploy/) is an Ingress controller for Kubernetes. You can install NGINX Ingress by following the [NGINX Ingress installation guide](https://kubernetes.github.io/ingress-nginx/deploy/). |
||||
|
|
||||
|
If you are using Helm, you can install NGINX Ingress using the following commands: |
||||
|
|
||||
|
```cs |
||||
|
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx |
||||
|
helm repo update |
||||
|
helm upgrade --install --version=4.0.19 ingress-nginx ingress-nginx/ingress-nginx |
||||
|
``` |
||||
|
|
||||
|
### mkcert |
||||
|
|
||||
|
Use mkcert to generate trusted certificates for local development. You can install mkcert by following the [official mkcert installation guide](https://github.com/FiloSottile/mkcert#installation). |
||||
@ -0,0 +1,6 @@ |
|||||
|
# ABP Knowledge Base |
||||
|
|
||||
|
The following documents provide useful information about several topics you might need to know. |
||||
|
|
||||
|
* [How to Fix "Filename too long" Error on Windows](windows-path-too-long-fix.md) |
||||
|
* [When to Use a Distributed Cache Server](when-to-use-a-distributed-cache-server.md) |
||||
@ -0,0 +1,49 @@ |
|||||
|
# When to Use a Distributed Cache Server |
||||
|
|
||||
|
ABP provides a [distributed cache service](../framework/fundamentals/caching.md) that is based on [ASP.NET Core's distributed cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed). This document explains when you need to have a separate cache server for your applications. |
||||
|
|
||||
|
## Understanding the Default Cache Service |
||||
|
|
||||
|
**Default implementation of the cache service works in-memory**. Memory cache is only useful if you are building a monolith application and you run a single instance of your application. For other cases, **you should use a real distributed cache server**. |
||||
|
|
||||
|
Here are a few example cases where you should use a distributed cache server: |
||||
|
|
||||
|
* You have a **monolith application**, but you run **multiple instances** of that application concurrently, for example, in a [clustered environment](../deployment/clustered-environment.md) |
||||
|
* You build a **microservice** or any kind of **distributed** system |
||||
|
* You have web **multiple applications** in your solution and they should share the same cache |
||||
|
|
||||
|
The problem is obvious: If each application instance uses its internal in-memory cache, and if two or more applications cache the same data, it is probable that they will cache different copies of the data. In that case, there is no way to **invalidate/refresh** that data in every application's memory when the data changes. |
||||
|
|
||||
|
## What is a Distributed Cache Server |
||||
|
|
||||
|
A **distributed cache server** (e.g. [Redis](../framework/fundamentals/redis-cache.md)) stores cache objects in a separate server application and allows multiple applications/processes to share the same cache objects. In that way; |
||||
|
|
||||
|
* All applications/services and all their instances use the same cache store and share the same cached objects. Once an application instance refreshes a cached object, all others use the new object. |
||||
|
* Even if your applications stop and restart, the cached objects are not lost, since they are managed by a separate cache server. |
||||
|
|
||||
|
## How to Use a Distributed Cache Server |
||||
|
|
||||
|
ABP [solution templates](../solution-templates/index.md) come with Redis configured when it is certainly necessary. For example; |
||||
|
|
||||
|
* The [microservice startup template](../solution-templates/microservice/index.md) always comes with [Redis configured](../solution-templates/microservice/distributed-cache.md) and also included as a docker container. |
||||
|
|
||||
|
* The application startup template comes with Redis configured when you select multiple applications, tiered architecture, or some other configuration that requires a distributed cache server. |
||||
|
|
||||
|
In other cases, to keep the dependencies minimal, they come with the default (in-memory) cache configuration. In those cases, if you need a distributed cache server, you should manually switch to a distributed cache provider for your application. |
||||
|
|
||||
|
See the *[Redis Cache](../framework/fundamentals/redis-cache.md)* document if you need to use Redis as the distributed cache server. See [ASP.NET Core's documentation](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) to see how to switch to another cache provider. |
||||
|
|
||||
|
### Installing a Redis Server to Your Local Environment |
||||
|
|
||||
|
If you want to use Redis as your distributed cache provider in your development environment, you can simply use the [official Redis docker image](https://hub.docker.com/_/redis). Once you have [Docker](https://www.docker.com/products/docker-desktop/) in your local machine, you can use the following command to run a Redis container and map the default Redis port: |
||||
|
|
||||
|
````bash |
||||
|
docker run -p 6379:6379 --name RedisServer -d redis |
||||
|
```` |
||||
|
|
||||
|
You can check the [official Redis docker image](https://hub.docker.com/_/redis) document for more options. |
||||
|
|
||||
|
## See Also |
||||
|
|
||||
|
* [ABP Distributed Cache](../framework/fundamentals/caching.md) |
||||
|
* [ASP.NET Core Distributed Cache](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed) |
||||
@ -0,0 +1,28 @@ |
|||||
|
# OpenIddict 5.x to 6.x Migration Guide |
||||
|
|
||||
|
The 6.0 release of OpenIddict is a major release that introduces breaking changes. |
||||
|
|
||||
|
Check this blog [OpenIddict 6.0 general availability](https://kevinchalet.com/2024/12/17/openiddict-6-0-general-availability/) for the new features introduced in OpenIddict 6.0. and the [Migrate to OpenIddict 6.0](https://documentation.openiddict.com/guides/migration/50-to-60) for more information about the changes. |
||||
|
|
||||
|
In this guide, we will explain the changes you need to make to your ABP application. |
||||
|
|
||||
|
## Constant changes |
||||
|
|
||||
|
The following constants have been renamed: |
||||
|
|
||||
|
| Old Constant Name | New Constant Name | |
||||
|
|---------------------------------------------------------------|-----------------------------------------------------------------| |
||||
|
| `OpenIddictConstants.Permissions.Endpoints.Logout` | `OpenIddictConstants.Permissions.Endpoints.EndSession` | |
||||
|
| `OpenIddictConstants.Permissions.Endpoints.Device` | `OpenIddictConstants.Permissions.Endpoints.DeviceAuthorization` | |
||||
|
|
||||
|
|
||||
|
## IdentityModel packages |
||||
|
|
||||
|
If you have a reference to `IdentityModel` directly, please upgrade the necessary package versions to the latest stable version, which is currently 8.3.0: |
||||
|
|
||||
|
* [System.IdentityModel.Tokens.Jwt](https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/) |
||||
|
* [Microsoft.IdentityModel.Protocols.OpenIdConnect](https://www.nuget.org/packages/Microsoft.IdentityModel.Protocols.OpenIdConnect/) |
||||
|
* [Microsoft.IdentityModel.Tokens](https://www.nuget.org/packages/Microsoft.IdentityModel.Tokens/) |
||||
|
* [Microsoft.IdentityModel.JsonWebTokens](https://www.nuget.org/packages/Microsoft.IdentityModel.JsonWebTokens/) |
||||
|
|
||||
|
That's all, it's a simple migration! If you have advanced usage of OpenIddict, please check the [official migration guide](https://documentation.openiddict.com/guides/migration/50-to-60) for more information. |
||||
|
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 |
@ -0,0 +1,56 @@ |
|||||
|
# Layered Solution: Authentication |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Built-In Features", |
||||
|
"Path": "solution-templates/layered-web-application/built-in-features" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Database configurations in the Layered solution", |
||||
|
"Path": "solution-templates/layered-web-application/database-configurations" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
||||
|
|
||||
|
The [Layered solution template](index.md) is fully configured for authentication. All the services and applications are configured to use the [OpenIddict](https://documentation.openiddict.com) library for authentication. They are configured in a common way for authentication. This document explains that common authentication structure. |
||||
|
|
||||
|
If you choose the *Tiered* option while [creating](../../get-started/layered-web-application.md#creating-a-new-solution) the solution, the solution will have the `*.AuthServer` project. |
||||
|
|
||||
|
## OpenIddict |
||||
|
|
||||
|
[OpenIddict](https://documentation.openiddict.com) is an open-source library that provides a simple and easy way to implement an OpenID Connect server in your application. ABP has built-in modules ([OpenIddict](../../modules/openiddict.md), [OpenIddict UI **\***](../../modules/openiddict-pro.md)) to integrate OpenIddict into the solution. |
||||
|
|
||||
|
## Domain Layer |
||||
|
|
||||
|
The layered solution template *Domain* layer is the responsible for the OpenIddict definitions (Applications, Scopes, etc.). Also, it provides the *OpenIddictDataSeedContributor* class to seed the initial data. It creates the default clients (applications) and scopes for the solution. |
||||
|
|
||||
|
The [OpenIddict UI **\***](../../modules/openiddict-pro.md) module is added only if you choose the OpenIddict UI module while creating the solution. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
The OpenIddict UI **\*** module provides a user interface to manage the OpenIddict entities such as applications, scopes, etc. You can manage these entities from the application UI. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
## The Authentication Application |
||||
|
|
||||
|
The solution may include an external authentication server (`auth-server`) application if you select the *Tiered* option during solution creation. Otherwise, the authentication server is integrated into one of the [Web Applications](web-applications.md). |
||||
|
|
||||
|
The authentication server handles token generation, validation, and user account management (e.g., login, registration). It uses the [Account](../../modules/account.md) or [Account Pro **\***](../../modules/account-pro.md) module. The [Account Pro **\***](../../modules/account-pro.md) module additionally supports [social logins](../../modules/account-pro.md#social--external-logins) (e.g., Google, Facebook). Social logins can be enabled, disabled, and configured directly from the application's user interface. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
## Authentication Flows |
||||
|
|
||||
|
Applications in the solution use different authentication flows depending on the application type: |
||||
|
|
||||
|
- **MVC UI Web Application**: |
||||
|
Uses the [Hybrid Flow](https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth) (OpenID Connect Authentication) for user authentication. |
||||
|
- **SPA and Swagger Applications**: |
||||
|
Use the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) to authenticate users. |
||||
|
|
||||
|
Once a user logs into the system and obtains a token from the authentication server, the `*.HttpApi.Host` application use [JWT Bearer Authentication](https://jwt.io/introduction/) to authorize the user's actions. |
||||
@ -0,0 +1,51 @@ |
|||||
|
# Layered Solution: BLOB Storing |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Multi-Tenancy", |
||||
|
"Path": "solution-templates/layered-web-application/multi-tenancy" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "CORS Configuration", |
||||
|
"Path": "solution-templates/layered-web-application/cors-configuration" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
||||
|
|
||||
|
This document explains how to store BLOBs (Binary Large Objects) in a layered solution. It is common to store files, images, videos, and other large objects in a distributed system. You can learn more about BLOB storage in the [BLOB Storing System](../../framework/infrastructure/blob-storing/index.md) documentation. |
||||
|
|
||||
|
In the layered solution template, the [Database Provider](../../framework/infrastructure/blob-storing/database.md) is used to store BLOBs in the database. The `Volo.Abp.BlobStoring.Database.EntityFrameworkCore` or `Volo.Abp.BlobStoring.Database.MongoDB` package provides the necessary implementations to store and retrieve BLOBs in the database. This setup is integrated into the layered solution template and is used in all related projects. You can change the database configuration in the `appsettings.json` file of the related project. |
||||
|
|
||||
|
You can use the `IBlobContainer` or `IBlobContainer<T>` service to store and retrieve BLOBs. Here is an example of storing a BLOB: |
||||
|
|
||||
|
```csharp |
||||
|
public class MyService : ITransientDependency |
||||
|
{ |
||||
|
private readonly IBlobContainer _blobContainer; |
||||
|
|
||||
|
public MyService(IBlobContainer blobContainer) |
||||
|
{ |
||||
|
_blobContainer = blobContainer; |
||||
|
} |
||||
|
|
||||
|
public async Task SaveBytesAsync(byte[] bytes) |
||||
|
{ |
||||
|
await _blobContainer.SaveAsync("my-blob-1", bytes); |
||||
|
} |
||||
|
|
||||
|
public async Task<byte[]> GetBytesAsync() |
||||
|
{ |
||||
|
return await _blobContainer.GetAllBytesOrNullAsync("my-blob-1"); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
## 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 to manage folders and files. You can learn more about the module in the [File Management *](../../modules/file-management.md) document. |
||||
|
|
||||
|
 |
||||
@ -0,0 +1,25 @@ |
|||||
|
# Layered Solution: Built-In Features |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Mobile Applications", |
||||
|
"Path": "solution-templates/layered-web-application/mobile-applications" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Authentication", |
||||
|
"Path": "solution-templates/layered-web-application/authentication" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
The Layered solution template includes several built-in features to help you get started with your layered web application. These features are designed to provide a solid foundation for your application and help you focus on your business logic. This document provides an overview of the built-in features included in the Layered solution template. The following documents explains these features in details: |
||||
|
|
||||
|
* [Authentication](authentication.md) |
||||
|
* [Database configurations](database-configurations.md) |
||||
|
* [Logging (with Serilog)](logging.md) |
||||
|
* [Swagger integration](swagger-integration.md) |
||||
|
* [Multi-Tenancy](multi-tenancy.md) |
||||
|
* [BLOB storing](blob-storing.md) |
||||
|
* [CORS configuration](cors-configuration.md) |
||||
@ -0,0 +1,37 @@ |
|||||
|
# Layered Solution: CORS Configuration |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "BLOB Storing", |
||||
|
"Path": "solution-templates/layered-web-application/blob-storing" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Helm Charts and Kubernetes", |
||||
|
"Path": "solution-templates/layered-web-application/helm-charts-and-kubernetes" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Cross-Origin Resource Sharing (CORS) is a security feature that allows web applications to make requests to a different domain than the one that served the web page. |
||||
|
|
||||
|
In the layered solution template, CORS configuration is applied in the following cases: |
||||
|
- If you select the [Tiered solution](solution-structure.md#tiered-structure-). |
||||
|
- If you choose [Angular](web-applications.md#angular) as the web application type. |
||||
|
- If you choose [Blazor WebAssembly](web-applications.md#blazor-webassembly) as the web application type. |
||||
|
- If you choose [No UI](web-applications.md#no-ui) as the web application type. |
||||
|
|
||||
|
The CORS settings are configured in the `appsettings.json` file of the corresponding project. Typically, the web application serves as the entry point for front-end applications, so it must be configured to accept requests from different origins. |
||||
|
|
||||
|
The default configuration in `appsettings.json` is as follows: |
||||
|
|
||||
|
```json |
||||
|
{ |
||||
|
"App": { |
||||
|
"CorsOrigins": "https://*.MyProjectName.com" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
You can modify the `CorsOrigins` property to include additional domains or wildcard subdomains as required by your application. |
||||
@ -0,0 +1,266 @@ |
|||||
|
# Layered Solution: Database configurations |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Authentication", |
||||
|
"Path": "solution-templates/layered-web-application/authentication" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Logging (with Serilog)", |
||||
|
"Path": "solution-templates/layered-web-application/logging" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
||||
|
|
||||
|
ABP Studio's Layered Solution Template includes pre-configured database settings. This document explains how to manage database configurations in your solution. |
||||
|
|
||||
|
## Connection Strings |
||||
|
|
||||
|
Connection strings are stored in the `appsettings.json` file. You can customize them for different environments by modifying the respective `appsettings.json` files. The `*.DbMigrator` project and one of the [Web Application](web-applications.md) projects use the `Default` connection string by default. |
||||
|
|
||||
|
To change the connection string for the `Default` key, update the `appsettings.json` file in your project. Connection strings are defined under the `ConnectionStrings` section, as shown below: |
||||
|
|
||||
|
```json |
||||
|
{ |
||||
|
"ConnectionStrings": { |
||||
|
"Default": "Server=(LocalDb)\\MSSQLLocalDB;Database=Bookstore;Trusted_Connection=True;TrustServerCertificate=true" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### The DbContext Class |
||||
|
|
||||
|
In the `*.EntityFrameworkCore` project, the `DbContext` class is defined. The `DbContext` class is derived from the `AbpDbContext` class, which is a part of the ABP Framework. |
||||
|
|
||||
|
```csharp |
||||
|
[ReplaceDbContext(typeof(IIdentityProDbContext))] |
||||
|
[ReplaceDbContext(typeof(ISaasDbContext))] |
||||
|
[ConnectionStringName("Default")] |
||||
|
public class BookstoreDbContext : |
||||
|
AbpDbContext<BookstoreDbContext>, |
||||
|
ISaasDbContext, |
||||
|
IIdentityProDbContext |
||||
|
{ |
||||
|
#region Entities from the modules |
||||
|
|
||||
|
// Identity |
||||
|
public DbSet<IdentityUser> Users { get; set; } |
||||
|
public DbSet<IdentityRole> Roles { get; set; } |
||||
|
public DbSet<IdentityClaimType> ClaimTypes { get; set; } |
||||
|
public DbSet<OrganizationUnit> OrganizationUnits { get; set; } |
||||
|
public DbSet<IdentitySecurityLog> SecurityLogs { get; set; } |
||||
|
public DbSet<IdentityLinkUser> LinkUsers { get; set; } |
||||
|
public DbSet<IdentityUserDelegation> UserDelegations { get; set; } |
||||
|
public DbSet<IdentitySession> Sessions { get; set; } |
||||
|
|
||||
|
// SaaS |
||||
|
public DbSet<Tenant> Tenants { get; set; } |
||||
|
public DbSet<Edition> Editions { get; set; } |
||||
|
public DbSet<TenantConnectionString> TenantConnectionStrings { get; set; } |
||||
|
|
||||
|
#endregion |
||||
|
|
||||
|
public BookstoreDbContext(DbContextOptions<BookstoreDbContext> options) |
||||
|
: base(options) |
||||
|
{ |
||||
|
|
||||
|
} |
||||
|
|
||||
|
protected override void OnModelCreating(ModelBuilder builder) |
||||
|
{ |
||||
|
base.OnModelCreating(builder); |
||||
|
|
||||
|
builder.ConfigurePermissionManagement(); |
||||
|
builder.ConfigureSettingManagement(); |
||||
|
builder.ConfigureBackgroundJobs(); |
||||
|
builder.ConfigureAuditLogging(); |
||||
|
builder.ConfigureFeatureManagement(); |
||||
|
builder.ConfigureIdentityPro(); |
||||
|
builder.ConfigureOpenIddictPro(); |
||||
|
builder.ConfigureLanguageManagement(); |
||||
|
builder.ConfigureSaas(); |
||||
|
builder.ConfigureTextTemplateManagement(); |
||||
|
builder.ConfigureGdpr(); |
||||
|
builder.ConfigureCmsKit(); |
||||
|
builder.ConfigureCmsKitPro(); |
||||
|
builder.ConfigureBlobStoring(); |
||||
|
|
||||
|
/* Configure your own tables/entities inside here */ |
||||
|
|
||||
|
//builder.Entity<YourEntity>(b => |
||||
|
//{ |
||||
|
// b.ToTable(BookstoreConsts.DbTablePrefix + "YourEntities", BookstoreConsts.DbSchema); |
||||
|
// b.ConfigureByConvention(); //auto configure for the base class props |
||||
|
// //... |
||||
|
//}); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
#### ConnectionStringName Attribute |
||||
|
|
||||
|
We're using the *Default* connection string in the `BookstoreDbContext` class. You can change the connection string name by updating the `ConnectionStringName` attribute. |
||||
|
|
||||
|
```csharp |
||||
|
[ConnectionStringName("Default")] |
||||
|
``` |
||||
|
|
||||
|
[The `ConnectionStringName` attribute](../../framework/fundamentals/connection-strings.md#set-the-connection-string-name) defines the unique name of the connection string that is being used by that `DbContext` class. It matches with the connection string defined in the `appsettings.json` file. That name is also used in database migrations to distinguish different database schemas, and used as the key while storing tenant connection strings for a multi-tenant system. |
||||
|
|
||||
|
#### ReplaceDbContext Attribute |
||||
|
|
||||
|
```csharp |
||||
|
[ReplaceDbContext(typeof(IIdentityProDbContext))] |
||||
|
[ReplaceDbContext(typeof(ISaasDbContext))] |
||||
|
``` |
||||
|
|
||||
|
The application DbContext utilizes the [Identity](../../modules/identity.md) and [Saas **\***](../../modules/saas.md) modules and creates a single database that contains these modules database schemas. These modules define their own `DbContext` class normally. But [the `ReplaceDbContext` attribute](../../framework/data/entity-framework-core/index.md#replace-other-dbcontextes) tells to ABP to use this (`BookstoreDbContext`) `DbContext` class instead of the `DbContext` classes defined by these modules. Technically, it replaces the given `DbContext` classes on runtime. We are doing that to ensure that we have a single (merged) database schema, single database migration path and a single database transaction operation when we work these multiple modules. When we replace a `DbContext`, we should implement its interface as done with the `BookstoreDbContext` class: |
||||
|
|
||||
|
````csharp |
||||
|
public class BookstoreDbContext : |
||||
|
AbpDbContext<BookstoreDbContext>, |
||||
|
ISaasDbContext, |
||||
|
IIdentityProDbContext |
||||
|
```` |
||||
|
|
||||
|
* That class implements `ISaasDbContext` and `IIdentityProDbContext`, so these modules can use it. |
||||
|
|
||||
|
As the next part, the `BookstoreDbContext` class defines the following properties those are forced by the implemented interfaces: |
||||
|
|
||||
|
```csharp |
||||
|
// Identity |
||||
|
public DbSet<IdentityUser> Users { get; set; } |
||||
|
public DbSet<IdentityRole> Roles { get; set; } |
||||
|
public DbSet<IdentityClaimType> ClaimTypes { get; set; } |
||||
|
public DbSet<OrganizationUnit> OrganizationUnits { get; set; } |
||||
|
public DbSet<IdentitySecurityLog> SecurityLogs { get; set; } |
||||
|
public DbSet<IdentityLinkUser> LinkUsers { get; set; } |
||||
|
public DbSet<IdentityUserDelegation> UserDelegations { get; set; } |
||||
|
public DbSet<IdentitySession> Sessions { get; set; } |
||||
|
|
||||
|
// SaaS |
||||
|
public DbSet<Tenant> Tenants { get; set; } |
||||
|
public DbSet<Edition> Editions { get; set; } |
||||
|
public DbSet<TenantConnectionString> TenantConnectionStrings { get; set; } |
||||
|
``` |
||||
|
|
||||
|
#### OnModelCreating Method |
||||
|
|
||||
|
The `OnModelCreating` method is used to configure the database schema. It calls the `Configure*` methods of the ABP Framework to configure the database schema for the modules. You can also configure your own tables/entities inside this method. |
||||
|
|
||||
|
```csharp |
||||
|
protected override void OnModelCreating(ModelBuilder builder) |
||||
|
{ |
||||
|
base.OnModelCreating(builder); |
||||
|
|
||||
|
builder.ConfigurePermissionManagement(); |
||||
|
builder.ConfigureSettingManagement(); |
||||
|
builder.ConfigureBackgroundJobs(); |
||||
|
builder.ConfigureAuditLogging(); |
||||
|
builder.ConfigureFeatureManagement(); |
||||
|
builder.ConfigureIdentityPro(); |
||||
|
builder.ConfigureOpenIddictPro(); |
||||
|
builder.ConfigureLanguageManagement(); |
||||
|
builder.ConfigureSaas(); |
||||
|
builder.ConfigureTextTemplateManagement(); |
||||
|
builder.ConfigureGdpr(); |
||||
|
builder.ConfigureCmsKit(); |
||||
|
builder.ConfigureCmsKitPro(); |
||||
|
builder.ConfigureBlobStoring(); |
||||
|
|
||||
|
/* Configure your own tables/entities inside here */ |
||||
|
|
||||
|
//builder.Entity<YourEntity>(b => |
||||
|
//{ |
||||
|
// b.ToTable(BookstoreConsts.DbTablePrefix + "YourEntities", BookstoreConsts.DbSchema); |
||||
|
// b.ConfigureByConvention(); //auto configure for the base class props |
||||
|
// //... |
||||
|
//}); |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
> The `Configure*` methods are extension methods defined in each module's `EntityFrameworkCore` project. These methods are used to configure the database schema for their respective modules. At runtime, the `DbContext` class is replaced by the `BookstoreDbContext` class only for the `DbContext` classes that use the `ReplaceDbContext` attribute. For other modules, their own dedicated `DbContext` classes are used without replacement. |
||||
|
|
||||
|
### The `IDesignTimeDbContextFactory` Implementation |
||||
|
|
||||
|
The `IDesignTimeDbContextFactory` interface is used to create a `DbContext` instance at design time. It is used by EF Core tools to create migrations and update the database. The `BookstoreDbContextFactory` class implements the `IDesignTimeDbContextFactory` interface to create a `BookstoreMigrationsDbContext` instance. |
||||
|
|
||||
|
```csharp |
||||
|
public class BookstoreDbContextFactory : IDesignTimeDbContextFactory<BookstoreDbContext> |
||||
|
{ |
||||
|
public BookstoreDbContext CreateDbContext(string[] args) |
||||
|
{ |
||||
|
var configuration = BuildConfiguration(); |
||||
|
|
||||
|
BookstoreEfCoreEntityExtensionMappings.Configure(); |
||||
|
|
||||
|
var builder = new DbContextOptionsBuilder<BookstoreDbContext>() |
||||
|
.UseSqlServer(configuration.GetConnectionString("Default")); |
||||
|
|
||||
|
return new BookstoreDbContext(builder.Options); |
||||
|
} |
||||
|
|
||||
|
private static IConfigurationRoot BuildConfiguration() |
||||
|
{ |
||||
|
var builder = new ConfigurationBuilder() |
||||
|
.SetBasePath(Path.Combine(Directory.GetCurrentDirectory(), "../Acme.Bookstore.DbMigrator/")) |
||||
|
.AddJsonFile("appsettings.json", optional: false); |
||||
|
|
||||
|
return builder.Build(); |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### Configuration |
||||
|
|
||||
|
In the `*.EntityFrameworkCore` project, the `BookstoreEntityFrameworkCoreModule` class is used to configure the database context. |
||||
|
|
||||
|
```csharp |
||||
|
public override void ConfigureServices(ServiceConfigurationContext context) |
||||
|
{ |
||||
|
context.Services.AddAbpDbContext<BookstoreDbContext>(options => |
||||
|
{ |
||||
|
/* Remove "includeAllEntities: true" to create |
||||
|
* default repositories only for aggregate roots */ |
||||
|
options.AddDefaultRepositories(includeAllEntities: true); |
||||
|
}); |
||||
|
|
||||
|
Configure<AbpDbContextOptions>(options => |
||||
|
{ |
||||
|
/* The main point to change your DBMS. |
||||
|
* See also BookstoreDbContextFactory for EF Core tooling. */ |
||||
|
options.UseSqlServer(); |
||||
|
}); |
||||
|
|
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
We are basically setting the SQL Server as the default DBMS for this application. and registering the `BookstoreDbContext` class to the [dependency injection](../../framework/fundamentals/dependency-injection.md) system. |
||||
|
|
||||
|
### SaaS Module: The Tenant Management UI **\*** |
||||
|
|
||||
|
SaaS module provides the necessary UI to set and change connection string for tenants and trigger the database migrations. |
||||
|
|
||||
|
#### The Connection String Management Modal |
||||
|
|
||||
|
You can click to the *Database Connection Strings* command in the *Actions* dropdown button for a tenant in the *Tenants* page of the SaaS module: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
It opens the *Database Connection Strings* modal as shown below: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
Here, we can set a *Default connection string* for the tenant. |
||||
|
|
||||
|
When you make the changes and save the dialog, the database is automatically created and migrated. If you later update the connection string (for example if you change the database name), it will also trigger the database migration process again. |
||||
|
|
||||
|
#### Manually Applying the Database Migrations |
||||
|
|
||||
|
If you need to manually trigger the database migrations for a specific tenant, click the *Actions* dropdown for the related tenant and select the *Apply Database Migrations* command on the *Tenant Management* page of the SaaS module: |
||||
|
|
||||
|
 |
||||
@ -0,0 +1,41 @@ |
|||||
|
# Layered Solution: Db Migrator |
||||
|
|
||||
|
````json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Web Applications", |
||||
|
"Path": "solution-templates/layered-web-application/web-applications" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Mobile Applications", |
||||
|
"Path": "solution-templates/layered-web-application/mobile-applications" |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
## Db Migrator Project |
||||
|
|
||||
|
The Db Migrator project is a console application designed to handle database schema migrations and seed data population. It operates as a standalone application that can be executed on-demand or integrated into a CI/CD pipeline. |
||||
|
|
||||
|
### Usage |
||||
|
|
||||
|
You can run the Db Migrator application: |
||||
|
- From the command line. |
||||
|
- Directly from Visual Studio. |
||||
|
|
||||
|
### Configuration |
||||
|
|
||||
|
The Db Migrator project maintains its own configuration, separate from the main application. If you need to update the database connection string or any related settings, ensure that changes are applied consistently to both the main application and the Db Migrator to avoid discrepancies. |
||||
|
|
||||
|
## Folder Structure |
||||
|
|
||||
|
In the `*.DbMigrator` project, you will find the `DbMigratorHostedService` class, which is responsible for executing database migrations and seeding data. This class is registered in the `Program` class and starts running when the application is launched. |
||||
|
|
||||
|
### Layers and Responsibilities |
||||
|
|
||||
|
- **`*.Domain` Layer**: |
||||
|
Contains the `Data` folder, which holds the necessary classes for managing database migrations and seed data. However, since the `*.Domain` layer does not reference the `EntityFrameworkCore` package, it only defines the abstraction for data migration. |
||||
|
|
||||
|
- **`*.EntityFrameworkCore` Layer**: |
||||
|
This layer is responsible for implementing database schema migrations. It includes the `EntityFrameworkCore[ProjectName]DbSchemaMigrator` class, which handles the actual migration logic using the `EntityFrameworkCore` package. |
||||
@ -0,0 +1,65 @@ |
|||||
|
# Layered Solution: Helm Charts and Kubernetes |
||||
|
|
||||
|
````json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "CORS configuration", |
||||
|
"Path": "solution-templates/layered-web-application/cors-configuration" |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
> You must have an ABP Business or a higher license to be able to use the Kubernetes features. |
||||
|
|
||||
|
This document explains how to deploy the layered solution to a Kubernetes cluster using [Helm](https://helm.sh/) charts. The layered solution template includes Helm charts for each application and infrastructure (Redis, RabbitMQ, etc). You can use these charts to deploy the solution to a Kubernetes cluster. You can see the Helm charts in the `etc/helm` folder of the solution. |
||||
|
|
||||
|
## Folder Structure |
||||
|
|
||||
|
The folder structure of the Helm charts is as follows: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
> You might have different charts based on the solution template options you selected while creating the solution. |
||||
|
|
||||
|
* **bookstore**: The Helm chart for the `Bookstore` solution. The folder name should be the same as your project name. |
||||
|
* **charts**: The sub-charts of the solution. Each application and infrastructure has its own chart. |
||||
|
* **templates**: The templates of the solution. It includes the ingress host URLs. |
||||
|
* **Chart.yaml**: The chart metadata. |
||||
|
* **values.bookstore-local.yaml**: The override values file for the [Kubernetes profile](../../studio/kubernetes.md#profile). It should follow the naming convention for your project name. |
||||
|
* **values.yaml**: The default values file for the chart. |
||||
|
* **build-all-images.ps1**: A PowerShell script to build all Docker images of the solution. |
||||
|
* **build-image.ps1**: A PowerShell script to build a Docker image of a specified project. |
||||
|
* **create-tls-secrets.ps1**: A PowerShell script to create local TLS secrets for the ingress controller. It's important when you try to [intercept a service](../../studio/kubernetes.md#intercept-a-service) and run it locally. |
||||
|
* **install.ps1**: A PowerShell script to install the solution to a Kubernetes cluster. You can override the default argument values. |
||||
|
* **uninstall.ps1**: A PowerShell script to uninstall the solution from a Kubernetes cluster. You can override the default argument values. |
||||
|
|
||||
|
## Installing the Helm Charts |
||||
|
|
||||
|
You can install the solution to a Kubernetes cluster using the `install.ps1` script. The script has the following arguments: |
||||
|
|
||||
|
* **ChartName**: Default value is the project name. You can create different charts and specify the chart name. In ABP Studio [Kubernetes Main Chart](../../studio/kubernetes.md#main-chart) *Install Chart(s)* command automatically sets the chart name. |
||||
|
* **Namespace**: The namespace to install the Kubernetes resources. Default value is the project name with the `-local` suffix. |
||||
|
* **ReleaseName**: The release name of the Helm chart. Default value is the project name with the `-local` suffix. |
||||
|
* **DotnetEnvironment**: The environment to run the application. Default value is `Staging`. |
||||
|
* **User**: The user responsible for installing the Kubernetes resources. The application will automatically set the user name if you configure it under [Specify the User](../../studio/kubernetes.md#specify-the-user). |
||||
|
|
||||
|
Before running the script, you need to build the Docker images of the solution. You can use the `build-all-images.ps1` script to build all Docker images of the solution. Afterwards, make sure that you have a Kubernetes TLS secret for the ingress controller. It is automatically created when you create the solution; however, if you clone the solution from a repository, you need to create it manually. You can use the `create-tls-secrets.ps1` script to create the TLS secret. Then you can run the `install.ps1` script to install the solution to a Kubernetes cluster. |
||||
|
|
||||
|
## Uninstalling the Helm Charts |
||||
|
|
||||
|
You can uninstall the solution from a Kubernetes cluster using the `uninstall.ps1` script. The script has the following arguments: |
||||
|
|
||||
|
* **Namespace**: The namespace to uninstall the helm chart. Default value is the project name with the `-local` suffix. |
||||
|
* **ReleaseName**: The release name of the Helm chart. Default value is the project name with the `-local` suffix. |
||||
|
* **User**: The user responsible for uninstalling the Kubernetes resources. The application will automatically set the user name if you configure it under [Specify the User](../../studio/kubernetes.md#specify-the-user). |
||||
|
|
||||
|
You can run the `uninstall.ps1` script to uninstall the solution from a Kubernetes cluster. |
||||
|
|
||||
|
```bash |
||||
|
./uninstall.ps1 |
||||
|
``` |
||||
|
|
||||
|
Additionally, in ABP Studio [Kubernetes](../../studio/kubernetes.md) feature, you can do the same operations more easily. You can use the Install Chart(s) and Uninstall Chart(s) commands to install and uninstall the solution to a Kubernetes cluster. Also, use the Build Docker Image(s) command to build the Docker images of the solution. |
||||
|
|
||||
|
 |
||||
|
After Width: | Height: | Size: 58 KiB |
|
After Width: | Height: | Size: 79 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 88 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 59 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 35 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 84 KiB |
|
After Width: | Height: | Size: 96 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
After Width: | Height: | Size: 103 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 95 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 42 KiB |
|
After Width: | Height: | Size: 7.1 KiB |
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 183 KiB |
@ -1,465 +1,35 @@ |
|||||
# Layered Application Solution Template |
# ABP Studio: Layered Solution Template |
||||
|
|
||||
This template provides a layered application structure based on the [Domain Driven Design](../../framework/architecture/domain-driven-design) (DDD) practices. |
````json |
||||
|
//[doc-nav] |
||||
## 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', |
"Next": { |
||||
loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule), |
"Name": "Overview", |
||||
canActivate: [authGuard, permissionGuard], |
"Path": "solution-templates/layered-web-application/overview" |
||||
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. |
ABP Studio provides pre-architected, production-ready templates to jump-start a new solution. One of these templates is the Layered solution template. It is designed for building monolithic layered systems that follow common application patterns based on [Domain-Driven Design](../../framework/architecture/domain-driven-design) (DDD) principles. The template includes multiple layers, integrates existing modules, and provides host applications based on your selections, making it an excellent foundation for your layered system. |
||||
- [The application development tutorial](../../tutorials/book-store/part-01.md) explains step by step application development. |
|
||||
|
|
||||
## See Also |
> **This document explains the Layered solution template in detail. It is a reference document to fully understand the solution and refer to when you have trouble.** |
||||
* [Video tutorial](https://abp.io/video-courses/essentials/app-template) |
> |
||||
|
> **If you want to quickly create a layered solution, please refer to *[Quick Start: Creating a Layered Web Application with ABP Studio](../../get-started/layered-web-application.md)* document.** |
||||
|
|
||||
|
## Contents |
||||
|
|
||||
|
* [Overview](overview.md) |
||||
|
* [Solution structure](solution-structure.md) |
||||
|
* [Main Components](main-components.md) |
||||
|
* [Web Applications](web-applications.md) |
||||
|
* [Db Migrator](db-migrator.md) |
||||
|
* [Mobile Applications](mobile-applications.md) |
||||
|
* [Built-In Features](built-in-features.md) |
||||
|
* [Authentication](authentication.md) |
||||
|
* [Database configurations](database-configurations.md) |
||||
|
* [Logging (with Serilog)](logging.md) |
||||
|
* [Swagger integration](swagger-integration.md) |
||||
|
* [Multi-Tenancy](multi-tenancy.md) |
||||
|
* [BLOB storing](blob-storing.md) |
||||
|
* [CORS configuration](cors-configuration.md) |
||||
|
* [Helm Charts and Kubernetes](helm-charts-and-kubernetes.md) |
||||
|
|||||
@ -0,0 +1,35 @@ |
|||||
|
# Layered Solution: Logging |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Database configurations", |
||||
|
"Path": "solution-templates/layered-web-application/database-configurations" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Swagger integration", |
||||
|
"Path": "solution-templates/layered-web-application/swagger-integration" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
The ABP Studio [layered solution template](index.md) is fully configured for [logging](../../framework/fundamentals/logging.md). All the applications are configured to use the [Serilog](https://serilog.net/) library for structured logging. They are configured in a common way for logging. This document explains that common logging structure. |
||||
|
|
||||
|
## The Serilog Sinks |
||||
|
|
||||
|
The Serilog library is configured so it writes the logs to the following targets (a.k.a. [sinks](https://github.com/serilog/serilog/wiki/Provided-Sinks)) in parallel: |
||||
|
|
||||
|
* **[Console](https://github.com/serilog/serilog-sinks-console)**: Logs are written to the standard output of the executing application. Logging to console is useful when you want to see logs easily while it is running in a container. |
||||
|
* **[File](https://github.com/serilog/serilog-sinks-file)**: Logs are written to a file named `logs.txt` located under the `Logs` folder of the executing application. File logging is useful when you run the application on your local computer. You can check logs easily when you have a trouble. This sinks is only configured for DEBUG mode. It won't be available in your production environment (you can change the behavior in your `Program.cs` file). |
||||
|
* **ABP Studio**: This is a Sink provided by ABP Studio. It sends all logs to ABP Studio, so you can easily monitor your logs in real-time on your ABP Studio Application Monitoring panel. |
||||
|
|
||||
|
The solution can work with [any sink](https://github.com/serilog/serilog/wiki/Provided-Sinks) supported by Serilog. You can add more sinks, remove pre-installed sinks or fine tune their configuration for your solution. |
||||
|
|
||||
|
## Program.cs |
||||
|
|
||||
|
The `Program.cs` file is the main point that configures the logging system. It is done here, because we want to initialize and start the logging in the very beginning of the application. |
||||
|
|
||||
|
## Additional Information |
||||
|
|
||||
|
We are using ABP Serilog Enrichers in the module class of the application. It is done by the `app.UseAbpSerilogEnrichers();` line in the `OnApplicationInitialization` method of your module class. That ASP.NET Core middleware adds current [tenant](../../framework/architecture/multi-tenancy/index.md), [user](../../framework/infrastructure/current-user.md), client and correlation id information to the log records. |
||||
@ -0,0 +1,21 @@ |
|||||
|
# Layered Solution: Main Components |
||||
|
|
||||
|
````json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Solution structure", |
||||
|
"Path": "solution-templates/layered-web-application/solution-structure" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Web Applications", |
||||
|
"Path": "solution-templates/layered-web-application/web-applications" |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
The solution consists of various applications; web applications, mobile applications, and a database migrator application. These applications are the main components of the solution and are designed to work together to provide a complete solution. The following documents explains these components in details: |
||||
|
|
||||
|
* [Web Applications](web-applications.md) |
||||
|
* [Db Migrator](db-migrator.md) |
||||
|
* [Mobile Applications](mobile-applications.md) |
||||
@ -0,0 +1,122 @@ |
|||||
|
# Layered Solution: Mobile Applications |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Db Migrator", |
||||
|
"Path": "solution-templates/layered-web-application/db-migrator" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Built-In Features", |
||||
|
"Path": "solution-templates/layered-web-application/built-in-features" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
> You must have an ABP Team or a higher license to be able to create a mobile application project with ABP Studio. |
||||
|
|
||||
|
Mobile applications are an essential part of modern software solutions. They provide a user-friendly interface to the end-users and allow them to access the system from anywhere. ABP Studio allows you to create mobile applications for your layered solution. You can create a new mobile application project, configure it, and run it on your device. |
||||
|
|
||||
|
## Mobile Application Types |
||||
|
|
||||
|
ABP Studio supports the following mobile application types: |
||||
|
|
||||
|
- **None**: No mobile application project is created. It is the default option. |
||||
|
- **MAUI**: Cross-platform mobile applications with .NET MAUI (Multi-platform App UI). You can create MAUI projects with ABP Studio. |
||||
|
- **React Native**: Cross-platform mobile applications that share code between iOS and Android platforms. You can create React Native projects with ABP Studio. |
||||
|
|
||||
|
You can select the mobile application type when creating a new layered application project during the *Mobile Framework* step. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### The MAUI Application |
||||
|
|
||||
|
This is the mobile application that is built based on Microsoft's [MAUI framework](https://learn.microsoft.com/en-us/dotnet/maui). It will be in the solution only if you've selected the MAUI as your mobile application option. |
||||
|
|
||||
|
#### Project Structure |
||||
|
Entire MAUI application is built on the AppShell pattern of MAUI. You can find the AppShell class in the `Acme.Bookstore.Maui` project. It is the entry point of the application. It is responsible for initializing the application and registering the services. You find all the pages and routing information in the `AppShell.xaml` file. |
||||
|
|
||||
|
- **Pages**: Pages are located in the `Pages` folder of the project. Each page has a XAML & C# file. XAML file is responsible for the UI and C# file is responsible for the initialization of the page. |
||||
|
|
||||
|
- **ViewModels**: ViewModels are located in the `ViewModels` folder of the project. Each ViewModel has a C# file. ViewModels are responsible for the business logic of the pages. |
||||
|
|
||||
|
- **Oidc**: Oidc folder contains the logic for the authentication of the application. It contains the `MauiAuthenticationBrowser` class which manages the authentication process of the application. |
||||
|
|
||||
|
- **Localization**: Localization folder contains the localization logic of the application. It contains regular ABP Localization logic and the `LocalizationResourceManager` class which is wrapper for the ABP localization logic on MAUI. |
||||
|
|
||||
|
- **Messages**: Messages folder contains the message data for the communication inside application. Messages are used to send data between pages and viewmodels. It's designed on the [MVVM Toolkit Messenger](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/messenger) feature. |
||||
|
|
||||
|
- **Storage**: Storage folder contains the storage logic of the application. It contains the `IStorage` class which is wrapper for the [SecureStorage](https://learn.microsoft.com/en-us/dotnet/maui/platform-integration/storage/secure-storage) feature. It is used to store the authentication data of the user and preferences of the application. |
||||
|
|
||||
|
_Rest of the folders are MAUI default folders. You can check the [.NET MAUI single project documentatipon](https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/single-project?view=net-maui-8.0) for more information._ |
||||
|
|
||||
|
#### Running the application |
||||
|
Before running the MAUI Application, rest of the applications in the solution must be running. Such as AuthServer, MobileGateway and the microservices. |
||||
|
|
||||
|
Make sure that you prepared devices for debugging. You can check the following documentation for each platform. |
||||
|
|
||||
|
- [Android](https://learn.microsoft.com/en-us/dotnet/maui/android/emulator/) |
||||
|
- [iOS](https://learn.microsoft.com/en-us/dotnet/maui/ios/pair-to-mac) |
||||
|
- [MacCatalyst](https://learn.microsoft.com/en-us/dotnet/maui/mac-catalyst/cli) |
||||
|
- [Windows](https://learn.microsoft.com/en-us/dotnet/maui/windows/setup) |
||||
|
|
||||
|
##### Network |
||||
|
|
||||
|
All the platforms including iOS, MacCataylst and Windows, runs the applications in the same network of the host. So, you can use the `localhost` address to connect to the applications. |
||||
|
|
||||
|
But in the **Android Emulator**, you need to use the `adb reverse` command to connect to the applications. You can use the following command to connect to the AuthServer application: |
||||
|
|
||||
|
```bash |
||||
|
adb reverse tcp:44300 tcp:44300 |
||||
|
``` |
||||
|
|
||||
|
> `44300` is an example port. You need to change it based on the port of the AuthServer & MobileGateway application. |
||||
|
|
||||
|
> You need to run the command for a running emulator. If you run the emulator after running the command, you need to run the command again. |
||||
|
|
||||
|
|
||||
|
##### Target Framework |
||||
|
|
||||
|
Since MAUI Applications have multiple target frameworks, you need to select the target framework before running the application. You can select the target framework from the context menu of the Solution Runner. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
##### Running with ABP Studio |
||||
|
You can start the MAUI application with the solution runner. You can click the start button of the MAUI application in the solution runner tree. It will start the application on the selected target framework. Since they're not running on a process and they're running on a device, you can't see them as running state in the solution runner. After the application is deployed, it'll be opened on the device and it'll be shown as stopped in the solution runner. |
||||
|
|
||||
|
#### Development on MAUI Application |
||||
|
|
||||
|
You can follow [Mobile Application Development Tutorial - MAUI](../../tutorials/mobile/maui/index.md) to learn how to develop on MAUI Application. |
||||
|
|
||||
|
### The React Native Application |
||||
|
|
||||
|
This is the mobile application that is built based on Facebook's [React Native framework](https://reactnative.dev/) and [Expo](https://expo.dev/). It will be in the solution only if you've selected React Native as your mobile application option. |
||||
|
|
||||
|
#### Project Structure |
||||
|
- **Environment.js**: file using for provide application level variables like `apiUrl`, `oAuthConfig` and etc. |
||||
|
|
||||
|
- **api**: The `api` folder contains HTTP request files that simplify API management in the React Native starter template |
||||
|
- `API.js:` exports **axiosInstance**. It provides axios instance filled api url |
||||
|
|
||||
|
- **components**: In the `components` folder you can reach built in react native components that you can use in your app. These components **facilitates** your list, select and etc. operations |
||||
|
|
||||
|
- **contexts**: `contexts` folder contains [react context](https://react.dev/reference/react/createContext). You can expots your contexts in this folder. `Localization context provided in here` |
||||
|
|
||||
|
- **navigators**: folder contains [react-native stacks](https://reactnavigation.org/docs/stack-navigator/). After create new *FeatureName*Navigator we need to provide in `DrawerNavigator.js` file as `Drawer.Screen` |
||||
|
|
||||
|
- **screens**: is the content of navigated page. We'll pass as component property to [Stack.Screen](https://reactnavigation.org/docs/native-stack-navigator/) |
||||
|
|
||||
|
- **store**: folder manages state-management operations. We will define `actions`, `reducers`, `sagas` and `selectors` here. |
||||
|
|
||||
|
- **styles**: folder contains app styles. `system-style.js` comes built in template we can also add new styles. |
||||
|
|
||||
|
- **utils**: folder contains helper functions that we can use in application |
||||
|
|
||||
|
#### Running the Application |
||||
|
|
||||
|
React Native applications can't be run with the solution runner. You need to run them with the React Native CLI. You can check the [React Native documentation](https://reactnative.dev/docs/environment-setup) to learn how to setup the environment for React Native development. |
||||
|
|
||||
|
Before running the React Native application, rest of the applications in the solution must be running. Such as AuthServer, MobileGateway and the microservices. |
||||
|
|
||||
|
Then you can run the React Native application by following this documentation: [Getting Started with the React Native](../../framework/ui/react-native/index.md). |
||||
@ -0,0 +1,74 @@ |
|||||
|
# Layered Solution: Multi-Tenancy |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Swagger integration", |
||||
|
"Path": "solution-templates/layered-web-application/swagger-integration" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "BLOB storing", |
||||
|
"Path": "solution-templates/layered-web-application/blob-storing" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
||||
|
|
||||
|
Multi-tenancy is a software architecture where a single instance(codebase) of software runs on a server and serves multiple tenants. Tenants are isolated from each other and can have their own data, configurations, and users. This document explains how the multi-tenancy mechanism works in the layered solution template. You can learn more about multi-tenancy in the [Multi-Tenancy](../../framework/architecture/multi-tenancy/index.md), [Tenant Management](../../modules/tenant-management.md) and [SaaS **\***](../../modules/saas.md) documents. |
||||
|
|
||||
|
## Multi-Tenancy in Layered Solutions |
||||
|
|
||||
|
The layered solution templates use the *Multi-Tenancy* architecture only if you *Enable Multi-Tenancy **\**** option while creating the solution. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
You can use different databases for each tenant or a shared database for 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,108 @@ |
|||||
|
# Layered Solution: Overview |
||||
|
|
||||
|
````json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Index", |
||||
|
"Path": "solution-templates/layered-web-application/index" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Solution Structure", |
||||
|
"Path": "solution-templates/layered-web-application/solution-structure" |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
||||
|
|
||||
|
|
||||
|
In this document, you will learn what the Layered solution template offers to you. |
||||
|
|
||||
|
## Pre-Installed Libraries & Services |
||||
|
|
||||
|
The following **libraries and services** come **pre-installed** and **configured** for both **development** and **production** environments. After creating your solution, you can **modify** or **remove** most of them as needed. |
||||
|
|
||||
|
* **[Autofac](https://autofac.org/)** for [Dependency Injection](../../framework/fundamentals/dependency-injection.md). |
||||
|
* **[Serilog](https://serilog.net/)** with File and Console [logging](../../framework/fundamentals/logging.md) providers. |
||||
|
* **[Redis](https://redis.io/)** for [distributed caching](../../framework/fundamentals/caching.md). Redis is used for distributed caching if you select the *Public Website* **\*** or *Tiered* **\*** option. |
||||
|
* **[Swagger](https://swagger.io/)** for exploring and testing HTTP APIs. |
||||
|
* **[OpenIddict](https://github.com/openiddict/openiddict-core)** as the built-in authentication server. |
||||
|
|
||||
|
## Pre-Configured Features |
||||
|
|
||||
|
The following features are built and pre-configured for you in the solution. |
||||
|
|
||||
|
* **Authentication** is fully configured based on best practices. |
||||
|
* **[Permission](../../framework/fundamentals/authorization.md)** (authorization), **[setting](../../framework/infrastructure/settings.md)**, **[feature](../../framework/infrastructure/features.md)** and the **[localization](../../framework/fundamentals/localization.md)** management systems are pre-configured and ready to use. |
||||
|
* **[Background job system](../../framework/infrastructure/background-jobs/index.md)**. |
||||
|
* **[BLOB storge](../../framework/infrastructure/blob-storing/index.md)** system is installed with the [database provider](../../framework/infrastructure/blob-storing/database.md). |
||||
|
* **On-the-fly database migration** system (services automatically migrated their database schema when you deploy a new version). **\*** |
||||
|
* **[Helm](https://helm.sh/)** charts are included to deploy the solution to **[Kubernetes](https://kubernetes.io/)**. **\*** |
||||
|
* **[Swagger](https://swagger.io/)** authentication is configured to test the authorized HTTP APIs. |
||||
|
|
||||
|
## Fundamental Modules |
||||
|
|
||||
|
The following modules are pre-installed and configured for the solution: |
||||
|
|
||||
|
* **[Account](../../modules/account.md)** to authenticate users (login, register, two factor auth **\***, etc) |
||||
|
* **[Identity](../../modules/identity.md)** to manage roles and users |
||||
|
* **[OpenIddict](../../modules/openiddict.md)** (the core part) to implement the OAuth authentication flows |
||||
|
|
||||
|
In addition these, [Feature Management](../../modules/feature-management.md), [Permission Management](../../modules/permission-management.md) and [Setting Management](../../modules/setting-management.md) modules are pre-installed as they are the fundamental feature modules of the ABP. |
||||
|
|
||||
|
## Optional Modules |
||||
|
|
||||
|
The following modules are optionally included in the solution, so you can select the ones you need: |
||||
|
|
||||
|
* **[Audit Logging](../../modules/audit-logging.md)** |
||||
|
* **[Chat](../../modules/chat.md)** **\*** |
||||
|
* **[File Management](../../modules/file-management.md)** **\*** |
||||
|
* **[GDPR](../../modules/gdpr.md)** **\*** |
||||
|
* **[Language Management](../../modules/language-management.md)** **\*** |
||||
|
* **[OpenIddict (Management UI)](../../modules/openiddict.md)** **\*** |
||||
|
* **[Tenant Management](../../modules/tenant-management.md) (Multi-Tenancy) or [SaaS](../../modules/saas.md)** **\*** |
||||
|
* **[Text Template Management](../../modules/text-template-management.md)** **\*** |
||||
|
|
||||
|
## UI Theme |
||||
|
|
||||
|
The **[LeptonX Lite](../../ui-themes/lepton-x-lite/index.md) or [LeptonX theme](https://leptontheme.com/)** **\*** is pre-configured for the solution. You can select one of the color palettes (System, Light or Dark) as default, while the end-user dynamically change it on the fly. |
||||
|
|
||||
|
## Other Options |
||||
|
|
||||
|
Layered startup template asks for some preferences while creating your solution. |
||||
|
|
||||
|
### Database Providers |
||||
|
|
||||
|
There are two database provider options are provided on a new solution creation: |
||||
|
|
||||
|
* **[Entity Framework Core](../../framework/data/entity-framework-core/index.md)** with SQL Server, MySQL and PostgreSQL DBMS options. You can [switch to anther DBMS](../../framework/data/entity-framework-core/other-dbms.md) manually after creating your solution. |
||||
|
* **[MongoDB](../../framework/data/mongodb/index.md)** |
||||
|
|
||||
|
### UI Frameworks |
||||
|
|
||||
|
The solution comes with a main web application with the following UI Framework options: |
||||
|
|
||||
|
* **None** (doesn't include a web application to the solution) |
||||
|
* **Angular** |
||||
|
* **MVC / Razor Pages UI** |
||||
|
* **Blazor WebAssembly** |
||||
|
* **Blazor Server** |
||||
|
* **Blazor WebApp** |
||||
|
* **MAUI with Blazor (Hybrid)** **\*** |
||||
|
|
||||
|
### The Mobile Application |
||||
|
|
||||
|
If you prefer, the solution includes a mobile application. The mobile application is fully integrated to the system, implements authentication (login) and other ABP features, and includes a few screens that you can use and take as example. The following options are available: |
||||
|
|
||||
|
* **None** (doesn't include a mobile application to the solution) |
||||
|
* **MAUI** **\*** |
||||
|
* **React Native** **\*** |
||||
|
|
||||
|
### Multi-Tenancy & SaaS Module **\*** |
||||
|
|
||||
|
The **[SaaS module](../../modules/saas.md)** is included as an option. When you select it, the **[multi-tenancy](../../framework/architecture/multi-tenancy/index.md)** system is automatically configured. Otherwise, the system will not include any multi-tenancy overhead. |
||||
|
|
||||
|
## See Also |
||||
|
|
||||
|
* [Quick Start: Creating a Layered Web Application with ABP Studio](../../get-started/layered-web-application.md) |
||||
@ -0,0 +1,216 @@ |
|||||
|
# Layered Solution: The Structure |
||||
|
|
||||
|
````json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Overview", |
||||
|
"Path": "solution-templates/layered-web-application/overview" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Main Components", |
||||
|
"Path": "solution-templates/layered-web-application/main-components" |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
||||
|
|
||||
|
This document explains the solution and folder structure of ABP Studio's [layered solution template](index.md). |
||||
|
|
||||
|
> This document assumes that you've created a new layered solution by following the *[Quick Start: Creating a Layered Web Application with ABP Studio](../../get-started/layered-web-application.md)* guide. (Choose the *Entity Framework Core* as the database provider.) |
||||
|
|
||||
|
## Understanding the ABP Solution Structure |
||||
|
|
||||
|
When you create a new layered solution, you will see a tree structure similar to the one below in the *Solution Explorer* panel: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
`Acme.Bookstore` is the main **ABP Studio module** of the solution. It includes two folders: `src` and `test`, as shown in the image above. The `src` folder contains the source code of the solution, which is structured according to [DDD](../../framework/architecture/domain-driven-design/index.md) principles, while the `test` folder holds the unit and integration tests. |
||||
|
|
||||
|
> Refer to the *[Concepts](../../studio/concepts.md)* document for a comprehensive definition of ABP Studio solution, module, and package terms. |
||||
|
|
||||
|
## Exploring the Folder Structure |
||||
|
|
||||
|
You can right-click the root item in the solution explorer (`Acme.Bookstore` for this example) and select the *Open with* -> *Explorer* command to open the folder containing the solution in your file system: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
The root folder of the solution will be similar to the following: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
* `.abpstudio` folder stores your personal preferences for this solution and is excluded from source control (Git ignored). It is created and used by ABP Studio. |
||||
|
* `etc` folder contains additional files for the solution, organized into the following sub-folders: |
||||
|
* `abp-studio` folder holds settings managed by ABP Studio. This folder is included in source control and shared among developers. |
||||
|
* `docker` folder provides docker-compose configurations to easily run infrastructure dependencies (e.g., RabbitMQ, Redis) for the solution on your local machine. |
||||
|
* `helm` folder contains Helm charts and related scripts for deploying the solution to Kubernetes. **\*** |
||||
|
* `src` folder contains the solution's source code, structured according to [DDD](../../framework/architecture/domain-driven-design/index.md) principles. It also includes database migrations and, depending on your project creation options, may include mobile and web application projects. |
||||
|
* `test` folder contains unit and integration tests for the solution. |
||||
|
|
||||
|
## Understanding the Layered Solution Structure |
||||
|
|
||||
|
The diagram below illustrates the application's layers and project dependencies: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### .Domain.Shared Project |
||||
|
|
||||
|
This project contains constants, enums and other objects these are actually a part of the domain layer, but needed to be used by all layers/projects in the solution. |
||||
|
|
||||
|
A `BookType` enum and a `BookConsts` class (which may have some constant fields for the `Book` entity, like `MaxNameLength`) are good candidates for this project. |
||||
|
|
||||
|
* This project has no dependency on other projects in the solution. All other projects depend on this one directly or indirectly. |
||||
|
|
||||
|
### .Domain Project |
||||
|
|
||||
|
This is the domain layer of the solution. It mainly contains [entities, aggregate roots](../../framework/architecture/domain-driven-design/entities.md), [domain services](../../framework/architecture/domain-driven-design/domain-services.md), [value objects](../../framework/architecture/domain-driven-design/value-objects.md), [repository interfaces](../../framework/architecture/domain-driven-design/repositories.md) and other domain objects. |
||||
|
|
||||
|
A `Book` entity, a `BookManager` domain service and an `IBookRepository` interface are good candidates for this project. |
||||
|
|
||||
|
* Depends on the `.Domain.Shared` because it uses constants, enums and other objects defined in that project. |
||||
|
|
||||
|
### .Application.Contracts Project |
||||
|
|
||||
|
This project mainly contains [application service](../../framework/architecture/domain-driven-design/application-services.md) **interfaces** and [Data Transfer Objects](../../framework/architecture/domain-driven-design/data-transfer-objects.md) (DTO) of the application layer. It exists to separate the interface & implementation of the application layer. In this way, the interface project can be shared to the clients as a contract package. |
||||
|
|
||||
|
An `IBookAppService` interface and a `BookCreationDto` class are good candidates for this project. |
||||
|
|
||||
|
* Depends on the `.Domain.Shared` because it may use constants, enums and other shared objects of this project in the application service interfaces and DTOs. |
||||
|
|
||||
|
### .Application Project |
||||
|
|
||||
|
This project contains the [application service](../../framework/architecture/domain-driven-design/application-services.md) **implementations** of the interfaces defined in the `.Application.Contracts` project. |
||||
|
|
||||
|
A `BookAppService` class is a good candidate for this project. |
||||
|
|
||||
|
* Depends on the `.Application.Contracts` project to be able to implement the interfaces and use the DTOs. |
||||
|
* Depends on the `.Domain` project to be able to use domain objects (entities, repository interfaces... etc.) to perform the application logic. |
||||
|
|
||||
|
### .EntityFrameworkCore Project |
||||
|
|
||||
|
This is the integration project for the EF Core. It defines the `DbContext` and implements repository interfaces defined in the `.Domain` project. |
||||
|
|
||||
|
* Depends on the `.Domain` project to be able to reference to entities and repository interfaces. |
||||
|
|
||||
|
> This project is available only if you are using EF Core as the database provider. If you select another database provider, its name will be different. |
||||
|
|
||||
|
### .DbMigrator Project |
||||
|
|
||||
|
This is a console application that simplifies the execution of database migrations on development and production environments. When you run this application, it: |
||||
|
|
||||
|
* Creates the database if necessary. |
||||
|
* Applies the pending database migrations. |
||||
|
* Seeds initial data if needed. |
||||
|
|
||||
|
> This project has its own `appsettings.json` file. So, if you want to change the database connection string, remember to change this file too. |
||||
|
|
||||
|
Especially, seeding initial data is important at this point. ABP has a modular data seed infrastructure. See [its documentation](../../framework/infrastructure/data-seeding.md) for more about the data seeding. |
||||
|
|
||||
|
While creating database & applying migrations seem only necessary for relational databases, this project comes even if you choose a NoSQL database provider (like MongoDB). In that case, it still seeds the initial data which is necessary for the application. |
||||
|
|
||||
|
* Depends on the `.EntityFrameworkCore` project (for EF Core) since it needs to access to the migrations. |
||||
|
* Depends on the `.Application.Contracts` project to be able to access permission definitions, because the initial data seeder grants all permissions to the admin role by default. |
||||
|
|
||||
|
### .HttpApi Project |
||||
|
|
||||
|
This project is used to define your API Controllers. |
||||
|
|
||||
|
Most of the time you don't need to manually define API Controllers since ABP's [Auto API Controllers](../../framework/api-development/auto-controllers.md) feature creates them automagically based on your application layer. However, in case of you need to write API controllers, this is the best place to do it. |
||||
|
|
||||
|
* Depends on the `.Application.Contracts` project to be able to inject the application service interfaces. |
||||
|
|
||||
|
### .HttpApi.Client Project |
||||
|
|
||||
|
This is a project that defines C# client proxies to use the HTTP APIs of the solution. You can share this library to 3rd-party clients, so they can easily consume your HTTP APIs in their Dotnet applications (For other types of applications, they can still use your APIs, either manually or using a tool in their own platform) |
||||
|
|
||||
|
Most of the time you don't need to manually create C# client proxies, thanks to ABP's [Dynamic C# API Clients](../../framework/api-development/dynamic-csharp-clients.md) feature. |
||||
|
|
||||
|
`.HttpApi.Client.ConsoleTestApp` project is a console application created to demonstrate the usage of the client proxies. |
||||
|
|
||||
|
* Depends on the `.Application.Contracts` project to be able to share the same application service interfaces and DTOs with the remote service. |
||||
|
|
||||
|
> You can delete this project & dependencies if you don't need to create C# client proxies for your APIs. |
||||
|
|
||||
|
### .Web Project |
||||
|
|
||||
|
This project contains the User Interface (UI) of the application if you are using ASP.NET Core MVC UI. It contains Razor pages, JavaScript files, CSS files, images and so on... |
||||
|
|
||||
|
This project contains the main `appsettings.json` file that contains the connection string and other configurations of the application. |
||||
|
|
||||
|
* Depends on the `.HttpApi` project since the UI layer needs to use APIs and the application service interfaces of the solution. |
||||
|
|
||||
|
> If you check the source code of the `.Web.csproj` file, you will see the references to the `.Application` and the `.EntityFrameworkCore` projects. |
||||
|
> |
||||
|
> These references are actually not needed while coding your UI layer, because the UI layer normally doesn't depend on the EF Core or the Application layer's implementation. These startup templates are ready for tiered deployment, where the API layer is hosted on a separate server than the UI layer. |
||||
|
> |
||||
|
> However, if you don't choose the `--tiered` option, these references will be in the .Web project to be able to host the Web, API and application layers in a single application endpoint. |
||||
|
> |
||||
|
> This gives you the ability to use domain entities & repositories in your presentation layer. However, this is considered as a bad practice according to DDD. |
||||
|
|
||||
|
### Test Projects |
||||
|
|
||||
|
The solution has multiple test projects, one for each layer: |
||||
|
|
||||
|
* `.Domain.Tests` is used to test the domain layer. |
||||
|
* `.Application.Tests` is used to test the application layer. |
||||
|
* `.EntityFrameworkCore.Tests` is used to test EF Core configuration and custom repositories. |
||||
|
* `.Web.Tests` is used to test the UI (if you are using ASP.NET Core MVC UI). |
||||
|
* `.TestBase` is a base (shared) project for all tests. |
||||
|
|
||||
|
In addition, `.HttpApi.Client.ConsoleTestApp` is a console application (not an automated test project) which demonstrate the usage of HTTP APIs from a .NET application. |
||||
|
|
||||
|
Test projects are prepared for integration testing; |
||||
|
|
||||
|
* It is fully integrated into the ABP and all services in your application. |
||||
|
* It uses SQLite in-memory database for EF Core. For MongoDB, it uses the [EphemeralMongo](https://github.com/asimmon/ephemeral-mongo) library. |
||||
|
* Authorization is disabled, so any application service can be easily used in tests. |
||||
|
|
||||
|
You can still create unit tests for your classes which will be harder to write (because you will need to prepare mock/fake objects), but faster to run (because it only tests a single class and skips all the initialization processes). |
||||
|
|
||||
|
### How to Run? |
||||
|
|
||||
|
You can open the [Solution Runner](../../studio/running-applications.md) panel and start the all applications. The default username is `admin` and the password is `1q2w3E*`. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
See [Getting Started With the ASP.NET Core MVC Template](../../get-started/layered-web-application.md) for more information. |
||||
|
|
||||
|
## Tiered Structure **\*** |
||||
|
|
||||
|
If you have selected the ASP.NET Core UI and specified the `--tiered` option, the solution created will be a tiered solution. The purpose of the tiered structure is to be able to **deploy Web applications and HTTP API to different servers**: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
* Browser runs your UI by executing HTML, CSS & JavaScript. |
||||
|
* Web servers host static UI files (CSS, JavaScript, image... etc.) & dynamic components (e.g. Razor pages). It performs HTTP requests to the API server to execute the business logic of the application. |
||||
|
* The API Server hosts the HTTP APIs which then use the application & domain layers of the application to perform the business logic. |
||||
|
* Finally, database server hosts your database. |
||||
|
|
||||
|
> Unless you actually need such a 4-tiered deployment, it's suggested to go with the default structure which is simpler to develop, deploy and maintain. |
||||
|
|
||||
|
The solution structure is shown below: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
As different from the default structure, two new projects come into play: `.AuthServer` & `.HttpApi.Host`. |
||||
|
|
||||
|
### .AuthServer Project |
||||
|
|
||||
|
This project is used as an authentication server for other projects. `.Web` project uses OpenId Connect Authentication to get identity and access tokens for the current user from the AuthServer. Then uses the access token to call the HTTP API server. HTTP API server uses bearer token authentication to obtain claims from the access token to authorize the current user. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
ABP uses the [OpenIddict Module](../../modules/openiddict.md) that uses the open-source [OpenIddict-core](https://github.com/openiddict/openiddict-core) library for the authentication between applications. See [OpenIddict documentation](https://documentation.openiddict.com/) for details about the OpenIddict and OpenID Connect protocol. |
||||
|
|
||||
|
It has its own `appsettings.json` that contains database connection and other configurations. |
||||
|
|
||||
|
### .HttpApi.Host Project |
||||
|
|
||||
|
This project is an application that hosts the API of the solution. It has its own `appsettings.json` that contains database connection and other configurations. |
||||
|
|
||||
|
### .Web Project |
||||
|
|
||||
|
Just like the default structure, this project contains the User Interface (UI) of the application. It contains razor pages, JavaScript files, style files, images and so on... |
||||
|
|
||||
|
This project contains an `appsettings.json` file, but this time it does not have a connection string because it never connects to the database. Instead, it mainly contains the endpoint of the remote API server and the authentication server. |
||||
@ -0,0 +1,19 @@ |
|||||
|
# Layered Solution: Swagger Integration |
||||
|
|
||||
|
```json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Logging (with Serilog)", |
||||
|
"Path": "solution-templates/layered-web-application/logging" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Multi-Tenancy", |
||||
|
"Path": "solution-templates/layered-web-application/multi-tenancy" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
[Swagger](https://swagger.io/) is a tool that helps to create, document, and consume RESTful web services. It provides a user interface to interact with the APIs and also a way to generate client SDKs for the APIs. |
||||
|
|
||||
|
In the [Swagger Integration](../../framework/api-development/swagger.md) document, you can find general information about Swagger integration with ABP Framework. |
||||
@ -0,0 +1,178 @@ |
|||||
|
# Layered Solution: Web Applications |
||||
|
|
||||
|
````json |
||||
|
//[doc-nav] |
||||
|
{ |
||||
|
"Previous": { |
||||
|
"Name": "Main Components", |
||||
|
"Path": "solution-templates/layered-web-application/main-components" |
||||
|
}, |
||||
|
"Next": { |
||||
|
"Name": "Db Migrator", |
||||
|
"Path": "solution-templates/layered-web-application/db-migrator" |
||||
|
} |
||||
|
} |
||||
|
```` |
||||
|
|
||||
|
> Some of the features mentioned in this document may not be available in the free version. We're using the **\*** symbol to indicate that a feature is available in the **[Team](https://abp.io/pricing)** and **[Higher](https://abp.io/pricing)** licenses. |
||||
|
|
||||
|
The web applications are the main user interfaces of the solution. They are the entry points for users to interact with the system. The Layered Solution Template supports the following web applications: |
||||
|
|
||||
|
- **MVC / Razor Pages**: This is an ASP.NET Core MVC application. It is a traditional web application that serves HTML pages to users and is suitable for building web applications with server-side rendering. |
||||
|
- **Angular**: This is an Angular application, a single-page application (SPA) that runs on the client side. It communicates with the server using HTTP requests and is ideal for building modern web applications with rich user interfaces. |
||||
|
- **Blazor UI**: A flexible framework for building web applications with .NET. It supports various hosting models: |
||||
|
- **Blazor WebAssembly**: This is a client-side SPA that runs entirely in the user's browser. It communicates with the server using HTTP requests and is suitable for modern web applications with rich interactivity and offline capabilities. |
||||
|
- **Blazor Server**: This is a server-side SPA that runs on the server and communicates with the client in real time using SignalR. It is ideal for applications requiring constant connectivity and rapid server updates. |
||||
|
- **Blazor WebApp**: This is a combination of Blazor technologies optimized for building hybrid web applications that can leverage both client-side and server-side capabilities. |
||||
|
- **Maui Blazor (Hybrid)** **\***: This enables building cross-platform applications that combine Blazor for the UI with .NET MAUI for native device integration. It is suitable for building apps that work across desktop and mobile platforms. |
||||
|
- **No UI**: This option creates a backend-only solution without a web interface, suitable for scenarios like API-only applications or headless services. |
||||
|
|
||||
|
You can select the web application type that fits your requirements during the solution creation process in the *UI Framework* step. The Layered Solution Template generates the selected web applications with the necessary configurations and integrations. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
## MVC / Razor Pages |
||||
|
|
||||
|
MVC (Model-View-Controller) is a design pattern commonly used for building web applications. Razor Pages, on the other hand, is a page-based programming model designed to make building web applications simpler and more productive. |
||||
|
|
||||
|
When you select the MVC / Razor Pages option in the Layered Solution Template, it generates an ASP.NET Core MVC application named something like `Acme.BookStore.Web`. This application serves as the web interface for your solution, using server-side rendering to deliver dynamic HTML pages to users. |
||||
|
|
||||
|
## Angular |
||||
|
|
||||
|
Angular is a popular front-end framework for building single-page applications (SPAs). It offers a rich set of features for creating modern web applications with dynamic and interactive user interfaces. |
||||
|
|
||||
|
When you select the Angular option in the Layered Solution Template, it generates: |
||||
|
- An Angular application located under the solution's root folder, typically named `angular`. |
||||
|
- An ASP.NET Core application, usually named something like `Acme.Bookstore.HttpApi.Host`. |
||||
|
|
||||
|
The Angular application runs as a client-side SPA in the user's browser and communicates with the server by sending HTTP requests to the `*.HttpApi.Host` application. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
Each of ABP modules is an NPM package. Some ABP modules are added as a dependency in `package.json`. These modules install with their dependencies. To see all ABP packages, you can run the following command in the `angular` folder: |
||||
|
|
||||
|
```bash |
||||
|
yarn list --pattern abp |
||||
|
``` |
||||
|
|
||||
|
Angular application module structure: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### AppModule |
||||
|
|
||||
|
`AppModule` is the root module of the application. Some of the ABP modules and some essential modules are imported to `AppModule`. |
||||
|
|
||||
|
ABP Config modules have also been imported to `AppModule` for initial requirements of the lazy-loadable ABP modules. |
||||
|
|
||||
|
### AppRoutingModule |
||||
|
|
||||
|
There are lazy-loadable ABP modules in the `AppRoutingModule` as routes. |
||||
|
|
||||
|
> Paths of ABP Modules should not be changed. |
||||
|
|
||||
|
You should add `routes` property in the `data` object to add a link on the menu to redirect to your custom pages. |
||||
|
|
||||
|
```js |
||||
|
{ |
||||
|
path: 'dashboard', |
||||
|
loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule), |
||||
|
canActivate: [authGuard, permissionGuard], |
||||
|
data: { |
||||
|
routes: { |
||||
|
name: 'ProjectName::Menu:Dashboard', |
||||
|
order: 2, |
||||
|
iconClass: 'fa fa-dashboard', |
||||
|
requiredPolicy: 'ProjectName.Dashboard.Host' |
||||
|
} as ABP.Route |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
In the above example; |
||||
|
* If the user is not logged in, authGuard blocks access and redirects to the login page. |
||||
|
* permissionGuard checks the user's permission with the `requiredPolicy` property of the `routes` object. If the user is not authorized to access the page, the 403 page appears. |
||||
|
* The `name` property of `routes` is the menu link label. A localization key can be defined. |
||||
|
* The `iconClass` property of the `routes` object is the menu link icon class. |
||||
|
* The `requiredPolicy` property of the `routes` object is the required policy key to access the page. |
||||
|
|
||||
|
After the above `routes` definition, if the user is authorized, the dashboard link will appear on the menu. |
||||
|
|
||||
|
### Shared Module |
||||
|
|
||||
|
The modules that may be required for all modules have been imported to the `SharedModule`. You should import `SharedModule` to all modules. |
||||
|
|
||||
|
See the [Sharing Modules](https://angular.io/guide/sharing-ngmodules) document. |
||||
|
|
||||
|
### Environments |
||||
|
|
||||
|
The files under the `src/environments` folder have the essential configuration of the application. |
||||
|
|
||||
|
### Home Module |
||||
|
|
||||
|
Home module is an example lazy-loadable module that loads on the root address of the application. |
||||
|
|
||||
|
### Styles |
||||
|
|
||||
|
The required style files are added to the `styles` array in `angular.json`. `AppComponent` loads some style files lazily via `LazyLoadService` after the main bundle is loaded to shorten the first rendering time. |
||||
|
|
||||
|
### Testing |
||||
|
|
||||
|
You should create your tests in the same folder as the file you want to test. |
||||
|
|
||||
|
See the [testing document](https://angular.io/guide/testing). |
||||
|
|
||||
|
### Depended Packages |
||||
|
|
||||
|
* [NG Bootstrap](https://ng-bootstrap.github.io/) is used as UI component library. |
||||
|
* [NGXS](https://www.ngxs.io/) is used as state management library. |
||||
|
* [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc) is used to support for OAuth 2 and OpenId Connect (OIDC). |
||||
|
* [Chart.js](https://www.chartjs.org/) is used to create widgets. |
||||
|
* [ngx-validate](https://github.com/ng-turkey/ngx-validate) is used for dynamic validation of reactive forms. |
||||
|
|
||||
|
## Blazor UI |
||||
|
|
||||
|
Blazor is a flexible framework for building web applications with .NET. It supports various hosting models, including Blazor WebAssembly, Blazor Server, Blazor WebApp, and Maui Blazor (Hybrid). |
||||
|
|
||||
|
### Blazor WebAssembly |
||||
|
|
||||
|
Blazor WebAssembly is a client-side SPA that runs entirely in the user's browser. It communicates with the server using HTTP requests and is suitable for modern web applications with rich interactivity and offline capabilities. |
||||
|
|
||||
|
When you select the Blazor WebAssembly option in the Layered Solution Template, it generates: |
||||
|
- A Blazor application located under the solution's root folder, typically named `*.Blazor`, which serves as the main Blazor host project. |
||||
|
- A Blazor client application, named `*.Blazor.Client`, where you can write the client-side (UI logic) code. |
||||
|
- An ASP.NET Core application, named `*.HttpApi.Host`, where the server-side (business logic) code runs. |
||||
|
|
||||
|
The Blazor client application communicates with the server by sending HTTP requests to the `*.HttpApi.Host` application. |
||||
|
|
||||
|
### Blazor Server |
||||
|
|
||||
|
Blazor Server is a server-side SPA that runs on the server and communicates with the client in real time using SignalR. It is ideal for applications requiring constant connectivity and rapid server updates. |
||||
|
|
||||
|
When you select the Blazor Server option in the Layered Solution Template, it generates: |
||||
|
- A Blazor application located under the solution's root folder, typically named `*.Blazor`, which serves as the main Blazor host project. |
||||
|
|
||||
|
### Blazor WebApp |
||||
|
|
||||
|
Blazor WebApp is a combination of Blazor technologies optimized for building hybrid web applications that can leverage both client-side and server-side capabilities. |
||||
|
|
||||
|
When you select the Blazor WebApp option in the Layered Solution Template, it generates: |
||||
|
- A Blazor application located under the solution's root folder, typically named `*.Blazor`, which serves as the main Blazor host project. |
||||
|
- A Blazor client application, named `*.Blazor.Client`, where you can write the client-side (UI logic) code. |
||||
|
|
||||
|
The Blazor client application communicates with the server by sending HTTP requests to the `*.Blazor` application. |
||||
|
|
||||
|
### Maui Blazor (Hybrid) **\*** |
||||
|
|
||||
|
Maui Blazor (Hybrid) enables building cross-platform applications that combine Blazor for the UI with .NET MAUI for native device integration. It is suitable for building apps that work across desktop and mobile platforms. |
||||
|
|
||||
|
When you select the Maui Blazor (Hybrid) option in the Layered Solution Template, it generates: |
||||
|
- A Maui Blazor (Hybrid) application located under the solution's root folder, typically named `*.MauiBlazor`, which serves as the main UI host project. |
||||
|
- An ASP.NET Core application, named `*.HttpApi.Host`, where the server-side (business logic) code runs. |
||||
|
|
||||
|
The Maui Blazor (Hybrid) application communicates with the server by sending HTTP requests to the `*.HttpApi.Host` application. |
||||
|
|
||||
|
## No UI |
||||
|
|
||||
|
This option creates a backend-only solution without a web interface, suitable for scenarios like API-only applications or headless services. |
||||
|
|
||||
|
When you select the No UI option in the Layered Solution Template, it generates an ASP.NET Core application named `*.HttpApi.Host` that serves as the backend API for your solution. |
||||
@ -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 |
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue