mirror of https://github.com/abpframework/abp.git
Fahri Gedik
10 months ago
428 changed files with 13724 additions and 3216 deletions
@ -0,0 +1,89 @@ |
|||
# ABP.IO Platform 10.0 Final Has Been Released! |
|||
|
|||
We are glad to announce that [ABP](https://abp.io/) 10.0 stable version has been released today. |
|||
|
|||
## What's New With Version 10.0? |
|||
|
|||
All the new features were explained in detail in the [10.0 RC Announcement Post](https://abp.io/community/announcements/announcing-abp-10-0-release-candidate-86lrnyox), so there is no need to review them again. You can check it out for more details. |
|||
|
|||
## Getting Started with 10.0 |
|||
|
|||
### How to Upgrade an Existing Solution |
|||
|
|||
You can upgrade your existing solutions with either ABP Studio or ABP CLI. In the following sections, both approaches are explained: |
|||
|
|||
### Upgrading via ABP Studio |
|||
|
|||
If you are already using the ABP Studio, you can upgrade it to the latest version. ABP Studio periodically checks for updates in the background, and when a new version of ABP Studio is available, you will be notified through a modal. Then, you can update it by confirming the opened modal. See [the documentation](https://abp.io/docs/latest/studio/installation#upgrading) for more info. |
|||
|
|||
After upgrading the ABP Studio, then you can open your solution in the application, and simply click the **Upgrade ABP Packages** action button to instantly upgrade your solution: |
|||
|
|||
 |
|||
|
|||
### Upgrading via ABP CLI |
|||
|
|||
Alternatively, you can upgrade your existing solution via ABP CLI. First, you need to install the ABP CLI or upgrade it to the latest version. |
|||
|
|||
If you haven't installed it yet, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
Or to update the existing CLI, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool update -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
After installing/updating the ABP CLI, you can use the [`update` command](https://abp.io/docs/latest/CLI#update) to update all the ABP related NuGet and NPM packages in your solution as follows: |
|||
|
|||
```bash |
|||
abp update |
|||
``` |
|||
|
|||
You can run this command in the root folder of your solution to update all ABP related packages. |
|||
|
|||
## Migration Guides |
|||
|
|||
There are a few breaking changes in this version that may affect your application. Please read the migration guide carefully, if you are upgrading from v9.x: [ABP Version 10.0 Migration Guide](https://abp.io/docs/10.0/release-info/migration-guides/abp-10-0) |
|||
|
|||
## Community News |
|||
|
|||
### New ABP Community Articles |
|||
|
|||
As always, exciting articles have been contributed by the ABP community. I will highlight some of them here: |
|||
|
|||
* [Alper Ebiçoğlu](https://abp.io/community/members/alper) |
|||
* [Optimize your .NET app for production Part 1](https://abp.io/community/articles/optimize-your-dotnet-app-for-production-for-any-.net-app-wa24j28e) |
|||
* [Optimize your .NET app for production Part 2](https://abp.io/community/articles/optimize-your-dotnet-app-for-production-for-any-.net-app-2-78xgncpi) |
|||
* [Return Code vs Exceptions: Which One is Better?](https://abp.io/community/articles/return-code-vs-exceptions-which-one-is-better-1rwcu9yi) |
|||
* [Sumeyye Kurtulus](https://abp.io/community/members/sumeyye.kurtulus) |
|||
* [Building Scalable Angular Apps with Reusable UI Components](https://abp.io/community/articles/building-scalable-angular-apps-with-reusable-ui-components-b9npiff3) |
|||
* [Angular Library Linking Made Easy: Paths, Workspaces and Symlinks](https://abp.io/community/articles/angular-library-linking-made-easy-paths-workspaces-and-5z2ate6e) |
|||
* [erdem çaygör](https://abp.io/community/members/erdem.caygor) |
|||
* [Building Dynamic Forms in Angular for Enterprise](https://abp.io/community/articles/building-dynamic-forms-in-angular-for-enterprise-6r3ewpxt) |
|||
* [From Server to Browser: Angular TransferState Explained](https://abp.io/community/articles/from-server-to-browser-angular-transferstate-explained-m99zf8oh) |
|||
* [Mansur Besleney](https://abp.io/community/members/mansur.besleney) |
|||
* [Top 10 Exception Handling Mistakes in .NET](https://abp.io/community/articles/top-10-exception-handling-mistakes-in-net-jhm8wzvg) |
|||
* [Berkan Şaşmaz](https://abp.io/community/members/berkansasmaz) |
|||
* [How to Dynamically Set the Connection String in EF Core](https://abp.io/community/articles/how-to-dynamically-set-the-connection-string-in-ef-core-30k87fpj) |
|||
* [Oğuzhan Ağır](https://abp.io/community/members/oguzhan.agir) |
|||
* [The ASP.NET Core Dependency Injection System](https://abp.io/community/articles/the-asp.net-core-dependency-injection-system-3vbsdhq8) |
|||
* [Selman Koç](https://abp.io/community/members/selmankoc) |
|||
* [5 Things Keep in Mind When Deploying Clustered Environment](https://abp.io/community/articles/5-things-keep-in-mind-when-deploying-clustered-environment-i9byusnv) |
|||
* [Muhammet Ali ÖZKAYA](https://abp.io/community/members/m.aliozkaya) |
|||
* [Repository Pattern in ASP.NET Core](https://abp.io/community/articles/repository-pattern-in-asp.net-core-2dudlg3j) |
|||
* [Armağan Ünlü](https://abp.io/community/members/armagan) |
|||
* [UI/UX Trends That Will Shape 2026](https://abp.io/community/articles/UI-UX-Trends-That-Will-Shape-2026-bx4c2kow) |
|||
* [Salih](https://abp.io/community/members/salih) |
|||
* [What is That Domain Service in DDD for .NET Developers?](https://abp.io/community/articles/what-is-that-domain-service-in-ddd-for-.net-developers-uqnpwjja) |
|||
* [Building an API Key Management System with ABP Framework](https://abp.io/community/articles/building-an-api-key-management-system-with-abp-framework-28gn4efw) |
|||
* [Fahri Gedik](https://abp.io/community/members/fahrigedik) |
|||
* [Signal-Based Forms in Angular](https://abp.io/community/articles/signal-based-forms-in-angular-21-9qentsqs) |
|||
|
|||
Thanks to the ABP Community for all the content they have published. You can also [post your ABP related (text or video) content](https://abp.io/community/posts/create) to the ABP Community. |
|||
|
|||
## About the Next Version |
|||
|
|||
The next feature version will be 10.1. You can follow the [release planning here](https://github.com/abpframework/abp/milestones). Please [submit an issue](https://github.com/abpframework/abp/issues/new) if you have any problems with this version. |
|||
|
After Width: | Height: | Size: 127 KiB |
|
After Width: | Height: | Size: 16 KiB |
@ -0,0 +1,277 @@ |
|||
# Repository Pattern in the ASP.NET Core |
|||
|
|||
If you’ve built a .NET app with a database, you’ve likely used Entity Framework, Dapper, or ADO.NET. They’re useful tools; still, when they live inside your business logic or controllers, the code can become harder to keep tidy and to test. |
|||
|
|||
That’s where the **Repository Pattern** comes in. |
|||
|
|||
At its core, the Repository Pattern acts as a **middle layer between your domain and data access logic**. It abstracts the way you store and retrieve data, giving your application a clean separation of concerns: |
|||
|
|||
* **Separation of Concerns:** Business logic doesn’t depend on the database. |
|||
* **Easier Testing:** You can replace the repository with a fake or mock during unit tests. |
|||
* **Flexibility:** You can switch data sources (e.g., from SQL to MongoDB) without touching business logic. |
|||
|
|||
Let’s see how this works with a simple example. |
|||
|
|||
## A Simple Example with Product Repository |
|||
|
|||
Imagine we’re building a small e-commerce app. We’ll start by defining a repository interface for managing products. |
|||
|
|||
You can find the complete sample code in this GitHub repository: |
|||
|
|||
https://github.com/m-aliozkaya/RepositoryPattern |
|||
|
|||
### Domain model and context |
|||
|
|||
We start with a single entity and a matching `DbContext`. |
|||
|
|||
`Product.cs` |
|||
|
|||
```csharp |
|||
using System.ComponentModel.DataAnnotations; |
|||
|
|||
namespace RepositoryPattern.Web.Models; |
|||
|
|||
public class Product |
|||
{ |
|||
public int Id { get; set; } |
|||
|
|||
[Required, StringLength(64)] |
|||
public string Name { get; set; } = string.Empty; |
|||
|
|||
[Range(0, double.MaxValue)] |
|||
public decimal Price { get; set; } |
|||
|
|||
[StringLength(256)] |
|||
public string? Description { get; set; } |
|||
|
|||
public int Stock { get; set; } |
|||
} |
|||
``` |
|||
|
|||
`"AppDbContext.cs` |
|||
|
|||
```csharp |
|||
using Microsoft.EntityFrameworkCore; |
|||
using RepositoryPattern.Web.Models; |
|||
|
|||
namespace RepositoryPattern.Web.Data; |
|||
|
|||
public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options) |
|||
{ |
|||
public DbSet<Product> Products => Set<Product>(); |
|||
} |
|||
``` |
|||
|
|||
### Generic repository contract and base class |
|||
|
|||
All entities share the same CRUD needs, so we define a generic interface and an EF Core implementation. |
|||
|
|||
`Repositories/IRepository.cs` |
|||
|
|||
```csharp |
|||
using System.Linq.Expressions; |
|||
|
|||
namespace RepositoryPattern.Web.Repositories; |
|||
|
|||
public interface IRepository<TEntity> where TEntity : class |
|||
{ |
|||
Task<TEntity?> GetByIdAsync(int id, CancellationToken cancellationToken = default); |
|||
Task<List<TEntity>> GetAllAsync(CancellationToken cancellationToken = default); |
|||
Task<List<TEntity>> GetListAsync(Expression<Func<TEntity, bool>> predicate, CancellationToken cancellationToken = default); |
|||
Task AddAsync(TEntity entity, CancellationToken cancellationToken = default); |
|||
Task UpdateAsync(TEntity entity, CancellationToken cancellationToken = default); |
|||
Task DeleteAsync(int id, CancellationToken cancellationToken = default); |
|||
} |
|||
``` |
|||
|
|||
`Repositories/EfRepository.cs` |
|||
|
|||
```csharp |
|||
using Microsoft.EntityFrameworkCore; |
|||
using RepositoryPattern.Web.Data; |
|||
|
|||
namespace RepositoryPattern.Web.Repositories; |
|||
|
|||
public class EfRepository<TEntity>(AppDbContext context) : IRepository<TEntity> |
|||
where TEntity : class |
|||
{ |
|||
protected readonly AppDbContext Context = context; |
|||
|
|||
public virtual async Task<TEntity?> GetByIdAsync(int id, CancellationToken cancellationToken = default) |
|||
=> await Context.Set<TEntity>().FindAsync([id], cancellationToken); |
|||
|
|||
public virtual async Task<List<TEntity>> GetAllAsync(CancellationToken cancellationToken = default) |
|||
=> await Context.Set<TEntity>().AsNoTracking().ToListAsync(cancellationToken); |
|||
|
|||
public virtual async Task<List<TEntity>> GetListAsync( |
|||
System.Linq.Expressions.Expression<Func<TEntity, bool>> predicate, |
|||
CancellationToken cancellationToken = default) |
|||
=> await Context.Set<TEntity>() |
|||
.AsNoTracking() |
|||
.Where(predicate) |
|||
.ToListAsync(cancellationToken); |
|||
|
|||
public virtual async Task AddAsync(TEntity entity, CancellationToken cancellationToken = default) |
|||
{ |
|||
await Context.Set<TEntity>().AddAsync(entity, cancellationToken); |
|||
await Context.SaveChangesAsync(cancellationToken); |
|||
} |
|||
|
|||
public virtual async Task UpdateAsync(TEntity entity, CancellationToken cancellationToken = default) |
|||
{ |
|||
Context.Set<TEntity>().Update(entity); |
|||
await Context.SaveChangesAsync(cancellationToken); |
|||
} |
|||
|
|||
public virtual async Task DeleteAsync(int id, CancellationToken cancellationToken = default) |
|||
{ |
|||
var entity = await GetByIdAsync(id, cancellationToken); |
|||
if (entity is null) |
|||
{ |
|||
return; |
|||
} |
|||
|
|||
Context.Set<TEntity>().Remove(entity); |
|||
await Context.SaveChangesAsync(cancellationToken); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Reads use `AsNoTracking()` to avoid tracking overhead, while write methods call `SaveChangesAsync` to keep the sample straightforward. |
|||
|
|||
### Product-specific repository |
|||
|
|||
Products need one extra query: list the items that are almost out of stock. We extend the generic repository with a dedicated interface and implementation. |
|||
|
|||
`Repositories/IProductRepository.cs` |
|||
|
|||
```csharp |
|||
using RepositoryPattern.Web.Models; |
|||
|
|||
namespace RepositoryPattern.Web.Repositories; |
|||
|
|||
public interface IProductRepository : IRepository<Product> |
|||
{ |
|||
Task<List<Product>> GetLowStockProductsAsync(int threshold, CancellationToken cancellationToken = default); |
|||
} |
|||
``` |
|||
|
|||
`Repositories/ProductRepository.cs` |
|||
|
|||
```csharp |
|||
using Microsoft.EntityFrameworkCore; |
|||
using RepositoryPattern.Web.Data; |
|||
using RepositoryPattern.Web.Models; |
|||
|
|||
namespace RepositoryPattern.Web.Repositories; |
|||
|
|||
public class ProductRepository(AppDbContext context) : EfRepository<Product>(context), IProductRepository |
|||
{ |
|||
public Task<List<Product>> GetLowStockProductsAsync(int threshold, CancellationToken cancellationToken = default) => |
|||
Context.Products |
|||
.AsNoTracking() |
|||
.Where(product => product.Stock <= threshold) |
|||
.OrderBy(product => product.Stock) |
|||
.ToListAsync(cancellationToken); |
|||
} |
|||
``` |
|||
|
|||
### 🧩 A Note on Unit of Work |
|||
|
|||
The Repository Pattern is often used together with the **Unit of Work** pattern to manage transactions efficiently. |
|||
|
|||
> 💡 *If you want to dive deeper into the Unit of Work pattern, check out our separate blog post dedicated to that topic. https://abp.io/community/articles/lv4v2tyf |
|||
|
|||
### Service layer and controller |
|||
|
|||
Controllers depend on a service, and the service depends on the repository. That keeps HTTP logic and data logic separate. |
|||
|
|||
`Services/ProductService.cs` |
|||
|
|||
```csharp |
|||
using RepositoryPattern.Web.Models; |
|||
using RepositoryPattern.Web.Repositories; |
|||
|
|||
namespace RepositoryPattern.Web.Services; |
|||
|
|||
public class ProductService(IProductRepository productRepository) |
|||
{ |
|||
private readonly IProductRepository _productRepository = productRepository; |
|||
|
|||
public Task<List<Product>> GetProductsAsync(CancellationToken cancellationToken = default) => |
|||
_productRepository.GetAllAsync(cancellationToken); |
|||
|
|||
public Task<List<Product>> GetLowStockAsync(int threshold, CancellationToken cancellationToken = default) => |
|||
_productRepository.GetLowStockProductsAsync(threshold, cancellationToken); |
|||
|
|||
public Task<Product?> GetByIdAsync(int id, CancellationToken cancellationToken = default) => |
|||
_productRepository.GetByIdAsync(id, cancellationToken); |
|||
|
|||
public Task CreateAsync(Product product, CancellationToken cancellationToken = default) => |
|||
_productRepository.AddAsync(product, cancellationToken); |
|||
|
|||
public Task UpdateAsync(Product product, CancellationToken cancellationToken = default) => |
|||
_productRepository.UpdateAsync(product, cancellationToken); |
|||
|
|||
public Task DeleteAsync(int id, CancellationToken cancellationToken = default) => |
|||
_productRepository.DeleteAsync(id, cancellationToken); |
|||
} |
|||
``` |
|||
|
|||
`Controllers/ProductsController.cs` |
|||
|
|||
```csharp |
|||
using Microsoft.AspNetCore.Mvc; |
|||
using RepositoryPattern.Web.Models; |
|||
using RepositoryPattern.Web.Services; |
|||
|
|||
namespace RepositoryPattern.Web.Controllers; |
|||
|
|||
public class ProductsController(ProductService productService) : Controller |
|||
{ |
|||
private readonly ProductService _productService = productService; |
|||
|
|||
public async Task<IActionResult> Index(CancellationToken cancellationToken) |
|||
{ |
|||
const int lowStockThreshold = 5; |
|||
var products = await _productService.GetProductsAsync(cancellationToken); |
|||
var lowStock = await _productService.GetLowStockAsync(lowStockThreshold, cancellationToken); |
|||
|
|||
return View(new ProductListViewModel(products, lowStock, lowStockThreshold)); |
|||
} |
|||
|
|||
// remaining CRUD actions call through ProductService in the same way |
|||
} |
|||
``` |
|||
|
|||
The controller never reaches for `AppDbContext`. Every operation travels through the service, which keeps tests simple and makes future refactors easier. |
|||
|
|||
### Dependency registration and seeding |
|||
|
|||
The last step is wiring everything up in `Program.cs`. |
|||
|
|||
```csharp |
|||
builder.Services.AddDbContext<AppDbContext>(options => |
|||
options.UseInMemoryDatabase("ProductsDb")); |
|||
builder.Services.AddScoped(typeof(IRepository<>), typeof(EfRepository<>)); |
|||
builder.Services.AddScoped<IProductRepository, ProductRepository>(); |
|||
builder.Services.AddScoped<ProductService>(); |
|||
``` |
|||
|
|||
The sample also seeds three products so the list page shows data on first run. |
|||
|
|||
Run the site with: |
|||
|
|||
```powershell |
|||
dotnet run --project RepositoryPattern.Web |
|||
``` |
|||
|
|||
## How ABP approaches the same idea |
|||
|
|||
ABP includes generic repositories by default (`IRepository<TEntity, TKey>`), so you often skip writing the implementation layer shown above. You inject the interface into an application service, call methods like `InsertAsync` or `CountAsync`, and ABP’s Unit of Work handles the transaction. When you need custom queries, you can still derive from `EfCoreRepository<TEntity, TKey>` and add them. |
|||
|
|||
For more details, check out the official ABP documentation on repositories: https://abp.io/docs/latest/framework/architecture/domain-driven-design/repositories |
|||
|
|||
### Closing note |
|||
|
|||
This setup keeps data access tidy without being heavy. Start with the generic repository, add small extensions per entity, pass everything through services, and register the dependencies once. Whether you hand-code it or let ABP supply the repository, the structure stays the same and your controllers remain clean. |
|||
|
After Width: | Height: | Size: 504 KiB |
@ -0,0 +1,98 @@ |
|||
# **Return Code vs Exceptions: Which One is Better?** |
|||
|
|||
Alright, so this debate pops up every few months on dev subreddits and forums |
|||
|
|||
> *Should you use return codes or exceptions for error handling?* |
|||
|
|||
And honestly, there’s no %100 right answer here! Both have pros/cons, and depending on the language or context, one might make more sense than the other. Let’s see... |
|||
|
|||
------ |
|||
|
|||
## 1. Return Codes --- Said to be "Old School Way" --- |
|||
|
|||
Return codes (like `0` for success, `-1` for failure, etc.) are the OG method. You mostly see them everywhere in C and C++. |
|||
They’re super explicit, the function literally *returns* the result of the operation. |
|||
|
|||
### ➕ Advantages of returning codes: |
|||
|
|||
- You *always* know when something went wrong |
|||
- No hidden control flow — what you see is what you get |
|||
- Usually faster (no stack unwinding, no exception overhead) |
|||
- Easy to use in systems programming, embedded stuff, or performance-critical code |
|||
|
|||
### ➖ Disadvantages of returning codes: |
|||
|
|||
- It’s easy to forget to check the return value (and boom, silent failure 😬) |
|||
- Makes code noisy... Everry function call followed by `if (result != SUCCESS)` gets annoying |
|||
- No stack trace or context unless you manually build one |
|||
|
|||
**For example:** |
|||
|
|||
```csharp |
|||
try |
|||
{ |
|||
await SendEmailAsync(); |
|||
} |
|||
catch (Exception e) |
|||
{ |
|||
Log.Exception(e.ToString()); |
|||
return -1; |
|||
} |
|||
``` |
|||
|
|||
Looks fine… until you forget one of those `if` conditions somewhere. |
|||
|
|||
------ |
|||
|
|||
## 2. Exceptions --- The Fancy & Modern Way --- |
|||
|
|||
Exceptions came in later, mostly with higher-level languages like Java, C#, and Python. |
|||
The idea is that you *throw* an error and handle it *somewhere else*. |
|||
|
|||
### ➕ Advantages of throwing exceptions: |
|||
|
|||
- Cleaner code... You can focus on the happy path and handle errors separately |
|||
- Can carry detailed info (stack traces, messages, inner exceptions...) |
|||
- Easier to handle complex error propagation |
|||
|
|||
### ➖ Disadvantages of throwing exceptions: |
|||
|
|||
- Hidden control flow — you don’t always see what might throw |
|||
- Performance hit (esp. in tight loops or low-level systems) |
|||
- Overused in some codebases (“everything throws everything”) |
|||
|
|||
**Example:** |
|||
|
|||
```csharp |
|||
try |
|||
{ |
|||
await SendEmailAsync(); |
|||
} |
|||
catch (Exception e) |
|||
{ |
|||
Log.Exception(e.ToString()); |
|||
throw e; |
|||
} |
|||
``` |
|||
|
|||
Way cleaner, but if `SendEmailAsync()` is deep in your call stack and it fails, it can be tricky to know exactly what went wrong unless you log properly. |
|||
|
|||
------ |
|||
|
|||
### And Which One’s Better? ⚖️ |
|||
|
|||
Depends on what you’re building. |
|||
|
|||
- **Low-level systems, drivers, real-time stuff 👉 Return codes.** Performance and control matter more. |
|||
- **Application-level, business logic, or high-level APIs 👉 Exceptions.** Cleaner and easier to maintain. |
|||
|
|||
And honestly, mixing both sometimes makes sense. |
|||
For example, you can use return codes internally and exceptions at the boundary of your API to surface meaningful errors to the user. |
|||
|
|||
------ |
|||
|
|||
### Conclusion |
|||
|
|||
Return codes = simple, explicit, but messy.t |
|||
Exceptions = clean, powerful, but can bite you. |
|||
Use what fits your project and your team’s sanity level 😅. |
|||
|
After Width: | Height: | Size: 5.1 KiB |
|
After Width: | Height: | Size: 52 KiB |
|
After Width: | Height: | Size: 107 KiB |
@ -0,0 +1,112 @@ |
|||
# UI & UX Trends That Will Shape 2026 |
|||
|
|||
Cinematic, gamified, high-wow-factor websites with scroll-to-play videos or scroll-to-tell stories are wonderful to experience, but you won't find these trends in this article. If you're interested in design trends directly related to the software world, such as **performance**, **accessibility**, **understandability**, and **efficiency**, grab a cup of coffee and enjoy. |
|||
|
|||
As we approach the end of 2025, I'd like to share with you the most important user interface and user experience design trends that have become more of a **toolkit** than a trend, and that continue to evolve and become a part of our lives. I predict we'll see a lot of them in 2026\. |
|||
|
|||
## 1\. Simplicity and Speed |
|||
|
|||
Designing understandable and readable applications is becoming far more important than designing in line with trends and fashion. In the software and business world, preferences are shifting more and more toward the **right design** over the cool design. As designers developing a product whose direct target audience is software developers, we design our products for the designers' enjoyment, but for the **end user's ease of use**. |
|||
|
|||
Users no longer care so much about the flashiness of a website. True converts are primarily interested in your product, service, or content. What truly matters to them is how easily and quickly they can access the information they're looking for. |
|||
|
|||
More users, more sales, better promotion, and a higher conversion rate... The elements that serve these goals are optimized solutions and thoughtful details in our designs, more than visual displays. |
|||
|
|||
If the "loading" icon appears too often on your digital product, you might not be doing it right. If you fail to optimize speed, the temporary effect of visual displays won't be enough to convert potential users into customers. Remember, the moment people start waiting, you've lost at least half of them. |
|||
|
|||
## 2\. Dark Mode \- Still, and Forever |
|||
 |
|||
|
|||
Dark Mode is no longer an option; it's a **standard**. It's become a necessity, not a choice, especially for users who spend hours staring at screens and are accustomed to dark themes in code editors and terminals. However, the approach to dark mode isn't simply about inverting colors; it's much deeper than that. The key is managing contrast and depth. |
|||
|
|||
The layer hierarchy established in a light-colored design doesn't lose its impact when switched to dark mode. The colors, shadows, highlights, and contrasting elements used to create an **easily perceivable hierarchy** should be carefully considered for each mode. Our [LeptonX theme](https://leptontheme.com/)'s Light, Dark, Semi-dark, and System modes offer valuable insights you might want to explore. |
|||
|
|||
You might also want to take a look at the dark and light modes we designed with these elements in mind in [ABP Studio](https://abp.io/get-started) and the [ABP.io Documents page](https://abp.io/docs/latest/). |
|||
|
|||
## 3\. Bento Grid \- A Timeless Trend |
|||
 |
|||
|
|||
People don't read your website; they **scan** it. |
|||
|
|||
Bento Grid, an indispensable trend for designers looking to manage their attention, looks set to remain a staple in 2026, just as it was in 2025\. No designer should ignore the fact that many tech giants, especially Apple and Samsung, are still using bento grids on their websites. The bento grid appears not only on websites but also in operating systems, VR headset interfaces, game console interfaces, and game designs. |
|||
|
|||
The golden rule is **contrast** and **balance**. |
|||
|
|||
The attractiveness and effectiveness of bento designs depend on certain factors you should consider when implementing them. If you ignore these rules, even with a proven method like bento, you can still alienate users. |
|||
|
|||
The bento grid is one of the best ways to display different types of content inclusively. When used correctly, it's also a great way to manipulate reading order, guiding the user's eye. Improper contrast and hierarchy can also create a negative experience. Designers should use this to guide the reader's eye: "Read here first, then read here." |
|||
|
|||
When creating a bento, you inherently have to sacrifice some of your "whitespace." This design has many elements for the user to focus on, and it actually strays from our first point, "Simplicity". Bento design, whose boundaries are drawn from the outset and independent of content, requires care not to include more or less than what is necessary. Too much content makes it boring; too little content makes it very close to meaningless. |
|||
|
|||
Bento grids should aim for a balanced design by using both simple text and sophisticated visuals. This visual can be an illustration, a video that starts playing when hovered over, a static image, or a large title. Only one or two cards on the screen at a time should have attention. |
|||
|
|||
## 4\. Larger Fonts, High Readability |
|||
 |
|||
|
|||
Large fonts have been a trend for several years, and it seems web designers are becoming more and more bold. The increasing preference for larger fonts every year is a sign that this trend will continue into 2026\. This trend is about more than just using large font sizes in headlines. |
|||
|
|||
Creating a cohesive typographic scale and proper line height and letter spacing are critical elements to consider when creating this trend. As the font size increases, line height should decrease, and the space between letters should be narrower. |
|||
|
|||
The browser default font size, which we used to see in body text and paragraphs and has now become standard, is 16 pixels. In the last few years, we've started seeing body font sizes of 17 or 18 pixels more frequently. The increasing importance of readability every year makes this more common. Font sizes in rem values, rather than px, provide the most efficient results. |
|||
|
|||
## 5\. Micro Animations |
|||
|
|||
Unless you're a web design agency designing a website to impress potential clients, you should avoid excessive changes, including excessive image changes during scrolling, and scroll direction changes. There's still room for oversized images and scroll animations. But be sure to create the visuals yourself. |
|||
|
|||
The trend I'm talking about here is **micro animations**, not macro ones. Small movements, not large ones. |
|||
|
|||
The animation approach of 2025 is **functional** and **performance-sensitive**. |
|||
|
|||
Microanimations exist to provide immediate feedback to the user. Instant feedback, like a button's shadow increasing when hovered over, a button's slight collapse when clicked, or a "Save" icon changing to a "Confirm" icon when saving data, keeps your designs alive. |
|||
|
|||
We see the real impact of the micro-animation trend in static, non-action visuals. The use of non-button elements in your designs, accentuated by micro-movements such as scrolling or hovering, seems poised to continue to create macro effects in 2026\. |
|||
|
|||
## 6\. Real Images and Human-like Touches |
|||
|
|||
People quickly spot a fake. It's very difficult to convince a user who visits your website for the first time and doesn't trust you. **First impressions** matter. |
|||
|
|||
Real photographs, actual product screenshots, and brand-specific illustrations will continue to be among the elements we want to see in **trust-focused** designs in 2026\. |
|||
|
|||
In addition to flawless work done by AI, vivid, real-life visuals, accompanied by deliberate imperfections, hand-drawn details, or designed products that convey the message, "A human made this site\!", will continue to feel warmer and more welcoming. |
|||
|
|||
The human touch is evident not only in the visuals but also in your **content and text**. |
|||
|
|||
In 2026, you'll need more **human-like touches** that will make your design stand out among the thousands of similar websites rapidly generated by AI. |
|||
|
|||
## 7\. Accessibility \- No Longer an Option, But a Legal and Ethical Obligation |
|||
|
|||
Accessibility, once considered a nice-to-do thing in recent years, is now becoming a **necessity** in 2026 and beyond. Global regulations like the European Accessibility Act require all digital products to comply with WCAG standards. |
|||
|
|||
All design and software improvements you make to ensure end users can fully perform their tasks in your products, regardless of their temporary or permanent disabilities, should be viewed as ethical and commercial requirements, not as a requirement to comply with these standards. |
|||
|
|||
The foundation of accessibility in design is to use semantic HTML for screen readers, provide full keyboard control of all interactive elements, and clearly communicate the roles of complex components to the development team. |
|||
|
|||
## 8\. Intentional Friction |
|||
|
|||
Steve Krug, the father of UX design, started the trend of designing everything at a hyper-usable level with his book "Don't Make Me Think." As web designers, we've embraced this idea so much that all we care about is getting the user to their destination in the shortest possible scenario and as quickly as possible. This has required so many understandability measures that, after a while, it's starting to feel like fooling the user. |
|||
|
|||
In recent years, designers have started looking for ways to make things a little more challenging, rather than just getting the user to the result. |
|||
|
|||
When the end user visits your website, tries to understand exactly what it is at first glance, struggles a bit, and, after a little effort, becomes familiar with how your world works, they'll be more inclined to consider themselves a part of it. |
|||
|
|||
This has nothing to do with anti-usability. This philosophy is called Intentional Friction. |
|||
|
|||
This isn't a flaw; it's the pinnacle of error prevention. It's a step to prevent errors from occurring on autopilot and respects the user's ability to understand complex systems. Examples include reviewing the order summary or manually typing the project name when deleting a project on GitHub. |
|||
|
|||
## Bonus: Where Does Artificial Intelligence Fit In? |
|||
|
|||
Artificial intelligence will be an infrastructure in 2026, not a trend. |
|||
|
|||
As designers, we should leverage AI not to paint us a picture, but to make workflows more intelligent. In my opinion, this is the best use case for AI. |
|||
|
|||
AI can learn user behavior and adapt the interface accordingly. Real-time A/B testing can save us time by conducting a real-time content review. The ability to actively use AI in any area that allows you to accelerate your progress will take you a step further in your career. |
|||
|
|||
Since your users are always human, **don't be too eager** to incorporate AI-generated visuals into your design. Unless you're creating and selling a ready-made theme, you should **avoid** AI-generated visuals, random bento grids, and randomly generated content. |
|||
|
|||
You should definitely incorporate AI into your work for new content, new ideas, personal and professional development, and insights that will take your design a step further. But just as you don't design your website for designers to like, the same applies to AI. Humans, not robots, will experience your website. **AI-assisted**, not AI-generated, designs with a human touch are the trend I most expect seeing in 2026\. |
|||
|
|||
## Conclusion |
|||
|
|||
In the end, it's all fundamentally about respect for the user and their time. In 2026, our success as designers and developers will be measured not by how "cool" we are, but by how "efficient" and "reliable" a world we build for our users. |
|||
|
|||
Thank you for your time. |
|||
|
After Width: | Height: | Size: 56 KiB |
|
After Width: | Height: | Size: 54 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 37 KiB |
@ -0,0 +1,592 @@ |
|||
# What is That Domain Service in DDD for .NET Developers? |
|||
|
|||
When you start applying **Domain-Driven Design (DDD)** in your .NET projects, you'll quickly meet some core building blocks: **Entities**, **Value Objects**, **Aggregates**, and finally… **Domain Services**. |
|||
|
|||
But what exactly *is* a Domain Service, and when should you use one? |
|||
|
|||
Let's break it down with practical examples and ABP Framework implementation patterns. |
|||
|
|||
--- |
|||
|
|||
 |
|||
|
|||
## The Core Idea of Domain Services |
|||
|
|||
A **Domain Service** represents **a domain concept that doesn't naturally belong to a single Entity or Value Object**, but still belongs to the **domain layer** - *not* to the application or infrastructure. |
|||
|
|||
In short: |
|||
|
|||
> If your business logic doesn't fit into a single Entity, but still expresses a business rule, that's a good candidate for a Domain Service. |
|||
|
|||
|
|||
|
|||
--- |
|||
|
|||
## Example: Money Transfer Between Accounts |
|||
|
|||
Imagine a simple **banking system** where you can transfer money between accounts. |
|||
|
|||
```csharp |
|||
public class Account : AggregateRoot<Guid> |
|||
{ |
|||
public decimal Balance { get; private set; } |
|||
|
|||
// Domain model should be created in a valid state. |
|||
public Account(decimal openingBalance = 0m) |
|||
{ |
|||
if (openingBalance < 0) |
|||
throw new BusinessException("Opening balance cannot be negative."); |
|||
Balance = openingBalance; |
|||
} |
|||
|
|||
public void Withdraw(decimal amount) |
|||
{ |
|||
if (amount <= 0) |
|||
throw new BusinessException("Withdrawal amount must be positive."); |
|||
if (Balance < amount) |
|||
throw new BusinessException("Insufficient balance."); |
|||
Balance -= amount; |
|||
} |
|||
|
|||
public void Deposit(decimal amount) |
|||
{ |
|||
if (amount <= 0) |
|||
throw new BusinessException("Deposit amount must be positive."); |
|||
Balance += amount; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> In a richer domain you might introduce a `Money` value object (amount + currency + rounding rules) instead of a raw `decimal` for stronger invariants. |
|||
|
|||
--- |
|||
|
|||
## Implementing a Domain Service |
|||
|
|||
 |
|||
|
|||
```csharp |
|||
public class MoneyTransferManager : DomainService |
|||
{ |
|||
public void Transfer(Account from, Account to, decimal amount) |
|||
{ |
|||
if (from is null) throw new ArgumentNullException(nameof(from)); |
|||
if (to is null) throw new ArgumentNullException(nameof(to)); |
|||
if (ReferenceEquals(from, to)) |
|||
throw new BusinessException("Cannot transfer to the same account."); |
|||
if (amount <= 0) |
|||
throw new BusinessException("Transfer amount must be positive."); |
|||
|
|||
from.Withdraw(amount); |
|||
to.Deposit(amount); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> **Naming Convention**: ABP suggests using the `Manager` or `Service` suffix for domain services. We typically use `Manager` suffix (e.g., `IssueManager`, `OrderManager`). |
|||
|
|||
> **Note**: This is a synchronous domain operation. The domain service focuses purely on business rules without infrastructure concerns like database access or event publishing. For cross-cutting concerns, use Application Service layer or domain events. |
|||
|
|||
--- |
|||
|
|||
## Domain Service vs. Application Service |
|||
|
|||
Here's a quick comparison: |
|||
|
|||
 |
|||
|
|||
| Layer | Responsibility | Example | |
|||
| ----------------------- | -------------------------------------------------------------------------------- | ---------------------------- | |
|||
| **Domain Service** | Pure business rule spanning entities/aggregates | `MoneyTransferManager` | |
|||
| **Application Service** | Orchestrates use cases, handles repositories, transactions, external systems | `BankAppService` | |
|||
|
|||
--- |
|||
|
|||
## The Application Service Layer |
|||
|
|||
An **Application Service** orchestrates the domain logic and handles infrastructure concerns: |
|||
|
|||
 |
|||
|
|||
```csharp |
|||
public class BankAppService : ApplicationService |
|||
{ |
|||
private readonly IRepository<Account, Guid> _accountRepository; |
|||
private readonly MoneyTransferManager _moneyTransferManager; |
|||
|
|||
public BankAppService( |
|||
IRepository<Account, Guid> accountRepository, |
|||
MoneyTransferManager moneyTransferManager) |
|||
{ |
|||
_accountRepository = accountRepository; |
|||
_moneyTransferManager = moneyTransferManager; |
|||
} |
|||
|
|||
public async Task TransferAsync(Guid fromId, Guid toId, decimal amount) |
|||
{ |
|||
var from = await _accountRepository.GetAsync(fromId); |
|||
var to = await _accountRepository.GetAsync(toId); |
|||
|
|||
_moneyTransferManager.Transfer(from, to, amount); |
|||
|
|||
await _accountRepository.UpdateAsync(from); |
|||
await _accountRepository.UpdateAsync(to); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> **Note**: Domain services are automatically registered to Dependency Injection with a **Transient** lifetime when inheriting from `DomainService`. |
|||
|
|||
--- |
|||
|
|||
## Benefits of ABP's DomainService Base Class |
|||
|
|||
The `DomainService` base class gives you access to: |
|||
|
|||
- **Localization** (`IStringLocalizer L`) - Multi-language support for error messages |
|||
- **Logging** (`ILogger Logger`) - Built-in logger for tracking operations |
|||
- **Local Event Bus** (`ILocalEventBus LocalEventBus`) - Publish local domain events |
|||
- **Distributed Event Bus** (`IDistributedEventBus DistributedEventBus`) - Publish distributed events |
|||
- **GUID Generator** (`IGuidGenerator GuidGenerator`) - Sequential GUID generation for better database performance |
|||
- **Clock** (`IClock Clock`) - Abstraction for date/time operations |
|||
|
|||
### Example with ABP Features |
|||
|
|||
> **Important**: While domain services *can* publish domain events using the event bus, they should remain focused on business rules. Consider whether event publishing belongs in the domain service or the application service based on your consistency boundaries. |
|||
|
|||
```csharp |
|||
public class MoneyTransferredEvent |
|||
{ |
|||
public Guid FromAccountId { get; set; } |
|||
public Guid ToAccountId { get; set; } |
|||
public decimal Amount { get; set; } |
|||
} |
|||
|
|||
public class MoneyTransferManager : DomainService |
|||
{ |
|||
public async Task TransferAsync(Account from, Account to, decimal amount) |
|||
{ |
|||
if (from is null) throw new ArgumentNullException(nameof(from)); |
|||
if (to is null) throw new ArgumentNullException(nameof(to)); |
|||
if (ReferenceEquals(from, to)) |
|||
throw new BusinessException(L["SameAccountTransferNotAllowed"]); |
|||
if (amount <= 0) |
|||
throw new BusinessException(L["InvalidTransferAmount"]); |
|||
|
|||
// Log the operation |
|||
Logger.LogInformation( |
|||
"Transferring {Amount} from {From} to {To}", amount, from.Id, to.Id); |
|||
|
|||
from.Withdraw(amount); |
|||
to.Deposit(amount); |
|||
|
|||
// Publish local event for further policies (limits, notifications, audit, etc.) |
|||
await LocalEventBus.PublishAsync( |
|||
new MoneyTransferredEvent |
|||
{ |
|||
FromAccountId = from.Id, |
|||
ToAccountId = to.Id, |
|||
Amount = amount |
|||
} |
|||
); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> **Local Events**: By default, event handlers are executed within the same Unit of Work. If an event handler throws an exception, the database transaction is rolled back, ensuring consistency. |
|||
|
|||
--- |
|||
|
|||
## Best Practices |
|||
|
|||
### 1. Keep Domain Services Pure and Focused on Business Rules |
|||
|
|||
Domain services should only contain business logic. They should not be responsible for application-level concerns like database transactions, authorization, or fetching entities from a repository. |
|||
|
|||
```csharp |
|||
// Good ✅ Pure rule: receives aggregates already loaded. |
|||
public class MoneyTransferManager : DomainService |
|||
{ |
|||
public void Transfer(Account from, Account to, decimal amount) |
|||
{ |
|||
// Business rules and coordination |
|||
from.Withdraw(amount); |
|||
to.Deposit(amount); |
|||
} |
|||
} |
|||
|
|||
// Bad ❌ Mixing application and domain concerns. |
|||
// This logic belongs in an Application Service. |
|||
public class MoneyTransferManager : DomainService |
|||
{ |
|||
private readonly IRepository<Account, Guid> _accountRepository; |
|||
|
|||
public MoneyTransferManager(IRepository<Account, Guid> accountRepository) |
|||
{ |
|||
_accountRepository = accountRepository; |
|||
} |
|||
|
|||
public async Task TransferAsync(Guid fromId, Guid toId, decimal amount) |
|||
{ |
|||
// Don't fetch entities inside a domain service. |
|||
var from = await _accountRepository.GetAsync(fromId); |
|||
var to = await _accountRepository.GetAsync(toId); |
|||
|
|||
from.Withdraw(amount); |
|||
to.Deposit(amount); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 2. Leverage Entity Methods First |
|||
|
|||
Always prefer encapsulating business logic within an entity's methods when the logic belongs to a single aggregate. A domain service should only be used when a business rule spans multiple aggregates. |
|||
|
|||
```csharp |
|||
// Good ✅ - Internal state change belongs in the entity |
|||
public class Account : AggregateRoot<Guid> |
|||
{ |
|||
public decimal Balance { get; private set; } |
|||
|
|||
public void Withdraw(decimal amount) |
|||
{ |
|||
if (Balance < amount) |
|||
throw new BusinessException("Insufficient balance"); |
|||
Balance -= amount; |
|||
} |
|||
} |
|||
|
|||
// Use Domain Service only when logic spans multiple aggregates |
|||
public class MoneyTransferManager : DomainService |
|||
{ |
|||
public void Transfer(Account from, Account to, decimal amount) |
|||
{ |
|||
from.Withdraw(amount); // Delegates to entity |
|||
to.Deposit(amount); // Delegates to entity |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 3. Prefer Domain Services over Anemic Entities |
|||
|
|||
Avoid placing business logic that coordinates multiple entities directly into an application service. This leads to an "Anemic Domain Model," where entities are just data bags and the business logic is scattered in application services. |
|||
|
|||
```csharp |
|||
// Bad ❌ - Business logic is in the Application Service (Anemic Domain) |
|||
public class BankAppService : ApplicationService |
|||
{ |
|||
public async Task TransferAsync(Guid fromId, Guid toId, decimal amount) |
|||
{ |
|||
var from = await _accountRepository.GetAsync(fromId); |
|||
var to = await _accountRepository.GetAsync(toId); |
|||
|
|||
// This is domain logic and should be in a Domain Service |
|||
if (ReferenceEquals(from, to)) |
|||
throw new BusinessException("Cannot transfer to the same account."); |
|||
if (amount <= 0) |
|||
throw new BusinessException("Transfer amount must be positive."); |
|||
|
|||
from.Withdraw(amount); |
|||
to.Deposit(amount); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 4. Use Meaningful Names |
|||
|
|||
ABP recommends naming domain services with a `Manager` or `Service` suffix based on the business concept they represent. |
|||
|
|||
```csharp |
|||
// Good ✅ |
|||
MoneyTransferManager |
|||
OrderManager |
|||
IssueManager |
|||
InventoryAllocationService |
|||
|
|||
// Bad ❌ |
|||
AccountHelper |
|||
OrderProcessor |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Advanced Example: Order Processing with Inventory Check |
|||
|
|||
Here's a more complex scenario showing domain service interaction with domain abstractions: |
|||
|
|||
```csharp |
|||
// Domain abstraction - defines contract but implementation is in infrastructure |
|||
public interface IInventoryChecker : IDomainService |
|||
{ |
|||
Task<bool> IsAvailableAsync(Guid productId, int quantity); |
|||
} |
|||
|
|||
public class OrderManager : DomainService |
|||
{ |
|||
private readonly IInventoryChecker _inventoryChecker; |
|||
|
|||
public OrderManager(IInventoryChecker inventoryChecker) |
|||
{ |
|||
_inventoryChecker = inventoryChecker; |
|||
} |
|||
|
|||
// Validates and coordinates order processing with inventory |
|||
public async Task ProcessAsync(Order order, Inventory inventory) |
|||
{ |
|||
// First pass: validate availability using domain abstraction |
|||
foreach (var item in order.Items) |
|||
{ |
|||
if (!await _inventoryChecker.IsAvailableAsync(item.ProductId, item.Quantity)) |
|||
{ |
|||
throw new BusinessException( |
|||
L["InsufficientInventory", item.ProductId]); |
|||
} |
|||
} |
|||
|
|||
// Second pass: perform reservations |
|||
foreach (var item in order.Items) |
|||
{ |
|||
inventory.Reserve(item.ProductId, item.Quantity); |
|||
} |
|||
|
|||
order.SetStatus(OrderStatus.Processing); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
> **Domain Abstractions**: The `IInventoryChecker` interface is a domain service contract. Its implementation can be in the infrastructure layer, but the contract belongs to the domain. This keeps the domain layer independent of infrastructure details while still allowing complex validations. |
|||
|
|||
> **Caution**: Always perform validation and action atomically within a single transaction to avoid race conditions (TOCTOU - Time Of Check Time Of Use). |
|||
|
|||
> **Transaction Boundaries**: When a domain service coordinates multiple aggregates, ensure the Application Service wraps the operation in a Unit of Work to maintain consistency. ABP's `[UnitOfWork]` attribute or Application Services' built-in UoW handling ensures this automatically. |
|||
|
|||
--- |
|||
|
|||
## Common Pitfalls and How to Avoid Them |
|||
|
|||
### 1. Bloated Domain Services |
|||
Don't let domain services become "god objects" that do everything. Keep them focused on a single business concept. |
|||
|
|||
```csharp |
|||
// Bad ❌ - Too many responsibilities |
|||
public class AccountManager : DomainService |
|||
{ |
|||
public void Transfer(Account from, Account to, decimal amount) { } |
|||
public void CalculateInterest(Account account) { } |
|||
public void GenerateStatement(Account account) { } |
|||
public void ValidateAddress(Account account) { } |
|||
public void SendNotification(Account account) { } |
|||
} |
|||
|
|||
// Good ✅ - Split by business concept |
|||
public class MoneyTransferManager : DomainService |
|||
{ |
|||
public void Transfer(Account from, Account to, decimal amount) { } |
|||
} |
|||
|
|||
public class InterestCalculationManager : DomainService |
|||
{ |
|||
public void Calculate(Account account) { } |
|||
} |
|||
``` |
|||
|
|||
### 2. Circular Dependencies Between Aggregates |
|||
When domain services coordinate multiple aggregates, be careful about creating circular dependencies. |
|||
|
|||
```csharp |
|||
// Consider using Domain Events instead of direct coupling |
|||
public class OrderManager : DomainService |
|||
{ |
|||
public async Task ProcessAsync(Order order) |
|||
{ |
|||
order.SetStatus(OrderStatus.Processing); |
|||
|
|||
// Instead of directly modifying Customer aggregate here, |
|||
// publish an event that CustomerManager can handle |
|||
await LocalEventBus.PublishAsync(new OrderProcessedEvent |
|||
{ |
|||
OrderId = order.Id, |
|||
CustomerId = order.CustomerId |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 3. Confusing Domain Service with Domain Event Handlers |
|||
Domain services orchestrate business operations. Domain event handlers react to state changes. Don't mix them. |
|||
|
|||
```csharp |
|||
// Domain Service - Orchestrates business logic |
|||
public class MoneyTransferManager : DomainService |
|||
{ |
|||
public async Task TransferAsync(Account from, Account to, decimal amount) |
|||
{ |
|||
from.Withdraw(amount); |
|||
to.Deposit(amount); |
|||
await LocalEventBus.PublishAsync( |
|||
new MoneyTransferredEvent |
|||
{ |
|||
FromAccountId = from.Id, |
|||
ToAccountId = to.Id, |
|||
Amount = amount |
|||
} |
|||
); |
|||
} |
|||
} |
|||
|
|||
// Domain Event Handler - Reacts to domain events |
|||
public class MoneyTransferredEventHandler : |
|||
ILocalEventHandler<MoneyTransferredEvent>, |
|||
ITransientDependency |
|||
{ |
|||
public async Task HandleEventAsync(MoneyTransferredEvent eventData) |
|||
{ |
|||
// Send notification, update analytics, etc. |
|||
} |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Testing Domain Services |
|||
|
|||
Domain services are easy to test because they have minimal dependencies: |
|||
|
|||
```csharp |
|||
public class MoneyTransferManager_Tests |
|||
{ |
|||
[Fact] |
|||
public void Should_Transfer_Money_Between_Accounts() |
|||
{ |
|||
// Arrange |
|||
var fromAccount = new Account(1000m); |
|||
var toAccount = new Account(500m); |
|||
var manager = new MoneyTransferManager(); |
|||
|
|||
// Act |
|||
manager.Transfer(fromAccount, toAccount, 200m); |
|||
|
|||
// Assert |
|||
fromAccount.Balance.ShouldBe(800m); |
|||
toAccount.Balance.ShouldBe(700m); |
|||
} |
|||
|
|||
[Fact] |
|||
public void Should_Throw_When_Insufficient_Balance() |
|||
{ |
|||
var fromAccount = new Account(100m); |
|||
var toAccount = new Account(500m); |
|||
var manager = new MoneyTransferManager(); |
|||
|
|||
Should.Throw<BusinessException>(() => |
|||
manager.Transfer(fromAccount, toAccount, 200m)); |
|||
} |
|||
|
|||
[Fact] |
|||
public void Should_Throw_When_Amount_Is_NonPositive() |
|||
{ |
|||
var fromAccount = new Account(100m); |
|||
var toAccount = new Account(100m); |
|||
var manager = new MoneyTransferManager(); |
|||
|
|||
Should.Throw<BusinessException>(() => |
|||
manager.Transfer(fromAccount, toAccount, 0m)); |
|||
Should.Throw<BusinessException>(() => |
|||
manager.Transfer(fromAccount, toAccount, -5m)); |
|||
} |
|||
|
|||
[Fact] |
|||
public void Should_Throw_When_Same_Account() |
|||
{ |
|||
var account = new Account(100m); |
|||
var manager = new MoneyTransferManager(); |
|||
|
|||
Should.Throw<BusinessException>(() => |
|||
manager.Transfer(account, account, 10m)); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Integration Testing with ABP Test Infrastructure |
|||
|
|||
```csharp |
|||
public class MoneyTransferManager_IntegrationTests : BankingDomainTestBase |
|||
{ |
|||
private readonly MoneyTransferManager _transferManager; |
|||
private readonly IRepository<Account, Guid> _accountRepository; |
|||
|
|||
public MoneyTransferManager_IntegrationTests() |
|||
{ |
|||
_transferManager = GetRequiredService<MoneyTransferManager>(); |
|||
_accountRepository = GetRequiredService<IRepository<Account, Guid>>(); |
|||
} |
|||
|
|||
[Fact] |
|||
public async Task Should_Transfer_And_Persist_Changes() |
|||
{ |
|||
// Arrange |
|||
var fromAccount = new Account(1000m); |
|||
var toAccount = new Account(500m); |
|||
|
|||
await _accountRepository.InsertAsync(fromAccount); |
|||
await _accountRepository.InsertAsync(toAccount); |
|||
await UnitOfWorkManager.Current.SaveChangesAsync(); |
|||
|
|||
// Act |
|||
await _transferManager.TransferAsync(fromAccount, toAccount, 200m); |
|||
await UnitOfWorkManager.Current.SaveChangesAsync(); |
|||
|
|||
// Assert |
|||
var updatedFrom = await _accountRepository.GetAsync(fromAccount.Id); |
|||
var updatedTo = await _accountRepository.GetAsync(toAccount.Id); |
|||
|
|||
updatedFrom.Balance.ShouldBe(800m); |
|||
updatedTo.Balance.ShouldBe(700m); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## When NOT to Use a Domain Service |
|||
|
|||
Not every operation needs a domain service. Avoid over-engineering: |
|||
|
|||
1. **Simple CRUD Operations**: Use Application Services directly |
|||
2. **Single Aggregate Operations**: Use Entity methods |
|||
3. **Infrastructure Concerns**: Use Infrastructure Services |
|||
4. **Application Workflow**: Use Application Services |
|||
|
|||
```csharp |
|||
// Don't create a domain service for this ❌ |
|||
public class AccountBalanceReader : DomainService |
|||
{ |
|||
public decimal GetBalance(Account account) => account.Balance; |
|||
} |
|||
|
|||
// Just use the property directly ✅ |
|||
var balance = account.Balance; |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Summary |
|||
- **Domain Services** are domain-level, not application-level |
|||
- They encapsulate **business logic that doesn't belong to a single entity** |
|||
- They keep your **entities clean** and **business logic consistent** |
|||
- In ABP, inherit from `DomainService` to get built-in features |
|||
- Keep them **focused**, **pure**, and **testable** |
|||
|
|||
--- |
|||
|
|||
## Final Thoughts |
|||
|
|||
Next time you're writing a business rule that doesn't clearly belong to an entity, ask yourself: |
|||
|
|||
> "Is this a Domain Service?" |
|||
|
|||
If it's pure domain logic that coordinates multiple entities or implements a business rule, **put it in the domain layer** - your future self (and your team) will thank you. |
|||
|
|||
Domain Services are a powerful tool in your DDD toolkit. Use them wisely to keep your domain model clean, expressive, and maintainable. |
|||
|
|||
--- |
|||
@ -0,0 +1 @@ |
|||
Learn what Domain Services are in Domain-Driven Design and when to use them in .NET projects. This practical guide covers the difference between Domain and Application Services, features real-world examples including money transfers and order processing, and shows how ABP Framework's DomainService base class simplifies implementation with built-in localization, logging, and event publishing. |
|||
@ -0,0 +1,156 @@ |
|||
# Announcing Server-Side Rendering (SSR) Support for ABP Framework Angular Applications |
|||
|
|||
We are pleased to announce that **Server-Side Rendering (SSR)** has become available for ABP Framework Angular applications! This highly requested feature brings major gains in performance, SEO, and user experience to your Angular applications based on ABP Framework. |
|||
|
|||
## What is Server-Side Rendering (SSR)? |
|||
|
|||
Server-Side Rendering refers to an approach which renders your Angular application on the server as opposed to the browser. The server creates the complete HTML for a page and sends it to the client, which can then show the page to the user. This poses many advantages over traditional client-side rendering. |
|||
|
|||
## Why SSR Matters for ABP Angular Applications |
|||
|
|||
### Improved Performance |
|||
- **Quicker visualization of the first contentful paint (FCP)**: Because prerendered HTML is sent over from the server, users will see content quicker. |
|||
- **Better perceived performance**: Even on slower devices, the page will be displaying something sooner. |
|||
- **Less JavaScript parsing time**: For example, the initial page load will not require parsing and executing a large bundle of JavaScript. |
|||
|
|||
### Enhanced SEO |
|||
- **Improved indexing by search engines**: Search engine bots are able to crawl and index your content quicker. |
|||
- **Improved rankings in search**: The quicker the content loads and the easier it is to access, the better your SEO score. |
|||
- **Preview when sharing on social channels**: Rich previews with the appropriate meta tags are generated when sharing links on social platforms. |
|||
|
|||
### Better User Experience |
|||
- **Support for low bandwidth**: Users with slower Internet connections will have a better experience |
|||
- **Progressive enhancement**: Users can start accessing the content before JavaScript has loaded |
|||
- **Better accessibility**: Screen readers and other assistive technologies can access the content immediately |
|||
|
|||
## Getting Started with SSR |
|||
|
|||
### Adding SSR to an Existing Project |
|||
|
|||
You can easily add SSR support to your existing ABP Angular application using the Angular CLI with ABP schematics: |
|||
|
|||
```bash |
|||
# Generate SSR configuration for your project |
|||
ng generate @abp/ng.schematics:ssr-add |
|||
|
|||
# Or using the short form |
|||
ng g @abp/ng.schematics:ssr-add |
|||
``` |
|||
|
|||
If you have multiple projects in your workspace, you can specify which project to add SSR to: |
|||
|
|||
```bash |
|||
ng g @abp/ng.schematics:ssr-add --project=my-project |
|||
``` |
|||
|
|||
If you want to skip the automatic installation of dependencies: |
|||
|
|||
```bash |
|||
ng g @abp/ng.schematics:ssr-add --skip-install |
|||
``` |
|||
|
|||
## What Gets Configured |
|||
|
|||
When you add SSR to your ABP Angular project, the schematic automatically: |
|||
|
|||
1. **Installs necessary dependencies**: Adds `@angular/ssr` and related packages |
|||
2. **Creates Server Configuration**: Creates `server.ts` and related files |
|||
3. **Updates Project Structure**: |
|||
- Creates `main.server.ts` to bootstrap the server |
|||
- Adds `app.config.server.ts` for standalone apps (or `app.module.server.ts` for NgModule apps) |
|||
- Configures server routes in `app.routes.server.ts` |
|||
4. **Updates Build Configuration**: updates `angular.json` to include: |
|||
- a `serve-ssr` target for local SSR development |
|||
- a `prerender` target for static site generation |
|||
- Proper output paths for browser and server bundles |
|||
|
|||
## Supported Configurations |
|||
|
|||
The ABP SSR schematic supports both modern and legacy Angular build configurations: |
|||
|
|||
### Application Builder (Suggested) |
|||
- The new `@angular-devkit/build-angular:application` builder |
|||
- Optimized for Angular 17+ apps |
|||
- Enhanced performance and smaller bundle sizes |
|||
|
|||
### Server Builder (Legacy) |
|||
- The original `@angular-devkit/build-angular:server` builder |
|||
- Designed for legacy Angular applications |
|||
- Compatible with legacy applications |
|||
|
|||
## Running Your SSR Application |
|||
|
|||
After adding SSR to your project, you can run your application in SSR mode: |
|||
|
|||
```bash |
|||
# Development mode with SSR |
|||
ng serve |
|||
|
|||
# Or specifically target SSR development server |
|||
npm run serve:ssr |
|||
|
|||
# Build for production |
|||
npm run build:ssr |
|||
|
|||
# Preview production build |
|||
npm run serve:ssr:production |
|||
``` |
|||
|
|||
## Important Considerations |
|||
|
|||
### Browser-Only APIs |
|||
Some browser APIs are not available on the server. Use platform checks to conditionally execute code: |
|||
|
|||
```typescript |
|||
import { isPlatformBrowser } from '@angular/common'; |
|||
import { PLATFORM_ID, inject } from '@angular/core'; |
|||
|
|||
export class MyComponent { |
|||
private platformId = inject(PLATFORM_ID); |
|||
|
|||
ngOnInit() { |
|||
if (isPlatformBrowser(this.platformId)) { |
|||
// Code that uses browser-only APIs |
|||
console.log('Running in browser'); |
|||
localStorage.setItem('key', 'value'); |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Storage APIs |
|||
`localStorage` and `sessionStorage` are not accessible on the server. Consider using: |
|||
- Cookies for server-accessible data. |
|||
- The state transfer API for hydration. |
|||
- ABP's built-in storage abstractions. |
|||
|
|||
### Third-Party Libraries |
|||
Please ensure that any third-party libraries you use are compatible with SSR. These libraries can require: |
|||
- Dynamic imports for browser-only code. |
|||
- Platform-specific service providers. |
|||
- Custom Angular Universal integration. |
|||
|
|||
## ABP Framework Integration |
|||
|
|||
The SSR implementation is natively integrated with all of the ABP Framework features: |
|||
|
|||
- **Authentication & Authorization**: The OAuth/OpenID Connect flow functions seamlessly with ABP |
|||
- **Multi-tenancy**: Fully supports tenant resolution and switching |
|||
- **Localization**: Server-side rendering respects the locale |
|||
- **Permission Management**: Permission checks work on both server and client |
|||
- **Configuration**: The ABP configuration system is SSR-ready |
|||
## Performance Tips |
|||
|
|||
1. **Utilize State Transfer**: Send data from server to client to eliminate redundant HTTP requests |
|||
2. **Optimize Images**: Proper image loading strategies, such as lazy loading and responsive images. |
|||
3. **Cache API Responses**: At the server, implement proper caching strategies. |
|||
4. **Monitor Bundle Size**: Keep your server bundle optimized |
|||
5. **Use Prerendering**: The prerender target should be used for static content. |
|||
|
|||
## Conclusion |
|||
|
|||
Server-side rendering can be a very effective feature in improving your ABP Angular application's performance, SEO, and user experience. Our new SSR schematic will make it easier than ever to add SSR to your project. |
|||
|
|||
Try it today and let us know what you think! |
|||
|
|||
--- |
|||
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 4.6 KiB |
@ -0,0 +1,354 @@ |
|||
# Building an API Key Management System with ABP Framework |
|||
|
|||
API keys are one of the most common authentication methods for APIs, especially for machine-to-machine communication. In this article, I'll explain what API key authentication is, when to use it, and how to implement a complete API key management system using ABP Framework. |
|||
|
|||
## What is API Key Authentication? |
|||
|
|||
An API key is a unique identifier used to authenticate requests to an API. Unlike user credentials (username/password) or OAuth tokens, API keys are designed for: |
|||
|
|||
- **Programmatic access** - Scripts, CLI tools, and automated processes |
|||
- **Service-to-service communication** - Microservices authenticating with each other |
|||
- **Third-party integrations** - External systems accessing your API |
|||
- **IoT devices** - Embedded systems with limited authentication capabilities |
|||
- **Mobile/Desktop apps** - Native applications that need persistent authentication |
|||
|
|||
## Why Use API Keys? |
|||
|
|||
While modern authentication methods like OAuth2 and JWT are excellent for user authentication, API keys offer distinct advantages in certain scenarios: |
|||
|
|||
**Simplicity**: No complex OAuth flows or token refresh mechanisms. Just include the key in your request header. |
|||
|
|||
**Long-lived**: Unlike JWT tokens that expire in minutes/hours, API keys can remain valid for months or years, making them ideal for automated systems. |
|||
|
|||
**Revocable**: You can instantly revoke a compromised key without affecting user credentials. |
|||
|
|||
**Granular Control**: Different keys for different purposes (read-only, admin, specific services). |
|||
|
|||
## Real-World Use Cases |
|||
|
|||
Here are some practical scenarios where API key authentication shines: |
|||
|
|||
### 1. Mobile Applications |
|||
Your mobile app needs to call your backend APIs. Instead of storing user credentials or managing token refresh flows, use an API key. |
|||
|
|||
```csharp |
|||
// Mobile app configuration |
|||
var apiClient = new ApiClient("https://api.yourapp.com"); |
|||
apiClient.SetApiKey("sk_mobile_prod_abc123..."); |
|||
``` |
|||
|
|||
### 2. Microservice Communication |
|||
Service A needs to call Service B's protected endpoints. |
|||
|
|||
```csharp |
|||
// Order Service calling Inventory Service |
|||
var request = new HttpRequestMessage(HttpMethod.Get, "https://inventory-service/api/products"); |
|||
request.Headers.Add("X-Api-Key", _configuration["InventoryService:ApiKey"]); |
|||
``` |
|||
|
|||
### 3. Third-Party Integrations |
|||
You're providing APIs to external partners or customers. |
|||
|
|||
```bash |
|||
# Customer's integration script |
|||
curl -H "X-Api-Key: pk_partner_xyz789..." \ |
|||
https://api.yourplatform.com/api/orders |
|||
``` |
|||
|
|||
## Implementing API Key Management in ABP Framework |
|||
|
|||
Now let's see how to build a complete API key management system using ABP Framework. I've created an open-source implementation that you can use in your projects. |
|||
|
|||
### Project Overview |
|||
|
|||
The implementation consists of: |
|||
|
|||
- **User-based API keys** - Each key belongs to a specific user |
|||
- **Permission delegation** - Keys inherit user permissions with optional restrictions |
|||
- **Secure storage** - Keys are hashed with SHA-256 |
|||
- **Prefix-based lookup** - Fast key resolution with caching |
|||
- **Web UI** - Manage keys through a user-friendly interface |
|||
- **Multi-tenancy support** - Full ABP multi-tenancy compatibility |
|||
|
|||
 |
|||
|
|||
### Architecture Overview |
|||
|
|||
The solution follows ABP's modular architecture with four main layers: |
|||
|
|||
``` |
|||
┌─────────────────────────────────────────────┐ |
|||
│ Web Layer (UI) │ |
|||
│ • Razor Pages for CRUD operations │ |
|||
│ • JavaScript for client interactions │ |
|||
└─────────────────────────────────────────────┘ |
|||
↓ |
|||
┌─────────────────────────────────────────────┐ |
|||
│ AspNetCore Layer (Middleware) │ |
|||
│ • Authentication Handler │ |
|||
│ • API Key Resolver (Header/Query) │ |
|||
└─────────────────────────────────────────────┘ |
|||
↓ |
|||
┌─────────────────────────────────────────────┐ |
|||
│ Application Layer (Business Logic) │ |
|||
│ • ApiKeyAppService (CRUD operations) │ |
|||
│ • DTO mappings and validations │ |
|||
└─────────────────────────────────────────────┘ |
|||
↓ |
|||
┌─────────────────────────────────────────────┐ |
|||
│ Domain Layer (Core Business) │ |
|||
│ • ApiKey Entity & Manager │ |
|||
│ • IApiKeyRepository │ |
|||
│ • Domain services & events │ |
|||
└─────────────────────────────────────────────┘ |
|||
``` |
|||
|
|||
### Key Components |
|||
|
|||
#### 1. Domain Layer - The Core Entity |
|||
|
|||
```csharp |
|||
public class ApiKey : FullAuditedAggregateRoot<Guid>, IMultiTenant |
|||
{ |
|||
public virtual Guid? TenantId { get; protected set; } |
|||
public virtual Guid UserId { get; protected set; } |
|||
public virtual string Name { get; protected set; } |
|||
public virtual string Prefix { get; protected set; } |
|||
public virtual string KeyHash { get; protected set; } |
|||
public virtual DateTime? ExpiresAt { get; protected set; } |
|||
public virtual bool IsActive { get; protected set; } |
|||
|
|||
// Key format: {prefix}_{key} |
|||
// Only the hash is stored, never the actual key |
|||
} |
|||
``` |
|||
|
|||
**Key Design Decisions:** |
|||
|
|||
- **Prefix-based lookup**: Keys have format `prefix_actualkey`. The prefix is indexed for fast database lookups. |
|||
- **SHA-256 hashing**: The actual key is hashed and never stored in plain text. |
|||
- **User association**: Each key belongs to a user, inheriting their permissions. |
|||
- **Soft delete**: Deleted keys are marked as deleted but not removed from database for audit purposes. |
|||
|
|||
#### 2. Authentication Flow |
|||
|
|||
Here's how authentication works when a request arrives: |
|||
|
|||
 |
|||
|
|||
```csharp |
|||
// 1. Extract API key from request |
|||
var apiKey = httpContext.Request.Headers["X-Api-Key"].FirstOrDefault(); |
|||
if (string.IsNullOrEmpty(apiKey)) return AuthenticateResult.NoResult(); |
|||
|
|||
// 2. Split prefix and key |
|||
var parts = apiKey.Split('_', 2); |
|||
var prefix = parts[0]; |
|||
var key = parts[1]; |
|||
|
|||
// 3. Find key by prefix (cached) |
|||
var apiKeyEntity = await _apiKeyRepository.FindByPrefixAsync(prefix); |
|||
if (apiKeyEntity == null) return AuthenticateResult.Fail("Invalid API key"); |
|||
|
|||
// 4. Verify hash |
|||
var keyHash = HashHelper.ComputeSha256(key); |
|||
if (apiKeyEntity.KeyHash != keyHash) |
|||
return AuthenticateResult.Fail("Invalid API key"); |
|||
|
|||
// 5. Check expiration and active status |
|||
if (apiKeyEntity.ExpiresAt < DateTime.UtcNow || !apiKeyEntity.IsActive) |
|||
return AuthenticateResult.Fail("API key expired or inactive"); |
|||
|
|||
// 6. Create claims principal with user identity |
|||
var claims = new List<Claim> |
|||
{ |
|||
new Claim(AbpClaimTypes.UserId, apiKeyEntity.UserId.ToString()), |
|||
new Claim(AbpClaimTypes.TenantId, apiKeyEntity.TenantId?.ToString() ?? ""), |
|||
new Claim("ApiKeyId", apiKeyEntity.Id.ToString()) |
|||
}; |
|||
|
|||
return AuthenticateResult.Success(ticket); |
|||
``` |
|||
|
|||
#### 3. Creating and Managing API Keys |
|||
|
|||
**Creating a new key:** |
|||
|
|||
 |
|||
|
|||
```csharp |
|||
public class ApiKeyManager : DomainService |
|||
{ |
|||
public async Task<(ApiKey, string)> CreateAsync( |
|||
Guid userId, |
|||
string name, |
|||
DateTime? expiresAt = null) |
|||
{ |
|||
// Generate unique prefix |
|||
var prefix = await GenerateUniquePrefixAsync(); |
|||
|
|||
// Generate secure random key |
|||
var key = GenerateSecureRandomString(32); |
|||
|
|||
// Hash the key for storage |
|||
var keyHash = HashHelper.ComputeSha256(key); |
|||
|
|||
var apiKey = new ApiKey( |
|||
GuidGenerator.Create(), |
|||
userId, |
|||
name, |
|||
prefix, |
|||
keyHash, |
|||
expiresAt, |
|||
CurrentTenant.Id |
|||
); |
|||
|
|||
await _apiKeyRepository.InsertAsync(apiKey); |
|||
|
|||
// Return both entity and the full key (prefix_key) |
|||
// This is the ONLY time the actual key is visible |
|||
return (apiKey, $"{prefix}_{key}"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**Important**: The actual key is returned only once during creation. After that, only the hash is stored. |
|||
|
|||
 |
|||
|
|||
### Using API Keys in Your Application |
|||
|
|||
Once created, clients can use the API key to authenticate: |
|||
|
|||
**HTTP Header (Recommended):** |
|||
```bash |
|||
curl -H "X-Api-Key: sk_prod_abc123def456..." \ |
|||
https://api.example.com/api/products |
|||
``` |
|||
|
|||
**JavaScript:** |
|||
```javascript |
|||
const response = await fetch('https://api.example.com/api/products', { |
|||
headers: { |
|||
'X-Api-Key': 'sk_prod_abc123def456...' |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
**C# HttpClient:** |
|||
```csharp |
|||
var client = new HttpClient(); |
|||
client.DefaultRequestHeaders.Add("X-Api-Key", "sk_prod_abc123def456..."); |
|||
var response = await client.GetAsync("https://api.example.com/api/products"); |
|||
``` |
|||
|
|||
**Python:** |
|||
```python |
|||
import requests |
|||
|
|||
headers = {'X-Api-Key': 'sk_prod_abc123def456...'} |
|||
response = requests.get('https://api.example.com/api/products', headers=headers) |
|||
``` |
|||
|
|||
### Permission Management |
|||
|
|||
API keys inherit the user's permissions, but you can further restrict them: |
|||
|
|||
 |
|||
|
|||
This allows scenarios like: |
|||
- Read-only API key for reporting tools |
|||
- Limited scope keys for third-party integrations |
|||
- Service-specific keys with minimal permissions |
|||
|
|||
```csharp |
|||
// Check if current request is authenticated via API key |
|||
if (CurrentUser.FindClaim("ApiKeyId") != null) |
|||
{ |
|||
var apiKeyId = CurrentUser.FindClaim("ApiKeyId").Value; |
|||
// Additional API key specific logic |
|||
} |
|||
``` |
|||
|
|||
## Performance Considerations |
|||
|
|||
The implementation uses several optimizations: |
|||
|
|||
**1. Prefix-based indexing**: Database lookups are done by prefix (indexed column), not the full key hash. |
|||
|
|||
**2. Distributed caching**: API keys are cached after first lookup, dramatically reducing database queries. |
|||
|
|||
```csharp |
|||
// Cache configuration |
|||
Configure<AbpDistributedCacheOptions>(options => |
|||
{ |
|||
options.KeyPrefix = "ApiKey:"; |
|||
}); |
|||
``` |
|||
|
|||
**3. Cache invalidation**: When a key is modified or deleted, cache is automatically invalidated. |
|||
|
|||
**Typical Performance:** |
|||
- Cached lookup: **< 5ms** |
|||
- Database lookup: **< 50ms** |
|||
- Cache hit rate: **~95%** |
|||
|
|||
## Security Best Practices |
|||
|
|||
When implementing API key authentication, follow these guidelines: |
|||
|
|||
✅ **Always use HTTPS** - Never send API keys over unencrypted connections |
|||
|
|||
✅ **Use different keys per environment** - Separate keys for dev, staging, production |
|||
|
|||
❌ **Don't log the full key** - Only log the prefix for debugging |
|||
|
|||
## Getting Started |
|||
|
|||
The complete source code is available on GitHub: |
|||
|
|||
**Repository**: [github.com/salihozkara/AbpApikeyManagement](https://github.com/salihozkara/AbpApikeyManagement) |
|||
|
|||
To integrate it into your ABP project: |
|||
|
|||
1. Clone or download the repository |
|||
2. Add project references to your solution |
|||
3. Add module dependencies to your modules |
|||
4. Run EF Core migrations to create the database tables |
|||
5. Navigate to `/ApiKeyManagement` to start managing keys |
|||
|
|||
```csharp |
|||
// In your Web module |
|||
[DependsOn(typeof(ApiKeyManagementWebModule))] |
|||
public class YourWebModule : AbpModule |
|||
{ |
|||
// ... |
|||
} |
|||
|
|||
// In your HttpApi.Host module |
|||
[DependsOn(typeof(ApiKeyManagementHttpApiModule))] |
|||
public class YourHttpApiHostModule : AbpModule |
|||
{ |
|||
// ... |
|||
} |
|||
``` |
|||
|
|||
## Conclusion |
|||
|
|||
API key authentication remains a crucial part of modern API security, especially for machine-to-machine communication. While it shouldn't replace user authentication methods like OAuth2 for user-facing applications, it's perfect for: |
|||
|
|||
- Automated scripts and tools |
|||
- Service-to-service communication |
|||
- Third-party integrations |
|||
- Long-lived access without token refresh complexity |
|||
|
|||
The implementation shown here demonstrates how ABP Framework's modular architecture, DDD principles, and built-in features (multi-tenancy, caching, permissions) can be leveraged to build a production-ready API key management system. |
|||
|
|||
The solution is open-source and ready to be integrated into your ABP projects. Feel free to explore the code, suggest improvements, or adapt it to your specific needs. |
|||
|
|||
**Resources:** |
|||
- GitHub Repository: [salihozkara/AbpApikeyManagement](https://github.com/salihozkara/AbpApikeyManagement) |
|||
- ABP Framework: [abp.io](https://abp.io) |
|||
- ABP Documentation: [docs.abp.io](https://abp.io/docs/latest) |
|||
|
|||
Happy coding! 🚀 |
|||
@ -0,0 +1 @@ |
|||
Learn how to implement API key authentication in ABP Framework applications. This comprehensive guide covers what API keys are, when to use them over OAuth2/JWT, real-world use cases for mobile apps and microservices, and a complete implementation with user-based key management, SHA-256 hashing, permission delegation, and built-in UI. |
|||
|
After Width: | Height: | Size: 752 KiB |
@ -0,0 +1,322 @@ |
|||
# Signal-Based Forms in Angular 21: Why You’ll Never Miss Reactive Forms Again |
|||
|
|||
Angular 21 introduces one of the most exciting developments in the modern edition of Angular: **Signal-Based Forms**. Built directly on the reactive foundation of Angular signals, this new experimental API provides a cleaner, more intuitive, strongly typed, and ergonomic approach for managing form state—without the heavy boilerplate of Reactive Forms. |
|||
|
|||
> ⚠️ **Important:** Signal Forms are *experimental*. |
|||
> Their API can change. Avoid using them in critical production scenarios unless you understand the risks. |
|||
|
|||
Despite this, Signal Forms clearly represent Angular’s future direction. |
|||
--- |
|||
|
|||
## Why Signal Forms? |
|||
|
|||
Traditionally in Angular, building forms has involved several concerns: |
|||
|
|||
- Tracking values |
|||
- Managing UI interaction states (touched, dirty) |
|||
- Handling validation |
|||
- Keeping UI and model in sync |
|||
|
|||
Reactive Forms solved many challenges but introduced their own: |
|||
|
|||
- Verbosity FormBuilder API |
|||
- Required subscriptions (valueChanges) |
|||
- Manual cleaning |
|||
- Difficult nested forms |
|||
- Weak type-safety |
|||
|
|||
**Signal Forms solve these problems through:** |
|||
|
|||
1." Automatic synchronization |
|||
2." Full type safety |
|||
3." Schema-based validation |
|||
4." Fine-grained reactivity |
|||
5." Drastically reduced boilerplate |
|||
6." Natural integration with Angular Signals |
|||
|
|||
--- |
|||
|
|||
### 1. Form Models — The Core of Signal Forms |
|||
|
|||
A **form model** is simply a writable signal holding the structure of your form data. |
|||
|
|||
```ts |
|||
import { Component, signal } from '@angular/core'; |
|||
import { form, Field } from '@angular/forms/signals'; |
|||
|
|||
@Component({ |
|||
selector: 'app-login', |
|||
imports: [Field], |
|||
template: ` |
|||
<input type="email" [field]="loginForm.email" /> |
|||
<input type="password" [field]="loginForm.password" /> |
|||
`, |
|||
}) |
|||
export class LoginComponent { |
|||
loginModel = signal({ |
|||
email: '', |
|||
password: '', |
|||
}); |
|||
|
|||
loginForm = form(this.loginModel); |
|||
} |
|||
``` |
|||
|
|||
Calling `form(model)` creates a **Field Tree** that maps directly to your model. |
|||
|
|||
--- |
|||
|
|||
### 2. Achieving Full Type Safety |
|||
|
|||
Although TypeScript can infer types from object literals, defining explicit interfaces provides maximum safety and better IDE support. |
|||
|
|||
```ts |
|||
interface LoginData { |
|||
email: string; |
|||
password: string; |
|||
} |
|||
|
|||
loginModel = signal<LoginData>({ |
|||
email: '', |
|||
password: '', |
|||
}); |
|||
|
|||
loginForm = form(loginModel); |
|||
``` |
|||
|
|||
Now: |
|||
|
|||
- `loginForm.email` → `FieldTree<string>` |
|||
- Accessing invalid fields like `loginForm.username` results in compile-time errors |
|||
|
|||
This level of type safety surpasses Reactive Forms. |
|||
|
|||
--- |
|||
|
|||
### 3. Reading Form Values |
|||
|
|||
#### Read from the model (entire form): |
|||
|
|||
```ts |
|||
onSubmit() { |
|||
const data = this.loginModel(); |
|||
console.log(data.email, data.password); |
|||
} |
|||
``` |
|||
|
|||
#### Read from an individual field: |
|||
|
|||
```html |
|||
<p>Current email: {{ loginForm.email().value() }}</p> |
|||
``` |
|||
|
|||
Each field exposes: |
|||
|
|||
- `value()` |
|||
- `valid()` |
|||
- `errors()` |
|||
- `dirty()` |
|||
- `touched()` |
|||
|
|||
All as signals. |
|||
|
|||
--- |
|||
|
|||
### 4. Updating Form Models Programmatically |
|||
|
|||
Signal Forms allow three update methods. |
|||
|
|||
#### 1. Replace the entire model |
|||
|
|||
```ts |
|||
this.userModel.set({ |
|||
name: 'Alice', |
|||
email: 'alice@example.com', |
|||
}); |
|||
``` |
|||
|
|||
#### 2. Patch specific fields |
|||
|
|||
```ts |
|||
this.userModel.update(prev => ({ |
|||
...prev, |
|||
email: newEmail, |
|||
})); |
|||
``` |
|||
|
|||
#### 3. Update a single field |
|||
|
|||
```ts |
|||
this.userForm.email().value.set(''); |
|||
``` |
|||
|
|||
This eliminates the need for: |
|||
|
|||
- `patchValue()` |
|||
- `setValue()` |
|||
- `formGroup.get('field')` |
|||
|
|||
--- |
|||
|
|||
### 5. Automatic Two-Way Binding With `[field]` |
|||
|
|||
The `[field]` directive enables perfect two-way data binding: |
|||
|
|||
```html |
|||
<input [field]="userForm.name" /> |
|||
``` |
|||
|
|||
#### How it works: |
|||
|
|||
- **User input → Field state → Model** |
|||
- **Model updates → Field state → Input UI** |
|||
|
|||
No subscriptions. |
|||
No event handlers. |
|||
No boilerplate. |
|||
|
|||
Reactive Forms could never achieve this cleanly. |
|||
|
|||
--- |
|||
|
|||
### 6. Nested Models and Arrays |
|||
|
|||
Models can contain nested object structures: |
|||
|
|||
```ts |
|||
userModel = signal({ |
|||
name: '', |
|||
address: { |
|||
street: '', |
|||
city: '', |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
Access fields easily: |
|||
|
|||
```html |
|||
<input [field]="userForm.address.street" /> |
|||
``` |
|||
|
|||
Arrays are also supported: |
|||
|
|||
```ts |
|||
orderModel = signal({ |
|||
items: [ |
|||
{ product: '', quantity: 1, price: 0 } |
|||
] |
|||
}); |
|||
``` |
|||
|
|||
Field state persists even when array items move, thanks to identity tracking. |
|||
|
|||
--- |
|||
|
|||
### 7. Schema-Based Validation |
|||
|
|||
Validation is clean and centralized: |
|||
|
|||
```ts |
|||
import { required, email } from '@angular/forms/signals'; |
|||
|
|||
const model = signal({ email: '' }); |
|||
|
|||
const formRef = form(model, { |
|||
email: [required(), email()], |
|||
}); |
|||
``` |
|||
|
|||
Field validation state is reactive: |
|||
|
|||
```ts |
|||
formRef.email().valid() |
|||
formRef.email().errors() |
|||
formRef.email().touched() |
|||
``` |
|||
|
|||
Validation no longer scatters across components. |
|||
|
|||
--- |
|||
|
|||
### 8. When Should You Use Signal Forms? |
|||
|
|||
#### New Angular 21+ apps |
|||
Signal-first architecture is the new standard. |
|||
|
|||
#### Teams wanting stronger type safety |
|||
Every field is exactly typed. |
|||
|
|||
#### Devs tired of Reactive Form boilerplate |
|||
Signal Forms drastically simplify code. |
|||
|
|||
#### Complex UI with computed reactive form state |
|||
Signals integrate perfectly. |
|||
|
|||
#### ❌ Avoid if: |
|||
- You need long-term stability |
|||
- You rely on mature Reactive Forms features |
|||
- Your app must avoid experimental APIs |
|||
|
|||
--- |
|||
|
|||
### 9. Reactive Forms vs Signal Forms |
|||
|
|||
| Feature | Reactive Forms | Signal Forms | |
|||
|--------|----------------|--------------| |
|||
| Boilerplate | High | Very low | |
|||
| Type-safety | Weak | Strong | |
|||
| Two-way binding | Manual | Automatic | |
|||
| Validation | Scattered | Centralized schema | |
|||
| Nested forms | Verbose | Natural | |
|||
| Subscriptions | Required | None | |
|||
| Change detection | Zone-heavy | Fine-grained | |
|||
|
|||
Signal Forms feel like the "modern Angular mode," while Reactive Forms increasingly feel legacy. |
|||
|
|||
--- |
|||
|
|||
### 10. Full Example: Login Form |
|||
|
|||
```ts |
|||
@Component({ |
|||
selector: 'app-login', |
|||
imports: [Field], |
|||
template: ` |
|||
<form (ngSubmit)="submit()"> |
|||
<input type="email" [field]="form.email" /> |
|||
<input type="password" [field]="form.password" /> |
|||
<button>Login</button> |
|||
</form> |
|||
`, |
|||
}) |
|||
export class LoginComponent { |
|||
model = signal({ email: '', password: '' }); |
|||
form = form(this.model); |
|||
|
|||
submit() { |
|||
console.log(this.model()); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Minimal. Reactive. Completely type-safe. |
|||
|
|||
--- |
|||
|
|||
## **Conclusion** |
|||
|
|||
Signal Forms in Angular 21 represent a big step forward: |
|||
|
|||
- Cleaner API |
|||
- Stronger type safety |
|||
- Automatic two-way binding |
|||
- Centralized validation |
|||
- Fine-grained reactivity |
|||
- Dramatically better developer experience |
|||
|
|||
|
|||
Although these are experimental, they clearly show the future of Angular's form ecosystem. |
|||
Once you get into using Signal Forms, you may never want to use Reactive Forms again. |
|||
|
|||
--- |
|||
@ -0,0 +1,25 @@ |
|||
**ABP Black Friday Deals are Almost Here\!** |
|||
|
|||
The season of huge savings is back\! We are happy to announce **ABP Black Friday Campaign**, packed with exclusive deals that you simply won't want to miss. Whether you are ready to start building with ABP or looking to expand your existing license, this is your chance to maximize your savings\! |
|||
|
|||
**Campaign Dates: Mark Your Calendar** |
|||
|
|||
Black Friday campaign is live for one week only\! Our deals run from: **November 24th \- December 1st.** |
|||
|
|||
Don't miss this limited-time opportunity to **save up to $3,000** and take your software development to the next level. |
|||
|
|||
**What's Included in the ABP Black Friday Campaign?** |
|||
|
|||
Here’s why this campaign is the best time to buy or upgrade: |
|||
|
|||
* Open to Everyone: This campaign is available for both new and existing customers. |
|||
* Stack Your Savings: You can combine this Black Friday offer with our multi-year discounts for the greatest possible value. |
|||
* Flexible Upgrades: Planning to upgrade to a higher package? Now is the perfect time to make that move at a lower cost. |
|||
* More Developer Seats? No Problem\! Additional developer seats are also eligible under this campaign, allowing you to grow your team effortlessly and affordably. |
|||
|
|||
**Save Money Now\!** |
|||
|
|||
This campaign is your best opportunity all year to unlock advanced features, scale your team, or upgrade your plan while **saving up to $3,000.** Secure your savings before the campaign ends on December 1st\! |
|||
|
|||
[**Visit Pricing Page to Explore Offers\!**](https://abp.io/pricing) |
|||
|
|||
@ -0,0 +1,149 @@ |
|||
# What’s New in .NET 10 Libraries and Runtime? |
|||
|
|||
With .NET 10, Microsoft continues to evolve the platform toward higher performance, stronger security, and modern developer ergonomics. This release brings substantial updates across both the **.NET Libraries** and the **.NET Runtime**, making everyday development faster, safer, and more efficient. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
## .NET Libraries Improvements |
|||
|
|||
### 1. Post-Quantum Cryptography |
|||
|
|||
.NET 10 introduces support for new **quantum-resistant algorithms**, ML-KEM, ML-DSA, and SLH-DSA, through the `System.Security.Cryptography` namespace. |
|||
These are available when running on compatible OS versions (OpenSSL 3.5+ or Windows CNG). |
|||
|
|||
**Why it matters:** This future-proofs .NET apps against next-generation security threats, keeping them aligned with emerging FIPS standards and PQC readiness. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 2. Numeric Ordering for String Comparison |
|||
|
|||
The `StringComparer` and `HashSet` classes now support **numeric-aware string comparison** via `CompareOptions.NumericOrdering`. |
|||
This allows natural sorting of strings like `v2`, `v10`, `v100`. |
|||
|
|||
**Why it matters:** Cleaner and more intuitive sorting for version names, product codes, and other mixed string-number data. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 3. String Normalization for Spans |
|||
|
|||
Normalization APIs now support `Span<char>` and `ReadOnlySpan<char>`, enabling text normalization without creating new string objects. |
|||
|
|||
**Why it matters:** Lower memory allocations in text-heavy scenarios, perfect for parsers, libraries, and streaming data pipelines. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 4. UTF-8 Support for Hex String Conversion |
|||
|
|||
The `Convert` class now allows **direct UTF-8 to hex conversions**, eliminating the need for intermediate string allocations. |
|||
|
|||
**Why it matters:** Faster serialization and deserialization, especially useful in networking, cryptography, and binary protocols. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 5. Async ZIP APIs |
|||
|
|||
ZIP handling now fully supports asynchronous operations, from creation and extraction to updates, with cancellation support. |
|||
|
|||
**Why it matters:** Ideal for real-time applications, WebSocket I/O, and microservices that handle compressed data streams. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 6. ZipArchive Performance Boost |
|||
|
|||
ZIP operations are now faster and more memory-efficient thanks to parallel extraction and reduced memory pressure. |
|||
|
|||
**Why it matters:** Perfect for file-heavy workloads like installers, packaging tools, and CI/CD utilities. |
|||
|
|||
------ |
|||
|
|||
|
|||
|
|||
### 7. TLS 1.3 Support on macOS |
|||
|
|||
.NET 10 brings **TLS 1.3 client support** to macOS using Apple’s `Network.framework`, integrated with `SslStream` and `HttpClient`. |
|||
|
|||
**Why it matters:** Consistent, faster, and more secure HTTPS connections across Windows, Linux, and macOS. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 8. Telemetry Schema URLs |
|||
|
|||
`ActivitySource` and `Meter` now support **telemetry schema URLs**, aligning with OpenTelemetry standards. |
|||
|
|||
**Why it matters:** Simplifies integration with observability platforms like Grafana, Prometheus, and Application Insights. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 9. OrderedDictionary Performance Improvements |
|||
|
|||
New overloads for `TryAdd` and `TryGetValue` improve performance by returning entry indexes directly. |
|||
|
|||
**Why it matters:** Up to 20% faster JSON updates and more efficient dictionary operations, particularly in `JsonObject`. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
## .NET Runtime Improvements |
|||
|
|||
|
|||
|
|||
### 1. JIT Compiler Enhancements |
|||
|
|||
- **Faster Struct Handling:** The JIT now passes structs directly via CPU registers, reducing memory operations. |
|||
*→ Result: Faster execution and tighter loops.* |
|||
|
|||
- **Array Interface Devirtualization:** Loops like `foreach` over arrays are now almost as fast as `for` loops. |
|||
*→ Result: Fewer abstraction costs and better inlining.* |
|||
|
|||
- **Improved Code Layout:** A new 3-opt heuristic arranges “hot” code paths closer in memory. |
|||
*→ Result: Better branch prediction and CPU cache performance.* |
|||
|
|||
- **Smarter Inlining:** The JIT can now inline more method types (even with `try-finally`), guided by runtime profiling. |
|||
*→ Result: Reduced overhead for frequently called methods.* |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 2. Stack Allocation Improvements |
|||
|
|||
.NET 10 extends stack allocation to **small arrays of both value and reference types**, with **escape analysis** ensuring safe allocation. |
|||
|
|||
**Why it matters:** Fewer heap allocations mean less GC work and faster execution, especially in high-frequency or temporary operations. |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
### 3. ARM64 Write-Barrier Optimization |
|||
|
|||
The garbage collector’s write-barrier logic is now optimized for ARM64, cutting unnecessary memory scans. |
|||
|
|||
**Why it matters:** Up to **20% shorter GC pauses** and better overall performance on ARM-based devices and servers. |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Summary |
|||
|
|||
.NET 10 doubles down on **performance, efficiency, and modern standards**. From quantum-ready cryptography to smarter memory management and diagnostics, this release makes .NET more ready than ever for the next generation of applications. |
|||
|
|||
Whether you’re building enterprise APIs, distributed systems, or cloud-native tools, upgrading to .NET 10 means faster code, safer systems, and better developer experience. |
|||
@ -1,3 +0,0 @@ |
|||
# Dynamic Proxying / Interceptors |
|||
|
|||
This document is planned to be written later. |
|||
@ -1,307 +0,0 @@ |
|||
# Artificial Intelligence |
|||
|
|||
ABP provides a simple way to integrate AI capabilities into your applications by unifying two popular .NET AI stacks under a common concept called a "workspace": |
|||
|
|||
- Microsoft.Extensions.AI `IChatClient` |
|||
- Microsoft.SemanticKernel `Kernel` |
|||
|
|||
A workspace is just a named scope. You configure providers per workspace and then resolve either default services (for the "Default" workspace) or workspace-scoped services. |
|||
|
|||
## Installation |
|||
|
|||
> This package is not included by default. Install it to enable AI features. |
|||
|
|||
It is suggested to use the ABP CLI to install the package. Open a command line window in the folder of the project (.csproj file) and type the following command: |
|||
|
|||
```bash |
|||
abp add-package Volo.Abp.AI |
|||
``` |
|||
|
|||
### Manual Installation |
|||
|
|||
Add nuget package to your project: |
|||
|
|||
```bash |
|||
dotnet add package Volo.Abp.AI |
|||
``` |
|||
|
|||
Then add the module dependency to your module class: |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
using Volo.Abp.Modularity; |
|||
|
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
## Usage |
|||
|
|||
### Chat Client |
|||
|
|||
#### Default configuration (quick start) |
|||
|
|||
Configure the default workspace to inject `IChatClient` directly. |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
using Microsoft.SemanticKernel; |
|||
using Volo.Abp.AI; |
|||
using Volo.Abp.Modularity; |
|||
|
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
}); |
|||
|
|||
// Chat client only in this quick start |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Once configured, inject the default chat client: |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
|
|||
public class MyService |
|||
{ |
|||
private readonly IChatClient _chatClient; // default chat client |
|||
|
|||
public MyService(IChatClient chatClient) |
|||
{ |
|||
_chatClient = chatClient; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### Workspace configuration |
|||
|
|||
Workspaces allow multiple, isolated AI configurations. Define workspace types (optionally decorated with `WorkspaceNameAttribute`). If omitted, the type’s full name is used. |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
|
|||
[WorkspaceName("GreetingAssistant")] |
|||
public class GreetingAssistant // ChatClient-only workspace |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
Configure a ChatClient workspace: |
|||
|
|||
```csharp |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<GreetingAssistant>(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
|
|||
chatClientConfiguration.BuilderConfigurers.Add(builder => |
|||
{ |
|||
// Anything you want to do with the builder: |
|||
// builder.UseFunctionInvocation().UseLogging(); // For example |
|||
}); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Semantic Kernel |
|||
|
|||
#### Default configuration |
|||
|
|||
|
|||
```csharp |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddAzureOpenAIChatClient("...", "..."); |
|||
}); |
|||
// Note: Chat client is not configured here |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Once configured, inject the default kernel: |
|||
|
|||
```csharp |
|||
using System.Threading.Tasks; |
|||
using Volo.Abp.AI; |
|||
|
|||
public class MyService |
|||
{ |
|||
private readonly IKernelAccessor _kernelAccessor; |
|||
public MyService(IKernelAccessor kernelAccessor) |
|||
{ |
|||
_kernelAccessor = kernelAccessor; |
|||
} |
|||
|
|||
public async Task DoSomethingAsync() |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; // Kernel might be null if no workspace is configured. |
|||
|
|||
var result = await kernel.InvokeAsync(/*... */); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### Workspace configuration |
|||
|
|||
```csharp |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<ContentPlanner>(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddOpenAIChatCompletion("...", "..."); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### Workspace usage |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
using Volo.Abp.AI; |
|||
using Microsoft.SemanticKernel; |
|||
|
|||
public class PlanningService |
|||
{ |
|||
private readonly IKernelAccessor<ContentPlanner> _kernelAccessor; |
|||
private readonly IChatClient<ContentPlanner> _chatClient; // available even if only Kernel is configured |
|||
|
|||
public PlanningService( |
|||
IKernelAccessor<ContentPlanner> kernelAccessor, |
|||
IChatClient<ContentPlanner> chatClient) |
|||
{ |
|||
_kernelAccessor = kernelAccessor; |
|||
_chatClient = chatClient; |
|||
} |
|||
|
|||
public async Task<string> PlanAsync(string topic) |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; // Microsoft.SemanticKernel.Kernel |
|||
// Use Semantic Kernel APIs if needed... |
|||
|
|||
var response = await _chatClient.GetResponseAsync( |
|||
[new ChatMessage(ChatRole.User, $"Create a content plan for: {topic}")] |
|||
); |
|||
return response?.Message?.Text ?? string.Empty; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Options |
|||
|
|||
`AbpAIOptions` configuration pattern offers `ConfigureChatClient(...)` and `ConfigureKernel(...)` methods for configuration. These methods are defined in the `WorkspaceConfiguration` class. They are used to configure the `ChatClient` and `Kernel` respectively. |
|||
|
|||
`Builder` is set once and is used to build the `ChatClient` or `Kernel` instance. `BuilderConfigurers` is a list of actions that are applied to the `Builder` instance for incremental changes. These actions are executed in the order they are added. |
|||
|
|||
If a workspace configures only the Kernel, a chat client may still be exposed for that workspace through the Kernel’s service provider (when available). |
|||
|
|||
|
|||
## Advanced Usage and Customizations |
|||
|
|||
### Addding Your Own DelegatingChatClient |
|||
|
|||
If you want to build your own decorator, implement a `DelegatingChatClient` derivative and provide an extension method that adds it to the `ChatClientBuilder` using `builder.Use(...)`. |
|||
|
|||
Example sketch: |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
|
|||
public class SystemMessageChatClient : DelegatingChatClient |
|||
{ |
|||
public SystemMessageChatClient(IChatClient inner, string systemMessage) : base(inner) |
|||
{ |
|||
SystemMessage = systemMessage; |
|||
} |
|||
|
|||
public string SystemMessage { get; set; } |
|||
|
|||
public override Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default) |
|||
{ |
|||
// Mutate messages/options as needed, then call base |
|||
return base.GetResponseAsync(messages, options, cancellationToken); |
|||
} |
|||
} |
|||
|
|||
public static class SystemMessageChatClientExtensions |
|||
{ |
|||
public static ChatClientBuilder UseSystemMessage(this ChatClientBuilder builder, string systemMessage) |
|||
{ |
|||
return builder.Use(client => new SystemMessageChatClient(client, systemMessage)); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
|
|||
```cs |
|||
chatClientConfiguration.BuilderConfigurers.Add(builder => |
|||
{ |
|||
builder.UseSystemMessage("You are a helpful assistant that greets users in a friendly manner with their names."); |
|||
}); |
|||
``` |
|||
|
|||
## Technical Anatomy |
|||
|
|||
- `AbpAIModule`: Wires up configured workspaces, registers keyed services and default services for the `"Default"` workspace. |
|||
- `AbpAIOptions`: Holds `Workspaces` and provides helper methods for internal keyed service naming. |
|||
- `WorkspaceConfigurationDictionary` and `WorkspaceConfiguration`: Configure per-workspace Chat Client and Kernel. |
|||
- `ChatClientConfiguration` and `KernelConfiguration`: Hold builders and a list of ordered builder configurers. |
|||
- `WorkspaceNameAttribute`: Names a workspace; falls back to the type’s full name if not specified. |
|||
- `IChatClient<TWorkspace>`: Typed chat client for a workspace. |
|||
- `IKernelAccessor<TWorkspace>`: Provides access to the workspace’s `Kernel` instance if configured. |
|||
- `AbpAIWorkspaceOptions`: Exposes `ConfiguredWorkspaceNames` for diagnostics. |
|||
|
|||
There are no database tables for this feature; it is a pure configuration and DI integration layer. |
|||
|
|||
## See Also |
|||
|
|||
- Microsoft.Extensions.AI (Chat Client) |
|||
- Microsoft Semantic Kernel |
|||
@ -0,0 +1,31 @@ |
|||
# Artificial Intelligence |
|||
ABP Framework provides integration for AI capabilities to your application by using Microsoft's popular AI libraries. The main purpose of this integration is to provide a consistent and easy way to use AI capabilities and manage different AI providers, models and configurations in a single application. |
|||
|
|||
ABP introduces a concept called **AI Workspace**. A workspace allows you to configure isolated AI configurations for a named scope. You can then resolve AI services for a specific workspace when you need to use them. |
|||
|
|||
> ABP Framework can work with any AI library or framework that supports .NET development. However, the AI integration features explained in the following documents provide a modular and standard way to work with AI, which allows ABP developers to create reusable modules and components with AI capabilities in a standard way. |
|||
|
|||
## Installation |
|||
|
|||
Use the [ABP CLI](../../../cli/index.md) to install the [Volo.Abp.AI](https://www.nuget.org/packages/Volo.Abp.AI) NuGet package into your project. Open a command line window in the root directory of your project (`.csproj` file) and type the following command: |
|||
|
|||
```bash |
|||
abp add-package Volo.Abp.AI |
|||
``` |
|||
|
|||
*For different installation options, check [the package definition page](https://abp.io/package-detail/Volo.Abp.AI).* |
|||
|
|||
## Usage |
|||
|
|||
The `Volo.Abp.AI` package provides integration with the following libraries: |
|||
|
|||
* [Microsoft.Extensions.AI](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai) |
|||
* [Microsoft.SemanticKernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) |
|||
|
|||
The Microsoft.Extensions.AI library is suggested for library developers to keep the library dependency minimum and simple (since it provides basic abstractions and fundamental AI provider integrations), while Semantic Kernel is suggested for applications that need rich and advanced AI integration features. |
|||
|
|||
Check the following documentation to learn how to use these libraries with the ABP integration: |
|||
|
|||
- [ABP Microsoft.Extensions.AI integration](./microsoft-extensions-ai.md) |
|||
- [ABP Microsoft.SemanticKernel integration](./microsoft-semantic-kernel.md) |
|||
|
|||
@ -0,0 +1,176 @@ |
|||
# Microsoft.Extensions.AI |
|||
[Microsoft.Extensions.AI](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai) is a library that provides a unified API for integrating AI services. It is a part of the Microsoft AI Extensions Library. It is used to integrate AI services into your application. This documentation is about the usage of this library with ABP Framework. Make sure you have read the [Artificial Intelligence](./index.md) documentation before reading this documentation. |
|||
|
|||
## Usage |
|||
|
|||
You can resolve `IChatClient` to access configured chat client from your service and use it directly. |
|||
|
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClient _chatClient; |
|||
public MyService(IChatClient chatClient) |
|||
{ |
|||
_chatClient = chatClient; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
return await _chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can also resolve `IChatClientAccessor` to access the `IChatClient` optionally configured scenarios such as developing a module or a service that may use AI capabilities **optionally**. |
|||
|
|||
|
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClientAccessor _chatClientAccessor; |
|||
public MyService(IChatClientAccessor chatClientAccessor) |
|||
{ |
|||
_chatClientAccessor = chatClientAccessor; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var chatClient = _chatClientAccessor.ChatClient; |
|||
if (chatClient is null) |
|||
{ |
|||
return "No chat client configured"; |
|||
} |
|||
return await chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Workspaces |
|||
|
|||
Workspaces are a way to configure isolated AI configurations for a named scope. You can define a workspace by decorating a class with the `WorkspaceNameAttribute` attribute that carries the workspace name. |
|||
- Workspace names must be unique. |
|||
- Workspace names cannot contain spaces _(use underscores or camelCase)_. |
|||
- Workspace names are case-sensitive. |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
|
|||
[WorkspaceName("CommentSummarization")] |
|||
public class CommentSummarization |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
> [!NOTE] |
|||
> If you don't specify the workspace name, the full name of the class will be used as the workspace name. |
|||
|
|||
You can resolve generic versions of `IChatClient` and `IChatClientAccessor` services for a specific workspace as generic arguments. If Chat Client is not configured for a workspace, you will get `null` from the accessor services. You should check the accessor before using it. This applies only for specified workspaces. Another workspace may have a configured Chat Client. |
|||
|
|||
`IChatClient<TWorkSpace>` or `IChatClientAccessor<TWorkSpace>` can be resolved to access a specific workspace's chat client. This is a typed chat client and can be configured separately from the default chat client. |
|||
|
|||
|
|||
Example of resolving a typed chat client: |
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClient<CommentSummarization> _chatClient; |
|||
|
|||
public MyService(IChatClient<CommentSummarization> chatClient) |
|||
{ |
|||
_chatClient = chatClient; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
return await _chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Example of resolving a typed chat client accessor: |
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClientAccessor<CommentSummarization> _chatClientAccessor; |
|||
} |
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var chatClient = _chatClientAccessor.ChatClient; |
|||
if (chatClient is null) |
|||
{ |
|||
return "No chat client configured"; |
|||
} |
|||
return await chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Configuration |
|||
|
|||
`AbpAIWorkspaceOptions` configuration is used to configure AI workspaces and their configurations. You can configure the default workspace and also configure isolated workspaces by using the this options class.It has to be configured **before the services are configured** in the `PreConfigure` method of your module class. It is important since the services are registered after the configuration is applied. |
|||
|
|||
- `AbpAIWorkspaceOptions` has a `Workspaces` property that is type of `WorkspaceConfigurationDictionary` which is a dictionary of workspace names and their configurations. It provides `Configure<T>` and `ConfigureDefault` methods to configure the default workspace and also configure isolated workspaces by using the workspace type. |
|||
|
|||
- Configure method passes `WorkspaceConfiguration` object to the configure action. You can configure the `ChatClient` by using the `ConfigureChatClient` method. |
|||
|
|||
- `ConfigureChatClient()` method passes `ChatClientConfiguration` parameter to the configure action. You can configure the `Builder` and `BuilderConfigurers` by using the `ConfigureBuilder` method. |
|||
- `Builder` is set once and is used to build the `ChatClient` instance. |
|||
- `BuilderConfigurers` is a list of actions that are applied to the `Builder` instance for incremental changes.These actions are executed in the order they are added. |
|||
|
|||
To configure a chat client, you'll need a LLM provider package such as [Microsoft.Extensions.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) or [OllamaSharp](https://www.nuget.org/packages/OllamaSharp/) to configure a chat client. |
|||
|
|||
_The following example requires [OllamaSharp](https://www.nuget.org/packages/OllamaSharp/) package to be installed._ |
|||
|
|||
|
|||
Demonstration of the default workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIWorkspaceOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
|
|||
Demonstration of the isolated workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIWorkspaceOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<CommentSummarization>(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
|
|||
## See Also |
|||
|
|||
- [Usage of Semantic Kernel](./microsoft-semantic-kernel.md) |
|||
- [AI Samples for .NET](https://learn.microsoft.com/en-us/samples/dotnet/ai-samples/ai-samples/) |
|||
@ -0,0 +1,135 @@ |
|||
# Microsoft.SemanticKernel |
|||
[Microsoft.SemanticKernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) is a library that provides a unified SDK for integrating AI services. This documentation is about the usage of this library with ABP Framework. Make sure you have read the [Artificial Intelligence](./index.md) documentation before reading this documentation. |
|||
|
|||
## Usage |
|||
|
|||
Semantic Kernel can be used by resolving `IKernelAccessor` service that carries the `Kernel` instance. Kernel might be `null` if no workspace is configured. You should check the kernel before using it. |
|||
|
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IKernelAccessor _kernelAccessor; |
|||
public MyService(IKernelAccessor kernelAccessor) |
|||
{ |
|||
_kernelAccessor = kernelAccessor; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; |
|||
if (kernel is null) |
|||
{ |
|||
return "No kernel configured"; |
|||
} |
|||
return await kernel.InvokeAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Workspaces |
|||
|
|||
Workspaces are a way to configure isolated AI configurations for a named scope. You can define a workspace by decorating a class with the `WorkspaceNameAttribute` attribute that carries the workspace name. |
|||
- Workspace names must be unique. |
|||
- Workspace names cannot contain spaces _(use underscores or camelCase)_. |
|||
- Workspace names are case-sensitive. |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
|
|||
[WorkspaceName("CommentSummarization")] |
|||
public class CommentSummarization |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
> [!NOTE] |
|||
> If you don't specify the workspace name, the full name of the class will be used as the workspace name. |
|||
|
|||
You can resolve generic versions of `IKernelAccessor` service for a specific workspace as generic arguments. If Kernel is not configured for a workspace, you will get `null` from the accessor service. You should check the accessor before using it. This applies only for specified workspaces. Another workspace may have a configured Kernel. |
|||
|
|||
|
|||
`IKernelAccessor<TWorkSpace>` can be resolved to access a specific workspace's kernel. This is a typed kernel accessor and each workspace can have its own kernel configuration. |
|||
|
|||
Example of resolving a typed kernel accessor: |
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IKernelAccessor<CommentSummarization> _kernelAccessor; |
|||
} |
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; |
|||
if (kernel is null) |
|||
{ |
|||
return "No kernel configured"; |
|||
} |
|||
return await kernel.InvokeAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Configuration |
|||
|
|||
`AbpAIWorkspaceOptions` configuration is used to configure AI workspaces and their configurations. You can configure the default workspace and also configure isolated workspaces by using the this options class.It has to be configured **before the services are configured** in the `PreConfigure` method of your module class. It is important since the services are registered after the configuration is applied. |
|||
|
|||
- `AbpAIWorkspaceOptions` has a `Workspaces` property that is type of `WorkspaceConfigurationDictionary` which is a dictionary of workspace names and their configurations. It provides `Configure<T>` and `ConfigureDefault` methods to configure the default workspace and also configure isolated workspaces by using the workspace type. |
|||
|
|||
- Configure method passes `WorkspaceConfiguration` object to the configure action. You can configure the `Kernel` by using the `ConfigureKernel` method. |
|||
|
|||
- `ConfigureKernel()` method passes `KernelConfiguration` parameter to the configure action. You can configure the `Builder` and `BuilderConfigurers` by using the `ConfigureBuilder` method. |
|||
- `Builder` is set once and is used to build the `Kernel` instance. |
|||
- `BuilderConfigurers` is a list of actions that are applied to the `Builder` instance for incremental changes.These actions are executed in the order they are added. |
|||
|
|||
To configure a kernel, you'll need a kernel connector package such as [Microsoft.SemanticKernel.Connectors.OpenAI](Microsoft.SemanticKernel.Connectors.OpenAI) to configure a kernel to use a specific LLM provider. |
|||
|
|||
_The following example requires [Microsoft.SemanticKernel.Connectors.AzureOpenAI](Microsoft.SemanticKernel.Connectors.AzureOpenAI) package to be installed._ |
|||
|
|||
Demonstration of the default workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddAzureOpenAIChatClient("...", "..."); |
|||
}); |
|||
// Note: Chat client is not configured here |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Demonstration of the isolated workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<CommentSummarization>(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddAzureOpenAIChatClient("...", "..."); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## See Also |
|||
|
|||
- [Usage of Microsoft.Extensions.AI](./microsoft-extensions-ai.md) |
|||
- [AI Samples for .NET](https://learn.microsoft.com/en-us/samples/dotnet/ai-samples/ai-samples/) |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue