diff --git a/Directory.Packages.props b/Directory.Packages.props index e4505d2ba3..4dbfba3fa9 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -58,70 +58,70 @@ - - - - - - - - - - + + + + + + + + + + - - - - + + + + - - - + + + - - - - - - - - - - + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + - - - - + + + + @@ -170,17 +170,17 @@ - + - - + + - - - + + + @@ -195,6 +195,6 @@ - + \ No newline at end of file diff --git a/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json b/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json index 61cf14b67c..d3f150be7a 100644 --- a/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json +++ b/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json @@ -785,6 +785,7 @@ "Enum:UiFramework:5": "Blazor Server", "Enum:UiFramework:6": "Blazor WebApp", "Enum:UiFramework:7": "Blazor MAUI", + "Enum:UiFramework:8": "React", "Enum:DatabaseProvider:0": "Unknown", "Enum:DatabaseProvider:1": "None", "Enum:DatabaseProvider:2": "EfCore", diff --git a/common.props b/common.props index d8e0b39c5c..8e25ef7520 100644 --- a/common.props +++ b/common.props @@ -1,8 +1,8 @@ latest - 10.5.0 - 5.5.0 + 10.6.0-preview + 5.6.0-preview $(NoWarn);CS1591;CS0436 https://abp.io/assets/abp_nupkg.png https://abp.io/ diff --git a/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/Post.md b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/Post.md new file mode 100644 index 0000000000..8dcde9d11a --- /dev/null +++ b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/Post.md @@ -0,0 +1,581 @@ +Multi-tenancy sounds simple at first: one application, many customers. In practice, it changes how you design data access, authentication, configuration, monitoring, migrations, and even support workflows. + +If you get it right, you can serve many organizations efficiently from one platform. If you get it wrong, you risk the worst kind of bug in SaaS: one tenant seeing another tenant's data. + +This article explains how to implement multi-tenancy in a practical way, starting from the core patterns and ending with an ABP-based implementation approach. The goal is not just to define multi-tenancy, but to help you choose the right model and avoid the mistakes that usually show up after launch. + +## What multi-tenancy actually means + +A tenant is usually a customer organization, company, school, or business unit using your application. Multi-tenancy means multiple tenants use the same application platform while remaining isolated from each other. + +That isolation can include: + +- Data isolation +- Authentication and authorization boundaries +- Feature differences per tenant +- Performance protection +- Audit and compliance boundaries + +It is useful to separate two ideas that are often mixed up: + +- **Multi-tenant application**: one application instance serves many tenants +- **Multi-instance deployment**: each customer gets a separate deployment + +Multi-instance is simpler from an isolation perspective, but more expensive to operate. Multi-tenancy is usually more efficient, but it requires stronger architectural discipline. + +## Choose your data isolation model first + +Most multi-tenancy decisions become easier once you choose the data isolation model. There are three common patterns. + +### 1. Shared database, shared schema + +This is the most common starting point. All tenants use the same tables, and each tenant-owned row includes a `TenantId`. + +Example: + +```sql +Orders +- Id +- TenantId +- CustomerId +- TotalAmount +- CreationTime +``` + +Every query must be tenant-aware. + +**Pros** + +- Lowest infrastructure cost +- Simplest provisioning +- One migration path +- Fastest way to launch + +**Cons** + +- Highest risk of accidental data leakage if tenant filtering is missed +- Noisy neighbor problems are more likely +- Harder to isolate performance-heavy tenants +- Compliance requirements may rule it out + +**Best for** + +- MVPs +- Early-stage SaaS products +- Products with many small tenants +- Teams that want operational simplicity first + +### 2. Shared database, separate schema per tenant + +In this model, tenants share the same database server, but each tenant has its own schema. + +For example: + +- `tenant_a.Orders` +- `tenant_b.Orders` + +**Pros** + +- Better separation than shared schema +- Easier tenant-specific backup and restore +- Lower leakage risk than row-level isolation alone + +**Cons** + +- Migrations become harder +- Schema drift becomes a real risk +- Managing hundreds of schemas gets messy +- Connection and routing logic becomes more complex + +**Best for** + +- Moderate compliance needs +- Tens to a few hundreds of tenants +- Teams that need more isolation without going full database-per-tenant + +### 3. Database per tenant + +Each tenant gets its own database, and sometimes even its own server. + +**Pros** + +- Strongest isolation +- Easier compliance story +- Easier tenant-specific backup, restore, and residency rules +- Better performance isolation +- Easier to support premium tenants with custom SLAs + +**Cons** + +- Higher cost +- More provisioning automation required +- More complex migrations and monitoring +- Operational overhead grows quickly + +**Best for** + +- Enterprise SaaS +- Regulated industries +- High-value tenants +- Cases where data residency or strict isolation matters + +## How to choose the right pattern + +There is no universally correct model. The right choice depends on trade-offs. + +Use these questions to decide: + +- How many tenants do you expect in 6 to 24 months? +- Do you have compliance requirements like HIPAA, GDPR residency constraints, or strict audit demands? +- How much tenant customization do you need? +- Can your team operate many databases reliably? +- What happens if one tenant runs expensive reports all day? +- Do you need tenant-specific backup and restore? + +A practical rule: + +- Start with **shared schema** if speed and cost matter most +- Use **database per tenant** if isolation and compliance matter most +- Use a **hybrid model** if your tenant base is mixed + +A hybrid model is common in real SaaS systems: + +- Small tenants live in shared infrastructure +- Large enterprise tenants get dedicated databases + +That gives you a better cost curve without forcing every customer into the most expensive setup. + +## The core building blocks of a multi-tenant system + +Regardless of the storage model, most implementations need the same building blocks. + +### Tenant resolution + +Before your application can isolate anything, it must know which tenant the request belongs to. + +Common tenant resolution strategies: + +- Subdomain: `acme.yourapp.com` +- Custom domain: `portal.acme.com` +- Header: `X-Tenant-Id` +- JWT claim or token metadata +- URL segment: `/t/acme/orders` + +Subdomain-based resolution is usually the cleanest for SaaS products. Header-based resolution is common for internal APIs but easier to misuse if not protected. + +The important part is consistency. Resolve the tenant early in the request pipeline and make it available everywhere else. + +### Tenant context + +Once resolved, store the active tenant in a tenant context that application services, repositories, caches, and logs can access. + +Typical tenant context data includes: + +- Tenant ID +- Tenant name or slug +- Connection string or database mapping +- Enabled features +- Region or residency info + +### Data filtering + +If you use shared tables, tenant filtering must be automatic. Do not rely on developers remembering to add `where TenantId == currentTenantId` in every query. + +This is where frameworks matter. ABP helps a lot here because it has built-in multi-tenancy support and data filters for tenant-aware entities. + +### Tenant-aware configuration + +Sooner or later, tenants will ask for differences: + +- Feature A enabled only for premium plans +- Different email templates +- Different password policies +- Different integrations +- Different branding + +Do not solve this with `if (tenant == ...)` scattered across the codebase. + +Use: + +- Feature flags +- Tenant settings +- Edition or plan-based configuration +- Modular integration points + +### Tenant-aware logging and auditing + +Every log entry and audit event should include tenant context where possible. + +That makes it much easier to answer questions like: + +- Which tenant triggered this error? +- Which tenant is causing high database load? +- Who accessed this record? +- Which tenant had failed background jobs? + +## Implementing multi-tenancy in ASP.NET Core + +If you build multi-tenancy manually in ASP.NET Core, the implementation usually follows this flow: + +1. Resolve tenant from the request +2. Load tenant metadata from a tenant store +3. Set current tenant context +4. Route database access based on tenant +5. Apply tenant filters automatically +6. Include tenant info in logs, cache keys, and background jobs + +A minimal tenant resolver middleware might look like this: + +```csharp +public class TenantResolutionMiddleware +{ + private readonly RequestDelegate _next; + + public TenantResolutionMiddleware(RequestDelegate next) + { + _next = next; + } + + public async Task InvokeAsync(HttpContext context, ICurrentTenantAccessor tenantAccessor) + { + var host = context.Request.Host.Host; + var subdomain = host.Split('.').FirstOrDefault(); + + if (!string.IsNullOrWhiteSpace(subdomain) && subdomain != "www") + { + tenantAccessor.CurrentTenantId = await ResolveTenantIdAsync(subdomain); + } + + await _next(context); + } + + private Task ResolveTenantIdAsync(string subdomain) + { + return Task.FromResult(null); + } +} +``` + +That is only the beginning. The hard part is making the rest of the application consistently tenant-aware. + +For example, your repository layer must avoid this kind of bug: + +```csharp +var orders = await _dbContext.Orders + .Where(x => x.Status == OrderStatus.Pending) + .ToListAsync(); +``` + +In a shared-schema model, that query is dangerous because it ignores tenant isolation. + +Safer approaches include: + +- Global query filters +- Tenant-aware repositories +- Row-level security at the database level +- Framework-level multi-tenancy abstractions + +## Implementing multi-tenancy with ABP + +ABP is a strong fit for multi-tenant business applications because multi-tenancy is built into the framework rather than bolted on later. + +ABP gives you several useful pieces out of the box: + +- Tenant resolution pipeline +- `ICurrentTenant` abstraction +- Multi-tenant entity support via `IMultiTenant` +- Data filters for tenant isolation +- Tenant management module +- Per-tenant connection string support +- Feature and setting systems + +### Tenant-aware entities + +In ABP, tenant-owned entities typically implement `IMultiTenant`. + +```csharp +using System; +using Volo.Abp.MultiTenancy; + +public class Product : IMultiTenant +{ + public Guid Id { get; set; } + public Guid? TenantId { get; set; } + public string Name { get; set; } = string.Empty; + public decimal Price { get; set; } +} +``` + +This matters because ABP can automatically apply tenant filters for entities that belong to a tenant. + +### Accessing the current tenant + +ABP exposes the current tenant through `ICurrentTenant`. + +```csharp +public class ProductAppService : ApplicationService +{ + private readonly IRepository _productRepository; + private readonly ICurrentTenant _currentTenant; + + public ProductAppService( + IRepository productRepository, + ICurrentTenant currentTenant) + { + _productRepository = productRepository; + _currentTenant = currentTenant; + } + + public async Task> GetListAsync() + { + var products = await _productRepository.GetListAsync(); + return ObjectMapper.Map, List>(products); + } +} +``` + +In a tenant context, ABP automatically scopes the repository query to the current tenant for multi-tenant entities. + +That is exactly the kind of default you want in a multi-tenant system: safe behavior unless you intentionally opt out. + +### Switching tenant context + +Background jobs, admin tools, and migration workflows sometimes need to operate in a specific tenant context. + +ABP supports this with `ICurrentTenant.Change(...)`. + +```csharp +using (_currentTenant.Change(tenantId)) +{ + var count = await _productRepository.GetCountAsync(); +} +``` + +This is useful, but it should be used carefully. Tenant context switching is powerful and easy to abuse if you do not keep boundaries clear. + +### Per-tenant connection strings + +If you choose database-per-tenant, ABP supports tenant-specific connection strings. That lets you keep the same application code while routing different tenants to different databases. + +This is one of the biggest practical advantages of using ABP for multi-tenancy: you can start simple and evolve toward stronger isolation without rewriting your entire application model. + +## Shared schema vs database per tenant in ABP + +ABP supports both host and tenant concepts, which makes it flexible enough for different SaaS stages. + +### Shared schema with ABP + +This is usually the easiest starting point. + +Use it when: + +- You want fast delivery +- Your tenants are relatively small +- Compliance requirements are moderate +- Your team wants simpler operations + +What to watch: + +- Ensure all tenant-owned entities implement `IMultiTenant` +- Be careful with raw SQL and custom queries +- Include `TenantId` in indexes where needed +- Test cross-tenant isolation aggressively + +### Database per tenant with ABP + +Use it when: + +- You need stronger isolation +- You have enterprise customers +- You need tenant-specific restore or residency +- You expect some tenants to be much larger than others + +What to watch: + +- Automate provisioning +- Automate migrations across tenant databases +- Monitor connection usage and migration failures +- Keep tenant metadata accurate and centralized + +## Migrations and schema management + +This is where many multi-tenant systems become painful. + +With shared schema, migrations are straightforward: apply once. + +With schema-per-tenant or database-per-tenant, you need orchestration. + +A practical migration workflow includes: + +- Track tenant inventory centrally +- Apply migrations in batches +- Record migration status per tenant +- Retry safely on failure +- Alert on drift +- Avoid manual one-off fixes unless documented and automated later + +If you have 5 tenants, manual migration might feel acceptable. If you have 500, it becomes an operational risk. + +For ABP-based systems, treat tenant database migration as a first-class operational workflow, not an afterthought. + +## Security pitfalls to avoid + +Multi-tenancy failures are usually not caused by the concept itself. They are caused by inconsistent enforcement. + +The most common mistakes are: + +### 1. Missing tenant filters + +This is the classic bug. One query forgets tenant scoping, and data leaks. + +Reduce the risk with: + +- Framework-level filters +- Repository abstractions +- Database row-level security where appropriate +- Integration tests that verify isolation + +### 2. Unsafe admin features + +Support tools, exports, reporting endpoints, and background jobs often bypass normal application flows. That makes them common leakage points. + +Treat admin code as high-risk code. + +### 3. Tenant context lost in async or background processing + +If a background job processes tenant data, it must explicitly carry tenant context. + +Do not assume the request context still exists. + +### 4. Shared cache keys + +If your cache key is just `product-list`, you already have a bug. + +Use tenant-aware cache keys such as: + +```text +tenant:{tenantId}:product-list +``` + +### 5. Weak audit trails + +When something goes wrong, you need to know: + +- Which tenant was affected +- Which user triggered the action +- Which service handled it +- Which data store was involved + +Without tenant-aware auditing, incident response becomes much harder. + +## Performance and noisy neighbor control + +Shared infrastructure saves money, but it also creates contention. + +A single tenant can hurt others through: + +- Expensive reports +- Large imports +- Chatty integrations +- Poorly indexed queries +- Background jobs running at the wrong time + +Mitigations include: + +- Indexing by `TenantId` +- Query timeouts +- Rate limiting per tenant +- Queue isolation for heavy jobs +- Read replicas for reporting +- Partitioning large tables +- Moving heavy tenants to dedicated databases + +This is why hybrid multi-tenancy is so common. It gives you an escape hatch when one tenant outgrows the shared model. + +## A practical implementation plan + +If you are building a new SaaS product, this is a sensible rollout path. + +### Phase 1: Start with shared schema + +- Resolve tenant from subdomain or domain +- Store tenant metadata centrally +- Use framework-level tenant filters +- Make all tenant-owned entities explicit +- Add tenant-aware logging, caching, and auditing + +For ABP, this is usually the fastest path because the framework already supports the core abstractions. + +### Phase 2: Add tenant configuration and feature management + +- Per-tenant settings +- Feature flags +- Plan-based capabilities +- Branding and integration settings + +This keeps customization manageable without branching the codebase. + +### Phase 3: Prepare for tenant mobility + +Even if you start with shared schema, design for future migration. + +That means: + +- Stable tenant IDs +- Export/import or replication strategy +- Clear ownership boundaries in data +- No hidden cross-tenant joins + +### Phase 4: Move selected tenants to dedicated databases + +Use an expand-backfill-contract approach: + +- **Expand**: create the target database +- **Backfill**: copy tenant data +- **Dual-write**: temporarily write to both stores if needed +- **Contract**: switch traffic and retire the old location + +This is much safer than a big-bang migration. + +## When to use multi-tenancy and when not to + +### When to use multi-tenancy + +- You are building a SaaS platform for many organizations +- Tenants share most application behavior +- Operational efficiency matters +- You want centralized upgrades and deployment +- You need a scalable commercial model + +### When NOT to use multi-tenancy + +- Every customer needs deep infrastructure-level customization +- Compliance requires strict physical isolation from day one +- Your team cannot support the operational complexity safely +- You only have a few large customers and each behaves like a separate product + +In those cases, multi-instance deployment may be the better choice. + +## Final recommendations + +If you are unsure where to start, start simpler than you think, but not sloppier than you can afford. + +That usually means: + +- Shared schema first +- Strong tenant resolution +- Automatic tenant filtering +- Tenant-aware logs, cache, and jobs +- A migration path to dedicated databases later + +ABP is especially useful here because it gives you the right primitives early: current tenant context, tenant-aware entities, filters, settings, and connection string support. That reduces the amount of custom plumbing you need to build and maintain. + +The biggest mistake is not choosing the wrong pattern. It is choosing a pattern without planning how tenant isolation will be enforced everywhere. + +## TL;DR + +- Multi-tenancy is mostly about safe isolation of data, behavior, and operations across customers. +- Shared schema is the easiest starting point; database-per-tenant gives the strongest isolation but adds operational cost. +- In ASP.NET Core, tenant resolution, tenant context, automatic filtering, and tenant-aware caching/logging are essential. +- ABP makes multi-tenancy easier with `ICurrentTenant`, `IMultiTenant`, data filters, tenant management, and per-tenant connection strings. +- Design for evolution early so large tenants can move to dedicated databases without a painful rewrite. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/cover.png b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/cover.png new file mode 100644 index 0000000000..2fde29d221 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-1.png b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-1.png new file mode 100644 index 0000000000..47af7d55fd Binary files /dev/null and b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-2.png b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-2.png new file mode 100644 index 0000000000..a3aebbdbf7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-3.png b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-3.png new file mode 100644 index 0000000000..0f96c0835a Binary files /dev/null and b/docs/en/Community-Articles/2026-06-03-how-to-implement-multitenancy-in-asp.net-core-and-abp/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/Post.md b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/Post.md new file mode 100644 index 0000000000..909aed4a3a --- /dev/null +++ b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/Post.md @@ -0,0 +1,1713 @@ +# Implementing Multi-Tenancy in ABP Framework: A Complete Practical Guide + +Multi-tenancy is one of those architectural decisions that looks simple in a slide deck and becomes very real the moment your SaaS application gets its second serious customer. + +At that point, questions start piling up: + +- How do you isolate tenant data safely? +- How do you resolve the current tenant from a request? +- Should all tenants share one database, or should large customers get dedicated databases? +- How do authentication, background jobs, caching, and seeding behave in a tenant-aware system? + +ABP Framework gives you a strong foundation for all of this. Instead of building tenant resolution, data filters, tenant-aware repositories, and host/tenant boundaries from scratch, you get a consistent multi-tenancy model integrated into the framework. + +This guide explains both the concepts and the implementation details. We will start with the architecture, then move into configuration, entity design, tenant resolution, seeding, authentication, database-per-tenant setups, and advanced production concerns. Along the way, we will build a practical SaaS CRM example to show how the pieces fit together. + +## What Multi-Tenancy Means in Practice + +Multi-tenancy means a single application serves multiple customers, where each customer is a tenant. Those tenants share the application platform, but their data, configuration, users, and operational boundaries must remain isolated. + +In ABP terms: + +- A **tenant** is typically a customer organization using your SaaS product. +- The **host** is the application owner or platform operator. +- In host context, `CurrentTenant` is `null`. +- In tenant context, `CurrentTenant.Id` identifies the active tenant. + +### Single-tenant vs multi-tenant + +A **single-tenant** system usually means: + +- one deployment per customer, +- one database per customer, +- isolated infrastructure by default, +- higher operational cost. + +A **multi-tenant** system usually means: + +- one application serves many customers, +- data isolation is enforced logically or physically, +- lower operational overhead, +- more architectural responsibility. + +### Why SaaS teams care about multi-tenancy + +Multi-tenancy matters because it directly affects: + +- cost efficiency, +- onboarding speed, +- operational scalability, +- security boundaries, +- customization strategy, +- enterprise sales readiness. + +### Advantages + +- Lower infrastructure cost per customer +- Centralized deployment and upgrades +- Easier feature rollout +- Better operational consistency +- Faster tenant provisioning + +### Challenges + +- Strong data isolation is mandatory +- Noisy-neighbor performance issues can appear +- Authentication becomes tenant-aware +- Background processing must preserve tenant context +- Reporting across tenants requires deliberate design +- Database-per-tenant operations add migration complexity + +### Why ABP simplifies multi-tenant development + +ABP helps because multi-tenancy is not treated as an afterthought. It is built into the framework through: + +- `ICurrentTenant` +- `IMultiTenant` +- automatic data filters +- tenant resolution middleware +- tenant management abstractions +- tenant-aware repositories and unit of work integration +- support for shared database, database-per-tenant, and hybrid models + +That combination removes a lot of repetitive plumbing and reduces the chance of subtle isolation bugs. + +## Understanding ABP Multi-Tenancy Architecture + +ABP’s multi-tenancy architecture is centered around tenant context propagation. The framework resolves the tenant from the incoming request, stores it in the current execution context, and applies that context to repositories, filters, services, and modules. + +### Core concepts + +#### Tenant concept + +A tenant is a customer boundary. In a CRM SaaS product, each company using the system is a tenant. + +Examples: + +- `Acme Logistics` +- `Northwind Retail` +- `Contoso Health` + +Each tenant may have: + +- its own users, +- its own roles, +- its own settings, +- its own features, +- its own data, +- optionally its own database. + +#### Host side + +The host side is the platform owner context. + +Typical host responsibilities: + +- create and manage tenants, +- assign subscription plans, +- configure editions and features, +- monitor usage, +- run cross-tenant administration, +- manage billing and provisioning. + +In ABP, host-side entities often have `TenantId = null`. + +#### Tenant side + +The tenant side is the customer-facing application context. + +Typical tenant responsibilities: + +- manage tenant users, +- manage tenant roles, +- create business data, +- configure tenant settings, +- consume tenant-specific features. + +#### `ICurrentTenant` + +`ICurrentTenant` is the main runtime service for reading the active tenant context. + +It exposes: + +- `Id` +- `Name` +- `IsAvailable` + +This service is used everywhere from application services to background jobs. + +#### Tenant resolution pipeline + +ABP resolves the tenant before your application logic runs. It uses configured contributors such as: + +- current user claims, +- query string, +- route values, +- headers, +- domain or subdomain, +- custom resolvers. + +Then `app.UseMultiTenancy()` sets the current tenant context. + +#### `IMultiTenant` + +Entities implementing `IMultiTenant` gain a `Guid? TenantId` property. ABP uses this to apply automatic filtering. + +If `TenantId` is: + +- a tenant id: the entity belongs to that tenant, +- `null`: the entity belongs to the host side. + +#### Data filters + +ABP automatically filters `IMultiTenant` entities so tenant queries only see their own data by default. + +This is one of the most important safety features in the framework. + +#### Tenant Management Module + +ABP provides tenant management infrastructure through its tenant management module and `ITenantStore` abstraction. + +This is used to: + +- store tenant definitions, +- resolve tenant configuration, +- retrieve tenant-specific connection strings, +- support tenant provisioning workflows. + +### Architecture diagram + +```mermaid +flowchart LR + A[Incoming HTTP Request] --> B[Tenant Resolution Contributors] + B --> C[Multi-Tenancy Middleware] + C --> D[ICurrentTenant] + D --> E[Application Service] + E --> F[Repository] + F --> G[Data Filter IMultiTenant] + G --> H[(Database)] +``` + +### Host and tenant boundaries + +```mermaid +flowchart TD + H[Host Context CurrentTenant = null] + T1[Tenant A Context] + T2[Tenant B Context] + + H --> HM[Tenant Management] + H --> FM[Feature Management] + H --> SM[Subscription Management] + + T1 --> D1[Tenant A Data] + T1 --> U1[Tenant A Users] + + T2 --> D2[Tenant B Data] + T2 --> U2[Tenant B Users] +``` + +### Query isolation flow + +```mermaid +sequenceDiagram + participant Req as Request + participant MW as Multi-Tenancy Middleware + participant CT as ICurrentTenant + participant Repo as Repository + participant DB as Database + + Req->>MW: Resolve tenant + MW->>CT: Set TenantId + CT->>Repo: Current tenant context available + Repo->>DB: SELECT ... WHERE TenantId = @CurrentTenantId + DB-->>Repo: Tenant-scoped rows +``` + +## Multi-Tenancy Models Supported by ABP + +ABP supports the three models most SaaS teams actually use: shared database, database per tenant, and hybrid. + +### 1) Single Database / Shared Database + +All tenants share the same physical database. Tenant-specific rows are separated by `TenantId`. + +#### How it works + +- One database stores host and tenant data. +- Tenant-aware entities implement `IMultiTenant`. +- ABP filters rows automatically. + +#### Advantages + +- Lowest infrastructure cost +- Simplest migrations +- Easier backup strategy +- Easier reporting across tenants +- Faster onboarding for small SaaS products + +#### Disadvantages + +- Weaker isolation than dedicated databases +- Noisy-neighbor risk +- Large tenants can affect shared performance +- Cross-tenant leak risk if filters are bypassed incorrectly + +### 2) Database Per Tenant + +Each tenant gets its own physical database. The host may also have a separate database. + +#### How it works + +- Tenant metadata is stored centrally or in a host database. +- `ITenantStore` resolves tenant configuration. +- Connection strings are selected dynamically per tenant. + +#### Advantages + +- Strong isolation +- Easier compliance conversations +- Better performance isolation +- Easier tenant-specific backup and restore +- Large tenants can scale independently + +#### Disadvantages + +- More operational overhead +- More complex migrations +- Harder cross-tenant analytics +- More secrets and connection strings to manage +- More provisioning automation required + +### 3) Hybrid Model + +Some tenants share a database, while larger or regulated tenants get dedicated databases. + +#### Enterprise SaaS scenarios + +This is often the most realistic model when: + +- small tenants are cost-sensitive, +- enterprise tenants require stronger isolation, +- some customers need regional or compliance-specific storage, +- you want a migration path from shared to dedicated databases. + +#### Advantages + +- Flexible cost model +- Better fit for mixed customer sizes +- Easier enterprise upsell path + +#### Disadvantages + +- Highest architectural complexity +- More operational branching +- More migration and observability work + +### Comparison table + +| Model | Isolation | Cost | Operational Complexity | Best For | +|---|---|---:|---:|---| +| Shared Database | Logical | Low | Low | Early-stage SaaS, many small tenants | +| Database Per Tenant | Physical | High | High | Enterprise SaaS, regulated workloads | +| Hybrid | Mixed | Medium to High | High | Growing SaaS with mixed tenant profiles | + +| Concern | Shared Database | Database Per Tenant | Hybrid | +|---|---|---|---| +| Migrations | Simple | Complex | Complex | +| Cross-tenant reporting | Easy | Harder | Mixed | +| Performance isolation | Limited | Strong | Selective | +| Tenant onboarding | Fast | Slower | Depends on tier | +| Compliance flexibility | Moderate | Strong | Strong | + +### When to use / When NOT to use + +#### Use shared database when + +- you are building an MVP or early SaaS, +- tenants are relatively small, +- cost efficiency matters more than hard isolation, +- your team wants simpler operations. + +#### Do not use shared database when + +- tenants require strict physical isolation, +- you expect very uneven tenant load, +- compliance or contractual requirements demand dedicated storage. + +#### Use database per tenant when + +- enterprise customers require isolation, +- you need tenant-specific backup/restore, +- large tenants justify dedicated infrastructure. + +#### Do not use database per tenant when + +- your team is not ready for migration automation, +- you have many tiny tenants and limited ops capacity, +- cross-tenant analytics is a core requirement and you have no aggregation strategy. + +#### Use hybrid when + +- you need both efficiency and enterprise flexibility, +- you want to move premium tenants to dedicated databases over time. + +#### Do not use hybrid when + +- your operational tooling is immature, +- your team is still validating the product and needs simplicity first. + +## Enabling Multi-Tenancy in ABP + +In most ABP solutions, multi-tenancy is enabled through a shared constant and framework options. + +### `MultiTenancyConsts` + +A typical template includes a constant like this: + +```csharp +namespace Acme.Crm; + +public static class MultiTenancyConsts +{ + public const bool IsEnabled = true; +} +``` + +This constant is often referenced across layers so the application has one central switch. + +### Configure `AbpMultiTenancyOptions` + +In your module: + +```csharp +using Volo.Abp.MultiTenancy; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.IsEnabled = MultiTenancyConsts.IsEnabled; + options.UserSharingStrategy = TenantUserSharingStrategy.Isolated; + }); +} +``` + +`UserSharingStrategy` matters when you decide whether users are isolated per tenant or shared across tenants. + +### Configure middleware + +In your HTTP pipeline: + +```csharp +public override void OnApplicationInitialization(ApplicationInitializationContext context) +{ + var app = context.GetApplicationBuilder(); + var env = context.GetEnvironment(); + + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + + app.UseRouting(); + app.UseAuthentication(); + app.UseMultiTenancy(); + app.UseAuthorization(); + + app.UseConfiguredEndpoints(); +} +``` + +The exact middleware order can vary by solution template, but `UseMultiTenancy()` must be present so tenant resolution runs. + +### Example appsettings.json + +For a shared database setup: + +```json +{ + "ConnectionStrings": { + "Default": "Server=localhost;Database=CrmShared;Trusted_Connection=True;TrustServerCertificate=True" + } +} +``` + +For a host database plus tenant metadata: + +```json +{ + "ConnectionStrings": { + "Default": "Server=localhost;Database=CrmHost;Trusted_Connection=True;TrustServerCertificate=True" + } +} +``` + +### Full module example + +```csharp +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp; +using Volo.Abp.Modularity; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm; + +[DependsOn( + typeof(AbpMultiTenancyModule) +)] +public class CrmHttpApiHostModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + options.IsEnabled = MultiTenancyConsts.IsEnabled; + options.UserSharingStrategy = TenantUserSharingStrategy.Isolated; + }); + } + + public override void OnApplicationInitialization(ApplicationInitializationContext context) + { + var app = context.GetApplicationBuilder(); + + app.UseRouting(); + app.UseAuthentication(); + app.UseMultiTenancy(); + app.UseAuthorization(); + app.UseConfiguredEndpoints(); + } +} +``` + +## Tenant Resolution Strategies + +Tenant resolution is where multi-tenancy becomes real. The framework must determine which tenant the request belongs to before your application logic executes. + +ABP supports multiple strategies, and you can combine them. + +### Default resolution contributors + +ABP can resolve tenants from: + +- current user claims, +- query string `__tenant`, +- route values, +- custom contributors. + +### Configure tenant resolution + +```csharp +using Volo.Abp.AspNetCore.MultiTenancy; +using Volo.Abp.MultiTenancy; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.AddDomainTenantResolver("{0}.mycrm.com"); + options.TenantResolvers.Add(new HeaderTenantResolveContributor()); + }); +} +``` + +### Subdomain resolution + +This is common in SaaS products: + +- `acme.mycrm.com` +- `northwind.mycrm.com` + +Configuration: + +```csharp +Configure(options => +{ + options.AddDomainTenantResolver("{0}.mycrm.com"); +}); +``` + +ABP extracts `acme` or `northwind` and uses it as the tenant identifier. + +### Domain resolution + +You can also map full domains to tenants, especially for enterprise customers using custom domains. + +Examples: + +- `crm.acme-enterprise.com` +- `portal.contosohealth.io` + +This usually requires custom tenant lookup logic or a domain mapping table in your tenant store. + +### Header-based resolution + +Useful for APIs, gateways, or internal service-to-service calls. + +Example custom contributor: + +```csharp +using System.Threading.Tasks; +using Volo.Abp.MultiTenancy; + +public class HeaderTenantResolveContributor : TenantResolveContributorBase +{ + public const string HeaderName = "X-Tenant"; + + public override string Name => "Header"; + + public override Task ResolveAsync(ITenantResolveContext context) + { + var httpContext = context.GetHttpContext(); + if (httpContext == null) + { + return Task.CompletedTask; + } + + var tenant = httpContext.Request.Headers[HeaderName].ToString(); + if (!tenant.IsNullOrWhiteSpace()) + { + context.TenantIdOrName = tenant; + } + + return Task.CompletedTask; + } +} +``` + +### Query string resolution + +Useful for testing and some integration scenarios. + +Example: + +- `/api/products?__tenant=acme` + +This is convenient, but usually not the best primary strategy for production browser apps. + +### Route-based resolution + +Example: + +- `/t/acme/products` + +This can work well for APIs or apps where tenant identity is part of the route structure. + +### Custom tenant resolver + +If your tenant identification depends on something domain-specific, implement your own contributor. + +Example: resolve tenant from an API key prefix. + +```csharp +using System.Threading.Tasks; +using Volo.Abp.MultiTenancy; + +public class ApiKeyTenantResolveContributor : TenantResolveContributorBase +{ + public override string Name => "ApiKey"; + + public override Task ResolveAsync(ITenantResolveContext context) + { + var httpContext = context.GetHttpContext(); + if (httpContext == null) + { + return Task.CompletedTask; + } + + var apiKey = httpContext.Request.Headers["X-Api-Key"].ToString(); + if (string.IsNullOrWhiteSpace(apiKey)) + { + return Task.CompletedTask; + } + + if (apiKey.StartsWith("acme_")) + { + context.TenantIdOrName = "acme"; + } + + return Task.CompletedTask; + } +} +``` + +### HTTP request flow + +```mermaid +sequenceDiagram + participant C as Client + participant R as Tenant Resolver Contributors + participant M as UseMultiTenancy Middleware + participant T as ITenantStore + participant CT as ICurrentTenant + participant A as Application Service + + C->>R: HTTP request with host/header/query/route + R->>M: TenantIdOrName resolved + M->>T: Load tenant configuration + T-->>M: Tenant info + connection strings + M->>CT: Set current tenant context + CT->>A: Tenant-aware execution begins +``` + +### Practical guidance + +- Use **subdomain resolution** for browser-based SaaS apps. +- Use **header-based resolution** for APIs behind gateways. +- Keep **query string resolution** mainly for testing or controlled integrations. +- Add **custom resolvers** only when the business rule is stable and well documented. + +## Creating Tenant-Aware Entities + +The most important rule in ABP multi-tenancy is simple: entities that belong to a tenant should implement `IMultiTenant`. + +### Basic entity design + +```csharp +using System; +using Volo.Abp.Domain.Entities.Auditing; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Products; + +public class Product : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; protected set; } + public string Name { get; private set; } + public decimal Price { get; private set; } + + protected Product() + { + } + + public Product(Guid id, Guid? tenantId, string name, decimal price) + : base(id) + { + TenantId = tenantId; + Name = name; + Price = price; + } +} +``` + +### Customer example + +```csharp +using System; +using Volo.Abp.Domain.Entities.Auditing; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Customers; + +public class Customer : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; protected set; } + public string CompanyName { get; private set; } + public string Email { get; private set; } + + protected Customer() + { + } + + public Customer(Guid id, Guid? tenantId, string companyName, string email) + : base(id) + { + TenantId = tenantId; + CompanyName = companyName; + Email = email; + } +} +``` + +### Order example + +```csharp +using System; +using Volo.Abp.Domain.Entities.Auditing; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Orders; + +public class Order : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; protected set; } + public Guid CustomerId { get; private set; } + public DateTime OrderDate { get; private set; } + public decimal TotalAmount { get; private set; } + + protected Order() + { + } + + public Order(Guid id, Guid? tenantId, Guid customerId, DateTime orderDate, decimal totalAmount) + : base(id) + { + TenantId = tenantId; + CustomerId = customerId; + OrderDate = orderDate; + TotalAmount = totalAmount; + } +} +``` + +### Aggregate root considerations + +A few practical rules help avoid trouble: + +- Put `TenantId` on aggregate roots that are tenant-owned. +- Keep child entities inside the same tenant boundary as the aggregate root. +- Avoid aggregates that reference entities from different tenants. +- Be explicit about whether an entity is host-owned or tenant-owned. + +### How ABP filters tenant data automatically + +Once an entity implements `IMultiTenant`, ABP applies the multi-tenant data filter automatically. + +That means this repository call: + +```csharp +var products = await _productRepository.GetListAsync(); +``` + +will only return rows for the current tenant when tenant context is active. + +### Generated SQL shape + +The exact SQL depends on your provider and query, but conceptually it looks like this: + +```sql +SELECT Id, TenantId, Name, Price +FROM CrmProducts +WHERE TenantId = @CurrentTenantId +``` + +In host context, behavior depends on the entity and query shape. Host-owned rows typically have `TenantId IS NULL`. + +### Important design note about `TenantId` + +`IMultiTenant` defines `Guid? TenantId`, which is nullable because host-owned entities may exist. + +If your entity must always belong to a tenant, you can enforce that in domain logic and EF configuration, but be careful. The framework’s default contract is nullable, and forcing non-null semantics requires deliberate mapping and validation. + +## Working with CurrentTenant + +`ICurrentTenant` is the runtime API you will use most often in multi-tenant services. + +### Reading current tenant information + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Products; + +public class ProductAppService : ApplicationService +{ + private readonly ICurrentTenant _currentTenant; + + public ProductAppService(ICurrentTenant currentTenant) + { + _currentTenant = currentTenant; + } + + public Task GetTenantInfoAsync() + { + var tenantId = _currentTenant.Id?.ToString() ?? "Host"; + var tenantName = _currentTenant.Name ?? "Host"; + + return Task.FromResult($"TenantId: {tenantId}, TenantName: {tenantName}"); + } +} +``` + +### Creating tenant-owned data safely + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.Domain.Repositories; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Products; + +public class ProductAppService : ApplicationService +{ + private readonly IRepository _productRepository; + private readonly ICurrentTenant _currentTenant; + + public ProductAppService( + IRepository productRepository, + ICurrentTenant currentTenant) + { + _productRepository = productRepository; + _currentTenant = currentTenant; + } + + public async Task CreateAsync(string name, decimal price) + { + if (!_currentTenant.IsAvailable) + { + throw new BusinessException("Products can only be created in tenant context."); + } + + var product = new Product(GuidGenerator.Create(), _currentTenant.Id, name, price); + await _productRepository.InsertAsync(product, autoSave: true); + return product.Id; + } +} +``` + +### Changing tenant context + +ABP allows temporary tenant switching with `CurrentTenant.Change(...)`. + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Domain.Repositories; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Reporting; + +public class TenantProductCounter : ITransientDependency +{ + private readonly ICurrentTenant _currentTenant; + private readonly IRepository _productRepository; + + public TenantProductCounter( + ICurrentTenant currentTenant, + IRepository productRepository) + { + _currentTenant = currentTenant; + _productRepository = productRepository; + } + + public async Task CountForTenantAsync(Guid tenantId) + { + using (_currentTenant.Change(tenantId)) + { + return await _productRepository.GetCountAsync(); + } + } +} +``` + +### Nested tenant scopes + +```csharp +public async Task CompareTwoTenantsAsync(Guid tenantA, Guid tenantB) +{ + using (_currentTenant.Change(tenantA)) + { + var countA = await _productRepository.GetCountAsync(); + + using (_currentTenant.Change(tenantB)) + { + var countB = await _productRepository.GetCountAsync(); + } + } +} +``` + +Nested scopes are useful, but they should remain easy to reason about. If tenant switching becomes deeply nested, move that logic into dedicated services. + +### Practical rules for `ICurrentTenant` + +- Read it at the application or domain service boundary. +- Avoid passing raw tenant ids everywhere when the current context already exists. +- Use `Change(...)` sparingly and intentionally. +- Never assume tenant context exists in host-side operations. + +## Data Isolation Mechanisms + +ABP’s biggest multi-tenancy advantage is that data isolation is integrated into repositories and unit of work. + +### Automatic data filtering + +When an entity implements `IMultiTenant`, ABP applies the multi-tenant filter automatically. + +That means: + +- tenant A cannot see tenant B rows through normal repository queries, +- host operations can work in host context, +- the same repository code behaves differently depending on `ICurrentTenant`. + +### Tenant-specific repositories + +You usually do not need separate repositories per tenant. The same repository becomes tenant-aware because the current tenant context changes the filter behavior. + +Example: + +```csharp +var customers = await _customerRepository.GetListAsync(); +``` + +In tenant `Acme`, this returns only Acme customers. + +### Unit of Work integration + +ABP’s unit of work carries tenant context through the execution flow. This matters because: + +- repository queries stay tenant-scoped, +- transactional operations remain consistent, +- tenant switching inside a scope affects subsequent repository calls. + +### Disabling the filter carefully + +Sometimes host-side reporting or maintenance tasks need cross-tenant access. + +```csharp +using System.Collections.Generic; +using System.Threading.Tasks; +using Volo.Abp.Data; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Domain.Repositories; + +public class CrossTenantProductReader : ITransientDependency +{ + private readonly IDataFilter _dataFilter; + private readonly IRepository _productRepository; + + public CrossTenantProductReader( + IDataFilter dataFilter, + IRepository productRepository) + { + _dataFilter = dataFilter; + _productRepository = productRepository; + } + + public async Task> GetAllAsync() + { + using (_dataFilter.Disable()) + { + return await _productRepository.GetListAsync(); + } + } +} +``` + +This is powerful and dangerous. + +### Security implications + +Disabling `IMultiTenant` filtering means you are bypassing one of your main isolation protections. + +Use it only when: + +- the operation is explicitly host-level, +- authorization is strong, +- the result is not accidentally exposed to tenant users, +- the code path is easy to audit. + +### SQL examples + +Normal tenant-scoped query: + +```sql +SELECT * +FROM CrmCustomers +WHERE TenantId = @CurrentTenantId +ORDER BY CompanyName +``` + +Cross-tenant query with filter disabled: + +```sql +SELECT * +FROM CrmCustomers +ORDER BY TenantId, CompanyName +``` + +### Isolation checklist + +- Tenant-owned entities implement `IMultiTenant` +- Tenant context is resolved before app logic +- Filters remain enabled by default +- Host-only operations are explicitly separated +- Cross-tenant reads are rare and audited + +## Seeding Tenant Data + +Seeding is where many multi-tenant applications become inconsistent. The host needs one set of seed data, while each tenant may need its own initialization. + +ABP’s `IDataSeedContributor` makes this manageable. + +### Host and tenant seeding model + +- Host seeding runs when `DataSeedContext.TenantId == null` +- Tenant seeding runs when `DataSeedContext.TenantId` has a value +- You can switch tenant context with `CurrentTenant.Change(...)` + +### Host seed contributor example + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Data; +using Volo.Abp.DependencyInjection; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Data; + +public class HostDataSeedContributor : IDataSeedContributor, ITransientDependency +{ + private readonly ICurrentTenant _currentTenant; + + public HostDataSeedContributor(ICurrentTenant currentTenant) + { + _currentTenant = currentTenant; + } + + public async Task SeedAsync(DataSeedContext context) + { + if (context.TenantId != null) + { + return; + } + + using (_currentTenant.Change(null)) + { + await Task.CompletedTask; + // Seed host-side editions, plans, global settings, etc. + } + } +} +``` + +### Tenant seed contributor example + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Data; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Domain.Repositories; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Data; + +public class TenantDataSeedContributor : IDataSeedContributor, ITransientDependency +{ + private readonly ICurrentTenant _currentTenant; + private readonly IRepository _productRepository; + + public TenantDataSeedContributor( + ICurrentTenant currentTenant, + IRepository productRepository) + { + _currentTenant = currentTenant; + _productRepository = productRepository; + } + + public async Task SeedAsync(DataSeedContext context) + { + if (context.TenantId == null) + { + return; + } + + using (_currentTenant.Change(context.TenantId)) + { + if (await _productRepository.GetCountAsync() > 0) + { + return; + } + + await _productRepository.InsertAsync( + new Products.Product(Guid.NewGuid(), context.TenantId, "Starter Plan", 49), + autoSave: true + ); + + await _productRepository.InsertAsync( + new Products.Product(Guid.NewGuid(), context.TenantId, "Growth Plan", 99), + autoSave: true + ); + } + } +} +``` + +### Per-tenant initialization during provisioning + +A common SaaS flow looks like this: + +1. Host admin creates tenant +2. Tenant metadata is stored +3. Tenant database is created or assigned +4. Migrations run +5. Seed contributors initialize tenant data +6. Admin user is created +7. Features/settings are applied + +### Practical seeding advice + +- Keep seeders idempotent +- Separate host and tenant concerns clearly +- Avoid large business workflows inside seed contributors +- Use provisioning services for complex onboarding + +## Multi-Tenant Authentication and Identity + +Authentication is where many multi-tenant systems fail in subtle ways. If tenant resolution happens too late, users may authenticate against the wrong tenant context. + +ABP’s identity integration helps because users are tenant-aware. + +### Tenant-specific users and roles + +In ABP: + +- users can belong to a tenant, +- roles can be tenant-specific, +- host users can exist separately, +- identity behavior depends on the user sharing strategy. + +### Identity module integration + +ABP Identity integrates with multi-tenancy so that user and role management respects tenant boundaries. + +Typical outcomes: + +- tenant admins manage only their tenant users, +- host admins manage platform-level concerns, +- tenant users do not see host-level identity data. + +### Login flow + +The tenant should be resolved before authentication whenever possible. + +Typical browser flow: + +1. User visits `acme.mycrm.com` +2. Tenant resolver identifies `acme` +3. Multi-tenancy middleware sets current tenant +4. Authentication runs in tenant context +5. User is validated against tenant-aware identity data +6. Authorized application logic executes + +### Login request flow diagram + +```mermaid +sequenceDiagram + participant U as User Browser + participant D as Domain/Subdomain Resolver + participant MT as Multi-Tenancy Middleware + participant ID as Identity/Auth + participant APP as Application + + U->>D: Request acme.mycrm.com/login + D->>MT: Tenant = acme + MT->>ID: Authenticate in tenant context + ID-->>APP: Authenticated tenant user + APP-->>U: Tenant-scoped session +``` + +### Tenant switching + +Tenant switching can mean different things: + +- switching browser context from one tenant domain to another, +- host admin impersonating or managing a tenant, +- shared-user scenarios where one identity can access multiple tenants. + +In most SaaS applications, the cleanest approach is domain-based switching rather than trying to mutate tenant context inside a long-lived UI session. + +### Shared user accounts vs isolated users + +ABP supports user sharing strategies. + +#### Isolated users + +- usernames/emails are unique within tenant scope, +- simpler mental model, +- best default for most SaaS apps. + +#### Shared users + +- one user identity may exist across tenants, +- global uniqueness rules become important, +- database-per-tenant setups become more complex, +- host-side identity metadata may need replication or synchronization. + +Unless you have a strong product reason, isolated users are usually the safer choice. + +## Database Per Tenant Configuration + +Database-per-tenant is where ABP’s abstractions become especially valuable. + +### Connection string management + +At runtime, the application needs to know which database to use for the current tenant. + +That information typically comes from `ITenantStore`. + +### `ITenantStore` + +`ITenantStore` is the abstraction used to retrieve tenant configuration, including: + +- tenant id, +- tenant name, +- activation state, +- connection strings. + +ABP provides implementations through tenant management infrastructure. In simpler setups, configuration-based tenant stores can also be used. + +### Tenant-specific database setup + +For module-specific database usage, you can configure database options like this: + +```csharp +using Volo.Abp.Data; +using Volo.Abp.Modularity; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.Databases.Configure("Saas", database => + { + database.IsUsedByTenants = true; + }); + }); +} +``` + +### Example tenant configuration shape + +In a custom store or configuration source, you may keep tenant metadata like this: + +```json +{ + "Tenants": [ + { + "Id": "11111111-1111-1111-1111-111111111111", + "Name": "acme", + "ConnectionStrings": { + "Default": "Server=sql1;Database=Crm_Acme;User Id=app;Password=secret;TrustServerCertificate=True" + } + }, + { + "Id": "22222222-2222-2222-2222-222222222222", + "Name": "northwind", + "ConnectionStrings": { + "Default": "Server=sql2;Database=Crm_Northwind;User Id=app;Password=secret;TrustServerCertificate=True" + } + } + ] +} +``` + +### Production-ready custom tenant store example + +```csharp +using System; +using System.Collections.Concurrent; +using System.Linq; +using System.Threading.Tasks; +using Microsoft.Extensions.Options; +using Volo.Abp.DependencyInjection; +using Volo.Abp.MultiTenancy; + +public class AppTenantStore : ITenantStore, ITransientDependency +{ + private readonly ConcurrentDictionary _tenantsByName; + private readonly ConcurrentDictionary _tenantsById; + + public AppTenantStore(IOptions options) + { + _tenantsByName = new ConcurrentDictionary(StringComparer.OrdinalIgnoreCase); + _tenantsById = new ConcurrentDictionary(); + + foreach (var tenant in options.Value.Tenants) + { + _tenantsByName[tenant.Name] = tenant; + if (tenant.Id.HasValue) + { + _tenantsById[tenant.Id.Value] = tenant; + } + } + } + + public Task FindAsync(string normalizedName) + { + _tenantsByName.TryGetValue(normalizedName, out var tenant); + return Task.FromResult(tenant); + } + + public Task FindAsync(Guid id) + { + _tenantsById.TryGetValue(id, out var tenant); + return Task.FromResult(tenant); + } +} + +public class AppTenantStoreOptions +{ + public TenantConfiguration[] Tenants { get; set; } = Array.Empty(); +} +``` + +### Provisioning flow for dedicated databases + +A production-grade tenant provisioning process usually includes: + +- create tenant record, +- generate or assign connection string, +- create database, +- run migrations, +- seed tenant data, +- create tenant admin, +- verify health checks. + +### Open source vs PRO note + +ABP supports database-per-tenant architecture in general, but UI-based connection string management for tenants is part of the commercial SaaS tooling. In open-source solutions, you typically implement your own management UI or provisioning workflow. + +## Advanced Scenarios in Real Applications + +Multi-tenancy affects more than repositories. In production systems, the tricky parts are usually background jobs, events, caching, features, settings, and observability. + +### Background jobs in tenant context + +If a background job processes tenant data, it must restore the correct tenant context. + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.BackgroundJobs; +using Volo.Abp.DependencyInjection; +using Volo.Abp.MultiTenancy; + +public class RebuildCustomerStatsArgs +{ + public Guid TenantId { get; set; } +} + +public class RebuildCustomerStatsJob : AsyncBackgroundJob, ITransientDependency +{ + private readonly ICurrentTenant _currentTenant; + + public RebuildCustomerStatsJob(ICurrentTenant currentTenant) + { + _currentTenant = currentTenant; + } + + public override async Task ExecuteAsync(RebuildCustomerStatsArgs args) + { + using (_currentTenant.Change(args.TenantId)) + { + await Task.CompletedTask; + // Recalculate tenant-specific metrics here. + } + } +} +``` + +### Distributed events + +When publishing distributed events, include tenant context explicitly if consumers need it. + +Good practice: + +- include `TenantId` in event payloads, +- restore tenant context in handlers, +- avoid assuming ambient tenant context exists in asynchronous boundaries. + +### Caching per tenant + +Cache keys should include tenant identity. + +Bad: + +- `customer-list` + +Better: + +- `tenant:{tenantId}:customer-list` + +Without tenant-aware cache keys, cross-tenant data leaks become very possible. + +### Feature management + +Features are a natural fit for SaaS plans. + +Examples: + +- maximum users, +- advanced reporting, +- API access, +- custom branding. + +ABP feature management supports tenant-level configuration and edition-based grouping. + +### Setting management + +Settings can be scoped globally, per tenant, or per user. + +Examples: + +- default currency, +- email sender, +- invoice numbering format, +- CRM pipeline defaults. + +### Audit logging + +Audit logs should capture tenant context so you can answer questions like: + +- which tenant triggered this action, +- which admin changed a tenant setting, +- which background job modified tenant data. + +### Localization + +Tenants often need different localization defaults: + +- language, +- timezone, +- regional formatting, +- legal text. + +Tenant-level settings are usually the right place for these preferences. + +### Common pitfalls + +- forgetting tenant context in background jobs, +- using cache keys without tenant id, +- disabling data filters too broadly, +- mixing host and tenant responsibilities in one service, +- assuming tenant resolution works the same in browser and API flows, +- not testing wildcard domain auth configuration carefully. + +## Building a Sample SaaS CRM Application + +Let’s connect the concepts with a practical example. + +Imagine a SaaS CRM built with ABP. + +### Functional areas + +#### Host administration + +The host side manages: + +- tenant creation, +- subscription plans, +- feature packages, +- billing integration, +- tenant health and usage. + +#### Tenant administration + +Each tenant manages: + +- users, +- roles, +- settings, +- branding, +- sales workflows. + +#### Customer management + +Tenant users create and manage: + +- customers, +- contacts, +- opportunities, +- orders, +- notes. + +#### Subscription management + +The host assigns plans such as: + +- Starter +- Growth +- Enterprise + +These plans map naturally to ABP features and settings. + +### Suggested architecture + +- **Host app** for platform administration +- **Tenant-facing app** resolved by subdomain +- **Shared modules** for identity, audit logging, feature management, setting management +- **Tenant-aware domain entities** for CRM data +- **Hybrid database strategy** if enterprise tenants need dedicated databases + +### Example domain boundaries + +Host-owned entities: + +- Tenant +n- SubscriptionPlan +- Edition +- BillingAccount + +Tenant-owned entities: + +- Customer +- Product +- Order +- SalesPipeline +- ActivityLog + +### Tenant-aware application service example + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.Domain.Repositories; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Customers; + +public class CustomerAppService : ApplicationService +{ + private readonly IRepository _customerRepository; + private readonly ICurrentTenant _currentTenant; + + public CustomerAppService( + IRepository customerRepository, + ICurrentTenant currentTenant) + { + _customerRepository = customerRepository; + _currentTenant = currentTenant; + } + + public async Task CreateAsync(string companyName, string email) + { + if (!_currentTenant.IsAvailable) + { + throw new BusinessException("Customer creation requires tenant context."); + } + + var customer = new Customer( + GuidGenerator.Create(), + _currentTenant.Id, + companyName, + email + ); + + await _customerRepository.InsertAsync(customer, autoSave: true); + return customer.Id; + } +} +``` + +### End-to-end request example + +A request to `https://acme.mycrm.com/api/customers` flows like this: + +1. Domain resolver extracts `acme` +2. `ITenantStore` loads tenant metadata +3. `ICurrentTenant` is set +4. Authentication runs in tenant context +5. Repository queries apply `IMultiTenant` filter +6. Only Acme customer data is returned + +That is the core ABP multi-tenancy story in one request. + +## Best Practices for ABP Multi-Tenant Applications + +Here are practical best practices that hold up well in real systems. + +1. **Implement `IMultiTenant` on every tenant-owned aggregate root.** Do not rely on conventions or memory. +2. **Use subdomain-based tenant resolution for browser SaaS apps.** It is usually the cleanest UX and operational model. +3. **Keep host and tenant application services separate.** Mixing them creates authorization and maintenance problems. +4. **Treat `IDataFilter.Disable()` as a privileged operation.** Review those code paths carefully. +5. **Index `TenantId` on large tables.** Shared-database performance depends on it. +6. **Include `TenantId` in cache keys, distributed events, and background job payloads.** Ambient context does not cross every boundary. +7. **Resolve tenant before authentication.** Especially for domain/subdomain-based login flows. +8. **Prefer isolated users unless shared identities are a real product requirement.** Shared users add complexity fast. +9. **Automate tenant provisioning.** Manual database creation and migration does not scale. +10. **Make seed contributors idempotent.** Tenant provisioning may be retried. +11. **Design for hybrid early if you expect enterprise customers.** Moving from shared-only to hybrid later is possible, but easier if planned. +12. **Store tenant connection strings securely.** Use secret management and rotation policies. +13. **Log tenant context in audit and operational logs.** Troubleshooting without tenant identity is painful. +14. **Test host context explicitly.** `CurrentTenant` being `null` is a valid and important scenario. +15. **Avoid cross-tenant joins in domain logic.** If you need cross-tenant analytics, build reporting pipelines intentionally. +16. **Keep tenant switching localized.** Use `CurrentTenant.Change(...)` in small, obvious scopes. +17. **Validate tenant ownership in domain rules where it matters.** Filters help, but domain invariants still matter. +18. **Monitor noisy-neighbor patterns.** Shared databases need tenant-level performance visibility. +19. **Run tenant-aware integration tests.** Unit tests alone will not catch resolution and filter issues. +20. **Document your tenant resolution strategy clearly.** Operations, frontend, and identity flows all depend on it. + +## Common Mistakes to Avoid + +Even experienced teams make the same multi-tenancy mistakes. + +### 1) Assuming repository filtering solves everything + +Repository filtering is excellent, but it does not replace: + +- authorization, +- cache isolation, +- event payload design, +- background job context restoration. + +### 2) Treating host context as an edge case + +In ABP, host context is a first-class concept. Design for it explicitly. + +### 3) Choosing database-per-tenant too early or too late + +Too early: + +- unnecessary operational burden. + +Too late: + +- painful migration for large tenants. + +### 4) Forgetting tenant-aware testing + +You should test: + +- host requests, +- tenant requests, +- invalid tenant requests, +- cross-tenant access attempts, +- background jobs with tenant context, +- cache behavior across tenants. + +## Final Thoughts + +ABP’s multi-tenancy support is one of the framework’s strongest features because it combines architectural clarity with practical runtime behavior. + +You get: + +- a clear host/tenant model, +- tenant resolution middleware, +- `ICurrentTenant` for runtime context, +- `IMultiTenant` for entity ownership, +- automatic data filtering, +- tenant-aware identity and module integration, +- support for shared, dedicated, and hybrid database strategies. + +That does not remove the need for good architecture. You still need to make deliberate choices about isolation, authentication, provisioning, caching, and operations. But ABP gives you a solid default path and a consistent set of abstractions, which is exactly what you want in a serious SaaS platform. + +If you are building an enterprise-grade SaaS application on .NET, ABP lets you spend more time on product logic and less time reinventing multi-tenancy infrastructure. + +## TL;DR + +- ABP multi-tenancy is built around `ICurrentTenant`, `IMultiTenant`, tenant resolution middleware, and automatic data filters. +- ABP supports shared database, database-per-tenant, and hybrid models, so you can match architecture to customer and compliance needs. +- Tenant resolution should happen before authentication, and subdomain resolution is usually the best default for SaaS apps. +- Tenant-aware design must extend beyond repositories to seeding, background jobs, caching, events, settings, and audit logging. +- The safest production approach is clear host/tenant separation, minimal filter bypassing, strong provisioning automation, and tenant-aware testing. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/cover.png b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/cover.png new file mode 100644 index 0000000000..b13a985e7e Binary files /dev/null and b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png new file mode 100644 index 0000000000..c8c2186287 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png new file mode 100644 index 0000000000..b49288411b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png new file mode 100644 index 0000000000..78d74772ad Binary files /dev/null and b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-4.png b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-4.png new file mode 100644 index 0000000000..c1568b4320 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-04-implementing-multitenancy-in-abp-framework-a-complete/inline-4.png differ diff --git a/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/Post.md b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/Post.md new file mode 100644 index 0000000000..e56e2b215b --- /dev/null +++ b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/Post.md @@ -0,0 +1,1452 @@ +# Implementing Multi-Tenancy in ABP Framework: A Complete Practical Guide + +Multi-tenancy is one of those architectural decisions that looks simple in a slide deck and becomes very real the moment you build a SaaS product. The hard part is not adding a `TenantId` column. The hard part is making tenant resolution, data isolation, authentication, seeding, background processing, caching, and database management work together without leaking data or creating operational pain. + +ABP Framework gives you a strong foundation for this. It has built-in multi-tenancy support, tenant-aware entities, automatic data filters, tenant resolution contributors, tenant management, and connection string infrastructure that supports shared database, database-per-tenant, and hybrid models. + +This guide explains both the concepts and the implementation details. It is written for intermediate to advanced .NET developers building real SaaS applications with ABP. + +## What Multi-Tenancy Means in SaaS + +A multi-tenant application serves multiple customers from the same application codebase and runtime while keeping each customer's data, users, configuration, and behavior isolated. + +In ABP terminology: + +- **Host side**: the application owner or platform operator +- **Tenant side**: each customer using the application +- **Current tenant**: the tenant context of the current request or operation + +### Single-tenant vs multi-tenant + +A **single-tenant** system usually means: + +- one deployment per customer +- isolated infrastructure by default +- simpler compliance story +- higher operational cost + +A **multi-tenant** system usually means: + +- one application serving many customers +- shared operational model +- lower cost per customer +- more architectural responsibility around isolation + +### Why multi-tenancy matters + +For SaaS products, multi-tenancy is often the difference between a manageable platform and an expensive collection of customer-specific deployments. + +Benefits: + +- lower infrastructure cost +- centralized updates and fixes +- faster onboarding of new customers +- easier feature rollout +- consistent operational model + +Challenges: + +- strict data isolation +- tenant-aware authentication and authorization +- scaling noisy tenants +- tenant-specific configuration +- migrations across shared or separate databases +- reporting across tenants + +### Why ABP simplifies this + +ABP removes a lot of repetitive plumbing: + +- `ICurrentTenant` exposes tenant context everywhere +- `IMultiTenant` enables automatic tenant filtering +- tenant resolution is built into the ASP.NET Core pipeline +- tenant management is available out of the box +- per-tenant connection strings support database-per-tenant and hybrid models +- identity, permissions, settings, features, and audit logging are tenant-aware + +That does not eliminate architectural decisions, but it gives you a consistent framework for implementing them correctly. + +## Understanding ABP Multi-Tenancy Architecture + +ABP's multi-tenancy model is practical: tenant context is resolved early, stored in the current execution scope, and then used by repositories, DbContexts, identity, settings, and other infrastructure. + +### Core concepts + +#### Tenant concept + +A tenant represents a customer organization in your SaaS system. A tenant typically has: + +- an `Id` +- a `Name` +- optional connection strings +- optional settings and features +- tenant-specific users and roles + +#### Host side + +The host side is where platform-wide operations happen: + +- creating and managing tenants +- assigning plans or subscriptions +- viewing cross-tenant analytics +- configuring defaults +- running migrations and maintenance + +Host-side operations usually run with `CurrentTenant.Id == null`. + +#### Tenant side + +The tenant side is where customer-specific operations happen: + +- managing users inside a tenant +- creating business data such as products, customers, and orders +- configuring tenant-level settings +- consuming tenant-specific features + +#### `ICurrentTenant` + +`ICurrentTenant` is the central service for reading the active tenant context. + +It exposes: + +- `Id` +- `Name` +- `IsAvailable` + +You will use it in application services, domain services, background jobs, seed contributors, and event handlers. + +#### Tenant resolution pipeline + +ABP resolves the tenant from the incoming request using contributors. Common sources include: + +- current user claims +- query string +- route values +- headers +- cookies +- domain or subdomain +- custom resolvers + +#### `IMultiTenant` + +Entities implementing `IMultiTenant` become tenant-aware. ABP applies automatic data filtering so tenant users only see rows belonging to their tenant. + +#### Data filters + +ABP uses data filters, typically backed by EF Core global query filters, to enforce tenant isolation for `IMultiTenant` entities. + +#### Tenant Management module + +ABP's Tenant Management module provides the infrastructure to create and manage tenants. In startup templates, this is often already integrated. In open-source ABP, core tenant management exists, while some advanced SaaS UI capabilities are part of ABP Commercial. + +### Request-to-data flow + +```mermaid +flowchart LR + A[Incoming HTTP Request] --> B[Tenant Resolution Contributors] + B --> C[Resolved Tenant Id or Name] + C --> D[ICurrentTenant Scope] + D --> E[Application Service] + E --> F[Repository / DbContext] + F --> G[IMultiTenant Data Filter] + G --> H[Tenant-Isolated Data] +``` + +### Host and tenant architecture view + +```mermaid +flowchart TB + Host[Host Side\nPlatform Owner] --> TM[Tenant Management] + Host --> Billing[Subscription / Plan Management] + Host --> Reporting[Cross-Tenant Reporting] + + TenantA[Tenant A] --> AppA[Application Modules] + TenantB[Tenant B] --> AppB[Application Modules] + TenantC[Tenant C] --> AppC[Application Modules] + + AppA --> Data[(Shared DB or Tenant DB)] + AppB --> Data + AppC --> Data +``` + +### How ABP applies tenant context + +Once the tenant is resolved: + +- repositories automatically filter `IMultiTenant` entities +- identity operations become tenant-specific +- settings and features can be resolved per tenant +- connection strings can switch dynamically for tenant databases +- audit logs can include tenant information + +This is why ABP multi-tenancy feels cohesive instead of bolted on. + + + +![Generated illustration](inline-1.png) + +## Multi-Tenancy Models Supported by ABP + +ABP supports three practical models. + +### 1) Single Database + +All tenants share one database. Tenant-specific rows are separated by `TenantId`. + +```mermaid +flowchart LR + T1[Tenant A] --> DB[(Shared Database)] + T2[Tenant B] --> DB + T3[Tenant C] --> DB +``` + +#### Advantages + +- lowest infrastructure cost +- simplest deployment model +- easiest migrations +- fast tenant provisioning +- easier aggregate reporting across tenants + +#### Disadvantages + +- weaker isolation than separate databases +- higher risk if filtering is misconfigured +- noisy tenants can affect others +- compliance requirements may be harder to satisfy + +### 2) Database Per Tenant + +Each tenant gets its own database. ABP switches connection strings based on tenant configuration. + +```mermaid +flowchart LR + T1[Tenant A] --> DB1[(Tenant A DB)] + T2[Tenant B] --> DB2[(Tenant B DB)] + T3[Tenant C] --> DB3[(Tenant C DB)] +``` + +#### Advantages + +- strongest data isolation +- easier tenant-specific backup and restore +- better compliance story +- easier per-tenant scaling and maintenance + +#### Disadvantages + +- more operational overhead +- migrations must run for every tenant database +- monitoring and backup complexity increases +- provisioning is slower than shared DB + +### 3) Hybrid Model + +Some tenants use the shared database, while premium or regulated tenants get dedicated databases. + +```mermaid +flowchart LR + T1[Tenant A] --> Shared[(Shared Database)] + T2[Tenant B] --> Shared + T3[Enterprise Tenant C] --> Dedicated[(Dedicated Database)] +``` + +#### Advantages + +- flexible cost/isolation tradeoff +- supports enterprise customers with stricter requirements +- lets you upgrade tenants without redesigning the app + +#### Disadvantages + +- most complex operational model +- more testing scenarios +- migration and support workflows become more involved + +### Comparison table + +| Model | Isolation | Cost | Operational Complexity | Reporting Across Tenants | Best Fit | +|---|---|---:|---:|---|---| +| Single Database | Medium | Low | Low | Easy | Early-stage SaaS, many small tenants | +| Database Per Tenant | High | High | High | Harder | Regulated or enterprise SaaS | +| Hybrid | Medium to High | Medium | High | Mixed | SaaS with tiered customer needs | + +### When to use / When NOT to use + +#### Use single database when + +- you need fast onboarding +- tenants are relatively small +- compliance requirements are moderate +- cross-tenant reporting matters + +#### Avoid single database when + +- customers require strict physical isolation +- one tenant can generate extreme load +- backup/restore must be tenant-specific + +#### Use database per tenant when + +- enterprise customers demand isolation +- you need tenant-specific maintenance windows +- compliance or residency rules are strict + +#### Avoid database per tenant when + +- you have thousands of tiny tenants +- your team is not ready for operational complexity +- your deployment and migration automation is immature + +#### Use hybrid when + +- you serve both SMB and enterprise customers +- you want a premium isolation tier +- you need a migration path from shared to dedicated databases + +#### Avoid hybrid when + +- your team wants the simplest possible operations +- you cannot invest in strong automation and observability + + + +![Generated illustration](inline-2.png) + +## Enabling Multi-Tenancy in ABP + +In ABP solutions, multi-tenancy is commonly controlled by a shared constant and configured through `AbpMultiTenancyOptions`. + +### `MultiTenancyConsts` + +Create or update `MultiTenancyConsts` in your `.Domain.Shared` project: + +```csharp +namespace Acme.Crm; + +public static class MultiTenancyConsts +{ + public const bool IsEnabled = true; +} +``` + +This keeps the setting centralized and easy to reference across modules. + +### Configure `AbpMultiTenancyOptions` + +In your web or HTTP API host module: + +```csharp +using Volo.Abp.MultiTenancy; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.IsEnabled = MultiTenancyConsts.IsEnabled; + }); +} +``` + +### Typical module configuration example + +```csharp +using Acme.Crm.MultiTenancy; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp; +using Volo.Abp.AspNetCore.MultiTenancy; +using Volo.Abp.Modularity; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm; + +[DependsOn( + typeof(AbpAspNetCoreMultiTenancyModule) +)] +public class CrmHttpApiHostModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + options.IsEnabled = MultiTenancyConsts.IsEnabled; + }); + + Configure(options => + { + options.TenantKey = "__tenant"; + }); + } + + public override void OnApplicationInitialization(ApplicationInitializationContext context) + { + var app = context.GetApplicationBuilder(); + + app.UseRouting(); + + if (MultiTenancyConsts.IsEnabled) + { + app.UseMultiTenancy(); + } + + app.UseAuthentication(); + app.UseAuthorization(); + + app.UseConfiguredEndpoints(); + } +} +``` + +### Relevant configuration files + +`appsettings.json` usually contains the default connection string and may contain tenant-related settings depending on your setup: + +```json +{ + "ConnectionStrings": { + "Default": "Server=localhost;Database=CrmShared;Trusted_Connection=True;TrustServerCertificate=True" + }, + "App": { + "SelfUrl": "https://localhost:44388" + } +} +``` + +If you use `DefaultTenantStore` for simple scenarios, tenant definitions can also be stored in configuration. In production, most real systems use the Tenant Management module and a database-backed tenant store. + +## Tenant Resolution Strategies + +Tenant resolution is where multi-tenancy becomes real. If the wrong tenant is resolved, everything after that is wrong too. + +ABP supports multiple strategies and lets you combine them. + +### Default resolution contributors + +Common contributors include: + +- current user claims +- query string: `?__tenant=acme` +- route value: `/api/acme/products` +- header: `__tenant: acme` +- cookie: `__tenant=acme` + +### Resolution flow through an HTTP request + +```mermaid +sequenceDiagram + participant Client + participant Middleware as MultiTenancy Middleware + participant Resolver as Tenant Resolvers + participant Store as ITenantStore + participant App as Application Service + participant Db as Repository/DbContext + + Client->>Middleware: HTTP Request + Middleware->>Resolver: Resolve tenant from claims/header/query/domain + Resolver->>Store: Find tenant by id or name + Store-->>Resolver: Tenant configuration + Resolver-->>Middleware: Active tenant + Middleware->>App: Execute under tenant scope + App->>Db: Query IMultiTenant entities + Db-->>App: Tenant-filtered data + App-->>Client: Response +``` + +### Subdomain and domain resolution + +Subdomain resolution is usually the cleanest production approach for SaaS. + +Example: `acme.mycrm.com` resolves tenant `acme`. + +```csharp +using Volo.Abp.MultiTenancy; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.AddDomainTenantResolver("{0}.mycrm.com"); + }); +} +``` + +You can also use full domain mapping patterns depending on your routing strategy. + +### Header-based resolution + +Useful for APIs, internal gateways, or integration testing. + +```csharp +Configure(options => +{ + options.TenantKey = "__tenant"; +}); +``` + +Request example: + +```http +GET /api/app/products HTTP/1.1 +Host: api.mycrm.com +__tenant: acme +Authorization: Bearer eyJ... +``` + +### Query string resolution + +Useful for demos and debugging, but not ideal as the primary production strategy. + +Example: + +```http +GET /api/app/products?__tenant=acme +``` + +### Route-based resolution + +If your API design includes tenant in the route, ABP can resolve from route values. + +Example route: + +```http +GET /api/acme/products +``` + +### Custom tenant resolver + +Sometimes tenant identification comes from a reverse proxy header, a custom JWT claim, or a partner integration contract. + +Create a custom contributor: + +```csharp +using System.Threading.Tasks; +using Microsoft.AspNetCore.Http; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.MultiTenancy; + +public class XTenantResolveContributor : TenantResolveContributorBase +{ + public const string ContributorName = "X-Tenant-Resolver"; + + public override string Name => ContributorName; + + public override Task ResolveAsync(ITenantResolveContext context) + { + var httpContext = context.ServiceProvider + .GetRequiredService() + .HttpContext; + + if (httpContext == null) + { + return Task.CompletedTask; + } + + var tenant = httpContext.Request.Headers["X-Tenant"].ToString(); + + if (!tenant.IsNullOrWhiteSpace()) + { + context.TenantIdOrName = tenant; + } + + return Task.CompletedTask; + } +} +``` + +Register it: + +```csharp +Configure(options => +{ + options.TenantResolvers.Insert(0, new XTenantResolveContributor()); +}); +``` + +### Practical guidance on resolver choice + +Prefer this order in production: + +1. subdomain/domain +2. authenticated user claim +3. trusted gateway header +4. route value +5. query string only for development or support scenarios + +Do not rely on query string alone for sensitive production flows. + + + +![Generated illustration](inline-3.png) + +## Creating Tenant-Aware Entities + +The most important rule is simple: if an entity belongs to a tenant, implement `IMultiTenant`. + +### Product entity example + +```csharp +using System; +using Volo.Abp.Domain.Entities.Auditing; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Products; + +public class Product : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; private set; } + public string Name { get; private set; } + public decimal Price { get; private set; } + + protected Product() + { + } + + public Product(Guid id, Guid? tenantId, string name, decimal price) + : base(id) + { + TenantId = tenantId; + Name = name; + Price = price; + } + + public void ChangePrice(decimal price) + { + Price = price; + } +} +``` + +### Customer entity example + +```csharp +using System; +using Volo.Abp.Domain.Entities.Auditing; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Customers; + +public class Customer : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; private set; } + public string CompanyName { get; private set; } + public string Email { get; private set; } + + protected Customer() + { + } + + public Customer(Guid id, Guid? tenantId, string companyName, string email) + : base(id) + { + TenantId = tenantId; + CompanyName = companyName; + Email = email; + } +} +``` + +### Order aggregate example + +```csharp +using System; +using System.Collections.Generic; +using Volo.Abp.Domain.Entities.Auditing; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Orders; + +public class Order : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; private set; } + public Guid CustomerId { get; private set; } + public DateTime OrderDate { get; private set; } + public List Lines { get; private set; } + + protected Order() + { + Lines = new List(); + } + + public Order(Guid id, Guid? tenantId, Guid customerId, DateTime orderDate) + : base(id) + { + TenantId = tenantId; + CustomerId = customerId; + OrderDate = orderDate; + Lines = new List(); + } +} + +public class OrderLine +{ + public Guid ProductId { get; private set; } + public int Quantity { get; private set; } + public decimal UnitPrice { get; private set; } + + protected OrderLine() + { + } + + public OrderLine(Guid productId, int quantity, decimal unitPrice) + { + ProductId = productId; + Quantity = quantity; + UnitPrice = unitPrice; + } +} +``` + +### Design considerations + +A few rules matter a lot: + +- keep `TenantId` immutable after creation whenever possible +- avoid moving entities between tenants +- ensure child entities belong to the same tenant as the aggregate root +- do not mix host-owned and tenant-owned data in the same aggregate casually +- index `TenantId` in large tables + +### How ABP filters tenant data automatically + +When an entity implements `IMultiTenant`, ABP applies a tenant filter automatically. If tenant `A` is active, queries only return rows where `TenantId == A`. + +That means this repository call: + +```csharp +var products = await _productRepository.GetListAsync(); +``` + +returns only the current tenant's products in a shared database model. + +### Host-owned entities + +Not every entity should implement `IMultiTenant`. + +Examples of host-owned entities: + +- subscription plans +- global feature definitions +- platform announcements +- tenant catalog records + +Those entities are intentionally shared or host-scoped. + +## Working with `ICurrentTenant` + +`ICurrentTenant` is the API you will use most often in multi-tenant business logic. + +### Reading current tenant information + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Products; + +public class ProductAppService : ApplicationService +{ + private readonly ICurrentTenant _currentTenant; + + public ProductAppService(ICurrentTenant currentTenant) + { + _currentTenant = currentTenant; + } + + public Task GetTenantInfoAsync() + { + var tenantId = _currentTenant.Id?.ToString() ?? "Host"; + var tenantName = _currentTenant.Name ?? "Host"; + + return Task.FromResult($"TenantId: {tenantId}, TenantName: {tenantName}"); + } +} +``` + +### Creating tenant-aware data + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.Domain.Repositories; +using Volo.Abp.Guids; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Products; + +public class ProductAppService : ApplicationService +{ + private readonly IRepository _productRepository; + private readonly IGuidGenerator _guidGenerator; + private readonly ICurrentTenant _currentTenant; + + public ProductAppService( + IRepository productRepository, + IGuidGenerator guidGenerator, + ICurrentTenant currentTenant) + { + _productRepository = productRepository; + _guidGenerator = guidGenerator; + _currentTenant = currentTenant; + } + + public async Task CreateAsync(string name, decimal price) + { + var product = new Product( + _guidGenerator.Create(), + _currentTenant.Id, + name, + price + ); + + await _productRepository.InsertAsync(product, autoSave: true); + } +} +``` + +### Changing tenant context temporarily + +Host-side services often need to execute logic for a specific tenant. + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Domain.Repositories; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Reporting; + +public class TenantReportService : ITransientDependency +{ + private readonly ICurrentTenant _currentTenant; + private readonly IRepository _productRepository; + + public TenantReportService( + ICurrentTenant currentTenant, + IRepository productRepository) + { + _currentTenant = currentTenant; + _productRepository = productRepository; + } + + public async Task GetProductCountAsync(Guid tenantId) + { + using (_currentTenant.Change(tenantId)) + { + return await _productRepository.GetCountAsync(); + } + } +} +``` + +### Nested tenant scopes + +Nested scopes are supported and useful when host-side orchestration calls tenant-specific logic. + +```csharp +using (_currentTenant.Change(null)) +{ + // host context + + using (_currentTenant.Change(tenantAId)) + { + // tenant A context + } + + using (_currentTenant.Change(tenantBId)) + { + // tenant B context + } +} +``` + +### Common mistake + +Do not cache `CurrentTenant.Id` globally or in singleton state. Tenant context is request or scope specific. + +## Data Isolation Mechanisms in ABP + +ABP's biggest value in multi-tenancy is not just storing tenant information. It is enforcing isolation consistently. + +### Automatic data filtering + +For `IMultiTenant` entities, ABP applies a tenant filter automatically. + +In a shared database model, a query conceptually becomes: + +```sql +SELECT Id, TenantId, Name, Price +FROM Products +WHERE TenantId = @CurrentTenantId +``` + +If soft delete is also enabled, it may look more like: + +```sql +SELECT Id, TenantId, Name, Price +FROM Products +WHERE TenantId = @CurrentTenantId + AND IsDeleted = 0 +``` + +The exact SQL depends on your provider and EF Core version, but the important point is that tenant filtering is automatic. + +### Tenant-specific repositories + +Standard repositories already respect tenant filters. In most cases, you do not need a special repository implementation just for tenant isolation. + +What you do need is discipline: + +- implement `IMultiTenant` +- avoid raw SQL that bypasses filters unless you know exactly what you are doing +- include tenant context in custom queries and projections + +### Disabling the tenant filter intentionally + +Host-side reporting or maintenance may require access to all tenants in a shared database. + +```csharp +using System.Collections.Generic; +using System.Threading.Tasks; +using Volo.Abp.Data; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Domain.Repositories; + +namespace Acme.Crm.Reporting; + +public class HostReportingService : ITransientDependency +{ + private readonly IDataFilter _dataFilter; + private readonly IRepository _productRepository; + + public HostReportingService(IDataFilter dataFilter, IRepository productRepository) + { + _dataFilter = dataFilter; + _productRepository = productRepository; + } + + public async Task> GetAllProductsAcrossTenantsAsync() + { + using (_dataFilter.Disable()) + { + return await _productRepository.GetListAsync(); + } + } +} +``` + +Important limitation: this only works for shared database scenarios. In database-per-tenant mode, there is no single query that can magically span all tenant databases. + +### Unit of Work integration + +Tenant context and data filters participate naturally in ABP's Unit of Work pipeline. That means: + +- repository operations inside the same UoW use the same tenant context +- transaction boundaries remain consistent +- switching tenant context inside a UoW should be done carefully and intentionally + +### Security implications + +Automatic filtering is a safety net, not a substitute for security design. + +You still need: + +- authorization checks +- tenant-aware cache keys +- careful raw SQL usage +- secure resolver configuration +- tests that verify cross-tenant isolation + +## Seeding Host and Tenant Data + +Seeding is where many multi-tenant applications become inconsistent. The fix is to make seeding explicit, idempotent, and tenant-aware. + +### `IDataSeedContributor` basics + +ABP uses `IDataSeedContributor` for modular data seeding. + +### Host and tenant seed contributor example + +```csharp +using System; +using System.Threading.Tasks; +using Acme.Crm.Products; +using Volo.Abp.Data; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Domain.Repositories; +using Volo.Abp.Guids; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Data; + +public class CrmDataSeedContributor : IDataSeedContributor, ITransientDependency +{ + private readonly IRepository _productRepository; + private readonly IGuidGenerator _guidGenerator; + private readonly ICurrentTenant _currentTenant; + + public CrmDataSeedContributor( + IRepository productRepository, + IGuidGenerator guidGenerator, + ICurrentTenant currentTenant) + { + _productRepository = productRepository; + _guidGenerator = guidGenerator; + _currentTenant = currentTenant; + } + + public async Task SeedAsync(DataSeedContext context) + { + using (_currentTenant.Change(context.TenantId)) + { + if (await _productRepository.GetCountAsync() > 0) + { + return; + } + + await _productRepository.InsertAsync( + new Product(_guidGenerator.Create(), context.TenantId, "Starter Plan", 49), + autoSave: true + ); + + await _productRepository.InsertAsync( + new Product(_guidGenerator.Create(), context.TenantId, "Professional Plan", 99), + autoSave: true + ); + } + } +} +``` + +### Seeding host data + +When `context.TenantId` is `null`, the contributor runs in host context. Use that for: + +- subscription plans +- global settings +- default editions or features +- host admin data + +### Seeding tenant data + +When `context.TenantId` has a value, seed tenant-specific defaults such as: + +- default CRM pipeline stages +- sample products +- tenant admin roles +- onboarding templates + +### Triggering seeding + +In migrator or startup code: + +```csharp +await dataSeeder.SeedAsync(new DataSeedContext()); +``` + +For a specific tenant: + +```csharp +await dataSeeder.SeedAsync(new DataSeedContext(tenantId)); +``` + +### Best seeding rules + +- make seeders idempotent +- never assume execution order unless you control it +- seed host and tenant data separately when needed +- in database-per-tenant mode, run migrations and seeding for each tenant database + +## Multi-Tenant Authentication and Identity + +Authentication in a multi-tenant app is not just about validating a user. It is about validating a user in the correct tenant context. + +ABP Identity is already tenant-aware: + +- `IdentityUser` includes `TenantId` +- `IdentityRole` includes `TenantId` +- permissions can target host, tenant, or both sides + +### Tenant-specific users and roles + +This means: + +- host admins can exist with `TenantId = null` +- tenant users belong to a specific tenant +- tenant roles are isolated from other tenants + +### Login flow + +A typical login flow looks like this: + +```mermaid +sequenceDiagram + participant User + participant Browser + participant App + participant Resolver as Tenant Resolver + participant Identity as Identity Module + + User->>Browser: Open tenant URL or login page + Browser->>App: Request with tenant context + App->>Resolver: Resolve tenant + Resolver-->>App: Tenant identified + User->>App: Submit username/password + App->>Identity: Authenticate within tenant scope + Identity-->>App: User validated for tenant + App-->>Browser: Auth cookie/token with tenant context +``` + +### Tenant switching + +Tenant switching usually happens through one of these patterns: + +- user visits a tenant-specific subdomain +- login page asks for tenant name first +- gateway injects tenant header +- token contains tenant claim after authentication + +For SaaS UX, subdomain-based switching is usually the cleanest. + +### Permissions by multi-tenancy side + +When defining permissions, ABP lets you specify whether a permission applies to: + +- host +- tenant +- both + +That matters for admin screens. For example: + +- tenant creation should be host-only +- customer management should be tenant-only +- profile management may be both + +## Database Per Tenant Configuration + +Database-per-tenant is where ABP's tenant infrastructure becomes especially valuable. + +### Connection string management + +Each tenant can have its own connection string. If a tenant-specific connection string exists, ABP uses it. Otherwise, it falls back to the default connection string. + +That gives you hybrid support naturally. + +### Tenant configuration storage with `ITenantStore` + +`ITenantStore` is responsible for retrieving tenant configuration. + +It can provide: + +- tenant id +- tenant name +- connection strings +- activation state and related metadata depending on implementation + +In simple setups, `DefaultTenantStore` can read from configuration. In production, tenant data is usually stored in the database through the Tenant Management module. + +### Example tenant configuration in code-backed store scenarios + +Conceptually, a tenant record may look like this: + +```json +{ + "id": "2f7f8f8d-8f8d-4f8d-9f8d-2f7f8f8d8f8d", + "name": "acme", + "connectionStrings": { + "Default": "Server=sql01;Database=Crm_Acme;User Id=app;Password=***;TrustServerCertificate=True" + } +} +``` + +### Production-ready considerations + +For database-per-tenant setups: + +- encrypt or securely store connection strings +- automate tenant database creation +- automate migrations per tenant +- monitor schema drift +- support backup and restore per tenant +- define a fallback strategy for unavailable tenant databases + +### Dynamic connection string resolution in practice + +In ABP, once the tenant is resolved and the tenant store returns a tenant-specific connection string, EF Core DbContexts use that connection automatically. You usually do not write custom DbContext switching logic yourself. + +That is one of the biggest practical benefits of using ABP instead of hand-rolling multi-tenancy. + +## Building a Sample SaaS CRM Application + +Let's connect the pieces with a realistic example. + +Imagine a SaaS CRM product with these modules: + +- host administration +- tenant administration +- customer management +- product catalog +- order management +- subscription management + +### Host administration + +Host users can: + +- create tenants +- assign subscription plans +- decide shared DB vs dedicated DB +- seed tenant defaults +- monitor tenant health + +### Tenant administration + +Tenant admins can: + +- manage users and roles +- configure CRM settings +- manage customers and products +- view tenant-specific reports + +### Domain model split + +Host-owned entities: + +- `SubscriptionPlan` +- `TenantSubscription` +- `TenantProvisioningLog` + +Tenant-owned entities implementing `IMultiTenant`: + +- `Customer` +- `Product` +- `Order` +- `Invoice` +- `SalesPipeline` + +### Provisioning flow + +A practical tenant onboarding flow: + +```mermaid +flowchart TD + A[Host Admin Creates Tenant] --> B[Store Tenant Record] + B --> C{Dedicated DB?} + C -- Yes --> D[Create Tenant Database] + C -- No --> E[Use Shared Database] + D --> F[Run Migrations] + E --> F[Run Shared/Tenant Seed Logic] + F --> G[Create Tenant Admin User] + G --> H[Tenant Ready] +``` + +### Example application service for tenant provisioning + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.Data; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Tenants; + +public class TenantProvisioningAppService : ApplicationService +{ + private readonly ITenantAppService _tenantAppService; + private readonly IDataSeeder _dataSeeder; + + public TenantProvisioningAppService( + ITenantAppService tenantAppService, + IDataSeeder dataSeeder) + { + _tenantAppService = tenantAppService; + _dataSeeder = dataSeeder; + } + + public async Task ProvisionAsync(string tenantName, string adminEmail) + { + var tenant = await _tenantAppService.CreateAsync(new TenantCreateDto + { + Name = tenantName, + AdminEmailAddress = adminEmail, + Password = "ChangeMe123*" + }); + + await _dataSeeder.SeedAsync(new DataSeedContext(tenant.Id)); + } +} +``` + +The exact DTOs and APIs may vary by ABP version and modules used, but the pattern is the same: create tenant, configure infrastructure, seed tenant data, then hand over to tenant admins. + + + +![Generated illustration](inline-4.png) + +## Advanced Multi-Tenant Scenarios + +Real SaaS systems need more than request-time filtering. + +### Background jobs in tenant context + +Background jobs must run under the correct tenant. + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.BackgroundJobs; +using Volo.Abp.DependencyInjection; +using Volo.Abp.MultiTenancy; + +namespace Acme.Crm.Jobs; + +public class RecalculateMetricsArgs +{ + public Guid TenantId { get; set; } +} + +public class RecalculateMetricsJob : AsyncBackgroundJob, ITransientDependency +{ + private readonly ICurrentTenant _currentTenant; + + public RecalculateMetricsJob(ICurrentTenant currentTenant) + { + _currentTenant = currentTenant; + } + + public override async Task ExecuteAsync(RecalculateMetricsArgs args) + { + using (_currentTenant.Change(args.TenantId)) + { + await Task.CompletedTask; + // tenant-aware work here + } + } +} +``` + +### Distributed events + +Include tenant information in event payloads or ensure handlers execute under the correct tenant scope. Otherwise, event consumers may process data in host context accidentally. + +### Caching per tenant + +Always include tenant id in cache keys. + +Bad: + +- `customer-list` + +Good: + +- `tenant:{tenantId}:customer-list` + +Without tenant-aware keys, cache leakage is almost guaranteed. + +### Feature management + +ABP feature management is useful for SaaS plans: + +- host defines available features +- tenants receive plan-based feature values +- premium tenants can unlock advanced modules + +Examples: + +- max users +- advanced reporting +- API access +- dedicated database eligibility + +### Setting management + +Settings can be layered: + +- application default +- host override +- tenant override +- user override where appropriate + +This is ideal for SMTP settings, branding, localization preferences, and business rules. + +### Audit logging + +Audit logs should capture tenant context so you can answer: + +- who changed what +- in which tenant +- from which client +- under which user identity + +### Localization + +Multi-tenant apps often need tenant-specific culture defaults, branding, or custom terminology. Keep localization extensible, but avoid turning every string into tenant-specific data unless there is a real business need. + +### Common pitfalls + +- forgetting `IMultiTenant` on a tenant-owned entity +- disabling tenant filters too broadly +- using raw SQL without tenant predicates +- not including tenant id in cache keys +- running jobs without tenant context +- migrating only the host database in DB-per-tenant mode +- allowing `TenantId` changes after entity creation +- trusting query string tenant resolution in production + +## Best Practices for Multi-Tenant ABP Applications + +Here are practical rules that hold up in production. + +1. **Implement `IMultiTenant` on every tenant-owned aggregate root.** Missing it is a classic data leak. +2. **Treat `TenantId` as immutable.** Moving data between tenants is rarely safe. +3. **Prefer subdomain or domain-based tenant resolution in production.** It is cleaner and harder to spoof than query strings. +4. **Use query string resolution mainly for development, support, or controlled integrations.** +5. **Index `TenantId` on large tables.** Shared database performance depends on it. +6. **Include tenant id in every cache key.** Never share cache entries across tenants accidentally. +7. **Test host context explicitly.** `CurrentTenant.Id == null` is a real execution mode. +8. **Test tenant context explicitly.** Verify that tenant A cannot see tenant B data. +9. **Be careful when disabling `IMultiTenant` filters.** Keep the scope as small as possible. +10. **Avoid raw SQL unless necessary.** If you use it, add tenant predicates yourself. +11. **Automate migrations for every tenant database.** Manual migration workflows do not scale. +12. **Make seed contributors idempotent.** Provisioning and recovery flows depend on repeatable seeding. +13. **Run background jobs under the correct tenant scope.** Pass tenant id in job args. +14. **Include tenant information in distributed event contracts or handler context.** +15. **Separate host-owned and tenant-owned entities clearly.** Ambiguous ownership creates bugs. +16. **Use feature management for plan-based SaaS behavior.** Do not hardcode plan logic everywhere. +17. **Use setting management for tenant-specific configuration.** Avoid custom config tables unless necessary. +18. **Secure tenant connection strings properly.** Treat them as secrets. +19. **Monitor tenant-level performance and failures.** One noisy tenant should be visible operationally. +20. **Design for tenant lifecycle operations.** Provisioning, suspension, upgrade, backup, restore, and deletion all matter. +21. **Plan reporting architecture early.** Cross-tenant reporting is easy in shared DB and harder in DB-per-tenant. +22. **Keep authorization tenant-aware.** Filtering data is not enough if permissions are wrong. +23. **Log tenant context in diagnostics and audit trails.** It speeds up support and incident response. +24. **Use hybrid architecture only when the business case is real.** It is powerful, but operationally expensive. +25. **Document your tenant model for the team.** Most multi-tenant bugs come from inconsistent assumptions. + +## Final Thoughts + +ABP does not make multi-tenancy trivial, but it makes it systematic. That matters a lot. Instead of scattering tenant checks across controllers, repositories, and middleware, you get a coherent model built around tenant resolution, current tenant context, data filters, tenant-aware identity, and connection string management. + +For most SaaS teams, the right path is: + +- start with shared database if your compliance and scale profile allow it +- model tenant ownership carefully with `IMultiTenant` +- use `ICurrentTenant` consistently +- automate seeding and provisioning +- move selected tenants to dedicated databases when the business case appears + +That is exactly the kind of evolution ABP supports well. + +## TL;DR + +- ABP provides built-in multi-tenancy with tenant resolution, `ICurrentTenant`, `IMultiTenant`, data filters, tenant management, and per-tenant connection strings. +- Shared database is simpler and cheaper; database-per-tenant gives stronger isolation; hybrid supports both at the cost of more complexity. +- Correct tenant resolution and entity modeling are the foundation of safe multi-tenancy in ABP. +- Use tenant-aware seeding, caching, background jobs, identity, and monitoring to avoid subtle production bugs. +- For real SaaS systems, ABP gives you the infrastructure you would otherwise spend months rebuilding. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/cover.png b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/cover.png new file mode 100644 index 0000000000..b7962924a9 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png new file mode 100644 index 0000000000..67da7fdaca Binary files /dev/null and b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png new file mode 100644 index 0000000000..9dfccabb2c Binary files /dev/null and b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png new file mode 100644 index 0000000000..a320e1a22a Binary files /dev/null and b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-4.png b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-4.png new file mode 100644 index 0000000000..1478c47a5e Binary files /dev/null and b/docs/en/Community-Articles/2026-06-05-implementing-multitenancy-in-abp-framework-a-complete/inline-4.png differ diff --git a/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-ai-agent.png b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-ai-agent.png new file mode 100644 index 0000000000..3c5bce22c0 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-ai-agent.png differ diff --git a/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-download-linux.png b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-download-linux.png new file mode 100644 index 0000000000..3f30213a31 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-download-linux.png differ diff --git a/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-solution-properties.png b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-solution-properties.png new file mode 100644 index 0000000000..913a193926 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-solution-properties.png differ diff --git a/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-solution-system.png b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-solution-system.png new file mode 100644 index 0000000000..be30260c71 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/abp-studio-solution-system.png differ diff --git a/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/cover.png b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/cover.png new file mode 100644 index 0000000000..d0cdbfa372 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/post.md b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/post.md new file mode 100644 index 0000000000..1a50443a8c --- /dev/null +++ b/docs/en/Community-Articles/2026-06-08-abp-studio-is-now-available-on-linux/post.md @@ -0,0 +1,116 @@ +# ABP Studio Is Now Available on Linux + +We are excited to announce that [ABP Studio](https://abp.io/studio), our cross-platform desktop application for ABP developers, is now available on Linux. + +With this release, Linux users can download and run ABP Studio as an **x64 AppImage**. This is an important step in making ABP Studio available wherever .NET and ABP developers prefer to work. + +## What can you do with ABP Studio? + +[ABP Studio](https://abp.io/studio) is a desktop application designed to make ABP development faster, easier, and more comfortable. It offers: + +* Easy creation of new solutions, from simple applications to distributed systems +* Visual architecture management for modular monolith and microservice solutions +* Solution exploration tools for entities, services, packages, and HTTP APIs +* Simplified running, debugging, and monitoring of multi-application solutions +* Kubernetes integration capabilities +* Built-in access to ABP-specific tooling and workflows + +The screenshots below were captured from ABP Studio on Linux through the AppImage. + +![ABP Studio solution system selection](abp-studio-solution-system.png) + +![ABP Studio solution properties step](abp-studio-solution-properties.png) + +## Linux Support Has Arrived + +ABP Studio has already been supporting multiple desktop environments, and now Linux joins that list. + +You can currently use ABP Studio on: + +* Windows x64 +* Windows ARM +* macOS Apple Silicon +* macOS Intel +* Linux x64 **(New!)** + +On Linux, the current distribution format is **AppImage**, which provides a practical way to distribute a desktop application across different Linux distributions without requiring a distribution-specific installer package. + +## What This Means for Developers + +Many ABP developers use Linux as their daily development environment. Until now, they needed to switch to another operating system to use ABP Studio. With Linux support, developers can now stay on their preferred platform and still benefit from ABP Studio's solution creation, architecture design, solution runner, monitoring, and integrated development experience. + +This is especially valuable for teams that already build and run their backend services on Linux-based environments and want to keep their development workflow aligned with that ecosystem. + +## AI Agent Is Available on Linux Too + +Another common question from the community has been whether ABP Studio AI Agent can be used on Linux machines. With this release, the answer is yes. + +Linux users can now use ABP Studio AI Agent in their own development environment. You can ask questions about your solution, plan implementation steps before changing code, and let the agent help with coding tasks while ABP Studio understands your ABP solution structure, build flow, and runtime context. + +![abp studio ai agent on linux](abp-studio-ai-agent.png) +For a deeper look at the AI Agent experience, see the original announcement: [Introducing ABP Studio AI Agent](https://abp.io/community/announcements/introducing-abp-studio-ai-agent-o1ni0toc). + +## Getting Started + +Downloading and running ABP Studio on Linux is simple: + +![abp studio download on linux](abp-studio-download-linux.png) + +1. Go to [abp.io/studio](https://abp.io/studio) +2. Download the **Linux x64 AppImage** +3. Open a terminal in the folder where the file was downloaded +4. Make the AppImage executable and run it + +```bash +chmod +x ./AbpStudio-stable.AppImage +./AbpStudio-stable.AppImage +``` + +Once launched, you can start using ABP Studio just like on the other supported platforms. + +## If the AppImage Does Not Run Directly + +Some Linux distributions may require additional runtime support for direct AppImage execution. + +For example, on some Ubuntu and Debian-based systems, you may need `libfuse2`: + +```bash +sudo apt update +sudo apt install libfuse2 +``` + +If FUSE is not available on your machine, you can still extract and run the AppImage manually: + +```bash +./AbpStudio-stable.AppImage --appimage-extract +./squashfs-root/AppRun +``` + +This fallback can be useful for testing or for environments where AppImage mounting is restricted. + +## Current Scope and Limitations + +This first Linux release is intentionally focused so we can deliver a reliable experience quickly. + +Here is the current scope: + +* Linux distribution is currently provided as an **x64 AppImage** +* **Linux ARM builds are not published yet** +* Depending on your Linux distribution, some native desktop or browser-related libraries may need to be installed +* When ABP Studio can detect a known native dependency problem, it tries to show guidance in the UI instead of leaving you with an unclear failure + +This means Linux support is ready to use today, and we will continue to improve the Linux experience in future releases. + +## A Better Cross-Platform Experience + +ABP Studio has always aimed to be the default way to start and develop ABP solutions. Linux support brings us closer to that goal by making the Studio experience more accessible across major desktop platforms. + +Whether you are creating a new solution, exploring packages and services, running multiple applications together, or monitoring runtime behavior, you can now do that on Linux too. + +## Conclusion + +We are happy to finally make ABP Studio available on Linux. + +This first release focuses on a practical and reliable target: **Linux x64 through AppImage**. It already opens the door for many developers who prefer Linux as their primary development environment, and it gives us a strong foundation to improve the Linux experience further. + +Please download it, try it in your daily workflow, and share your feedback with us. If you encounter a problem or want to request additional Linux targets like ARM, feel free to open an issue and let us know. diff --git a/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/Post.md b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/Post.md new file mode 100644 index 0000000000..a63ce8c77c --- /dev/null +++ b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/Post.md @@ -0,0 +1,496 @@ +ABP has supported multiple UI approaches for a long time, but many teams building line-of-business apps have been waiting for a first-class React option that feels native to the framework instead of bolted on. That is exactly what the ABP React template brings. + +If you are already using ABP for application services, modules, authentication, multi-tenancy, and code generation, the React template gives you a modern frontend stack without forcing you to hand-wire the same infrastructure in every project. You get React + TypeScript, a sensible project structure, generated API clients, authentication, localization, permission-aware UI, and a prebuilt admin experience that matches how ABP applications are typically built. + +This article explains what the ABP React template is, how it is structured, what you get out of the box, where it fits well, and what to watch for before adopting it. + +## What is the ABP React template? + +The ABP React template is the React UI option in ABP Framework's modern template system. It is available through ABP Studio v3.0+ and through the CLI when you create a modern solution. + +Typical commands look like this: + +```bash +abp new MyCompany.MyApp --modern --ui-framework react +``` + +Depending on your architecture, ABP supports React in these template types: + +- Layered: `app --modern` +- Single-layer: `app-nolayers --modern` +- Microservice: `microservice --modern` + +A very important detail: React UI is part of the modern template system. If you create a classic ABP solution, React UI is not included. + +At the time of its introduction, the React UI arrived as a beta/preview in 10.4.0-rc.1, with general availability planned for ABP 10.4 stable. So if you are evaluating it, make sure your ABP version and tooling align with the current docs. + +## The tech stack behind the template + +ABP did not build the React template around random choices. The stack is opinionated, but in a practical way that fits business applications. + +### Core frontend stack + +The template uses: + +- React +- TypeScript +- Vite +- TanStack Router +- TanStack Query +- Tailwind CSS +- shadcn/ui +- Radix UI +- Zod +- React Hook Form +- Axios +- Vitest + +That combination matters because it covers the common pain points in enterprise React apps: + +- Routing is structured and type-friendly. +- Server state is handled properly instead of scattered across components. +- Forms and validation are consistent. +- UI components are source-owned, not black-box widgets. +- Build and local development are fast. + +### Why this stack makes sense for ABP apps + +ABP applications usually have: + +- many CRUD screens +- authenticated users +- role and permission checks +- localization +- backend-driven DTOs +- modular features +- admin pages +- multi-tenant concerns + +The React template maps well to that reality. It is not trying to be a blank React starter. It is trying to be a production-ready frontend foundation for ABP-based applications. + + + +![Generated illustration](inline-1.png) + +## Project structure and template layout + +The structure depends on which ABP solution type you choose. + +### Layered and single-layer solutions + +In layered and single-layer templates, the React application lives under the solution root: + +```text +react/ +``` + +The Admin Console is embedded under the backend host and served from: + +```text +/admin-console/* +``` + +This setup is convenient when you want a unified application host and do not need to split the frontend into separate deployable apps. + +### Microservice solutions + +In the microservice template, the React application is placed under: + +```text +apps/react/ +``` + +The Admin Console is a separate app: + +```text +apps/react-admin-console/ +``` + +It is typically served through the Web Gateway using YARP. This is a better fit when your architecture already separates concerns across gateways and independently deployed services. + +### Common folders you will work with + +The frontend typically includes folders like these: + +- `components/` for layouts, reusable UI, and feature components +- `lib/` for auth, API setup, theme, and routing helpers +- `pages/` for page-level components +- `routes/` for route definitions +- `locales/` for translations + +This is a familiar structure for React teams, but it also reflects ABP conventions well enough that backend and frontend concerns stay aligned. + +## What you get out of the box + +The main value of the ABP React template is not that it uses React. Plenty of templates do that. The real value is that it wires React into ABP's application model. + + + +![Generated illustration](inline-2.png) + +## Authentication and authorization + +Authentication is one of the first places where many custom React frontends get messy. The ABP React template handles this using OpenID Connect with Authorization Code flow and PKCE against the ABP Auth Server. + +That means you get a setup suitable for modern browser-based applications without having to build the auth plumbing from scratch. + +### What is included + +Out of the box, you get: + +- OIDC integration +- route protection +- auth-related helpers and hooks +- support for ABP's authorization model +- permission-aware navigation and UI + +Permission-aware UI is especially useful in real applications. Instead of hardcoding role checks everywhere, you can use ABP's permission system in the frontend so menus, buttons, and screens reflect what the current user is actually allowed to do. + +For example, a user without the right permission should not see management actions just because the page rendered successfully. + +### Why this matters in practice + +In many projects, teams secure the backend correctly but forget to make the frontend behave consistently. The result is confusing UX: + +- users see actions they cannot execute +- menus show modules they cannot access +- pages fail after navigation instead of being guarded earlier + +The ABP React template reduces that mismatch. + +## API integration without hand-written client boilerplate + +One of the most useful parts of the template is the generated API client approach. + +ABP can generate frontend API clients from OpenAPI definitions, so your React app consumes backend endpoints using generated contracts instead of duplicated DTO definitions or hand-written fetch code. + +### Why this is a big deal + +Without generated clients, frontend/backend integration often drifts over time: + +- DTOs change but frontend types do not +- query strings are built inconsistently +- error handling varies by developer +- service layers become repetitive + +With the ABP React template, Axios is already set up and typically used together with TanStack Query. That gives you a cleaner pattern for data fetching, caching, invalidation, and loading states. + +A simplified example looks like this: + +```tsx +import { useQuery } from '@tanstack/react-query'; +import { identityUserControllerGetList } from '@/client'; + +export function UsersPage() { + const query = useQuery({ + queryKey: ['users'], + queryFn: () => identityUserControllerGetList({ maxResultCount: 10, skipCount: 0 }), + }); + + if (query.isLoading) return
Loading...
; + if (query.isError) return
Failed to load users.
; + + return ( +
    + {query.data.items.map((user) => ( +
  • {user.userName}
    • + ))} +
+ ); +} +``` + +The exact generated function names may vary based on your solution, but the pattern is the point: use generated contracts, wrap them with TanStack Query, and keep components focused on UI. + +## UI system and customization model + +The ABP React template uses shadcn/ui with Radix UI primitives and Tailwind CSS. That is a smart choice for teams that want control over their UI instead of being locked into a vendor component library. + +### Source-owned components + +This is one of the most important characteristics of the template: the frontend is source-owned. + +Your components, pages, and UI primitives live in your solution. They are not hidden behind proprietary packages that you cannot meaningfully adjust. + +That gives you freedom to: + +- restyle components +- change layouts +- modify route structure +- reorganize menus +- build your own design language on top +- customize page composition without fighting framework internals + +In practice, ABP places UI primitives under locations like `src/components/ui/`, so you can modify them directly when needed. + +### Theme support + +The template supports light, dark, and system themes. Styling is based on Tailwind CSS and CSS variables, which is a good fit for maintainable theming. + +If your team needs brand-level customization, this approach is usually easier to work with than overriding a large third-party theme package. + +### A practical trade-off + +Source-owned UI gives you control, but it also means you own consistency. If every developer changes shared components casually, the design system can drift quickly. + +The template gives you freedom. Your team still needs discipline. + + + +![Generated illustration](inline-3.png) + +## Forms, validation, and developer ergonomics + +Business apps live and die by form quality. The ABP React template uses React Hook Form and Zod, which is a solid setup for forms that need validation, predictable behavior, and clean code. + +This stack helps with: + +- schema-driven validation +- reusable form components +- clearer error handling +- less form boilerplate +- better TypeScript integration + +For ABP-style applications with lots of create/update dialogs and data-entry screens, that is a practical choice. + +A minimal example might look like this: + +```tsx +import { z } from 'zod'; +import { useForm } from 'react-hook-form'; +import { zodResolver } from '@hookform/resolvers/zod'; + +const schema = z.object({ + name: z.string().min(1, 'Name is required'), +}); + +type FormValues = z.infer; + +export function ProductForm() { + const form = useForm({ + resolver: zodResolver(schema), + defaultValues: { name: '' }, + }); + + const onSubmit = (values: FormValues) => { + console.log(values); + }; + + return ( +
+ +

{form.formState.errors.name?.message}

+ +
+ ); +} +``` + +The exact ABP project will likely wrap inputs with shared UI components, but the workflow remains familiar. + +## Localization and multi-tenancy + +If you are building a SaaS product or an internal enterprise application for multiple regions, this part matters a lot. + +The ABP React template includes support for: + +- localization with i18next +- ABP localization resources and keys +- culture information from the backend +- end-to-end multi-tenant scenarios + +This is where ABP has always been strong, and the React template carries that strength into the frontend. + +### Why this matters + +Many React starters look great until you need to answer these questions: + +- Where does the current tenant come from? +- How does the frontend know which culture is active? +- How are permission and tenant context propagated to API requests? +- How do I keep localization aligned with backend resources? + +With the ABP React template, these are not afterthoughts. + + + +![Generated illustration](inline-4.png) + +## The built-in Admin Console + +Another notable piece is the React-based Admin Console provided through `Volo.Abp.AdminConsole`. + +This gives you a prebuilt admin UI for common ABP modules such as: + +- Identity +- Settings +- Audit Logs +- and other standard management features + +### Why it is useful + +For many projects, admin screens are necessary but not differentiating. You need them, but you do not want to spend weeks rebuilding infrastructure screens that ABP already understands well. + +The Admin Console helps you start with a solid baseline. + +### One thing to be clear about + +The Admin Console is managed by ABP and is often intended to be used mostly as-is. If your project requires heavy customization there, you should evaluate that path carefully before assuming it behaves like the rest of your source-owned frontend. + +That is not necessarily a problem, but it is worth knowing early. + +## Runtime configuration with dynamic-env.json + +A practical detail that deserves more attention is `dynamic-env.json` under the public folder. + +This file allows runtime configuration for values such as: + +- OAuth issuer +- client ID +- API base URLs +- related environment settings + +That means you can adapt environment-specific settings without rebuilding the frontend for every deployment target. + +For teams deploying across dev, staging, and production, this is much more convenient than baking every environment value into the build. + +### Real-world example + +Suppose your staging environment uses different hostnames and an alternate auth server URL. With runtime configuration, you can update those values at deployment time instead of producing another frontend artifact just for staging. + +That said, when you change URLs or hostnames, remember that runtime config is only part of the story. You also need to update OpenIddict client settings such as redirect URIs and related auth configuration. + +## Development workflow + +The local development loop is straightforward. + +### Running the application + +You typically: + +1. start the backend host with `dotnet run` +2. go to the React app folder +3. install dependencies with `npm install` +4. start the frontend with `npm run dev` + +Vite keeps frontend startup and rebuild times fast, which helps a lot when you are iterating on pages and forms. + +### Production build + +For production, you build the frontend with: + +```bash +npm run build +``` + +This outputs the app to `dist/`. How it is served depends on the template: + +- via the backend host in simpler solution structures +- via a gateway or separate frontend host in microservice setups + +### Testing + +The template uses Vitest and React Testing Library, with scripts such as: + +- `npm run test` +- `npm run test:coverage` + +This is a good baseline. It encourages teams to test UI behavior without dragging in slow or outdated frontend test setups. + +## When to use the ABP React template + +The ABP React template is a strong fit when your project already wants ABP's backend capabilities and your team prefers React on the frontend. + +Use it when: + +- you are starting a new ABP project with a modern template +- you want React + TypeScript with ABP conventions already wired in +- you need authentication, permissions, localization, and multi-tenancy from day one +- you want generated API clients instead of duplicated DTOs +- you prefer source-owned UI components +- your app is admin-heavy, form-heavy, or module-heavy + +### Good fit examples + +- SaaS admin portals +- internal enterprise dashboards +- operations and management systems +- modular business applications with many CRUD workflows +- ABP-based platforms needing a modern React frontend + +## When not to use it + +It is not the right default for every case. + +Avoid or reconsider it when: + +- you are on a classic ABP template and do not want to migrate to modern templates +- your team wants a very custom frontend architecture unrelated to ABP conventions +- your application is mostly marketing pages or content-driven public pages +- you do not need ABP's auth, permission, module, or tenant model +- you expect deep customization of every built-in admin experience without validating the boundaries first + +### A practical warning + +Do not choose the template just because it uses React. Choose it because you want React inside the ABP ecosystem. + +That distinction matters. + +## Common pitfalls and things to check early + +The template is productive, but there are a few details worth validating at the beginning of a project. + +### 1. Make sure you are using a modern template + +This is the most common source of confusion. React UI is for modern templates. If you create a classic solution, the React UI option is not there. + +### 2. Align auth settings across environments + +If you change frontend URLs, callback paths, ports, or hostnames, update: + +- runtime frontend configuration +- OpenIddict client redirect URIs +- post-logout redirect URIs if applicable +- any gateway or proxy configuration involved + +A lot of login issues come from partial updates here. + +### 3. Treat source-owned UI like a product asset + +Because the UI code is in your solution, it is easy to modify. That is good. It also means teams can slowly lose consistency unless they define clear frontend standards. + +### 4. Understand the Admin Console boundary + +The Admin Console is valuable, but it is not the same customization surface as your app pages. If extensive admin customization is a requirement, validate that path before committing architecture decisions around it. + +## Why the ABP React template is different from a plain React starter + +A plain React starter gives you flexibility, but also leaves many critical concerns unresolved. The ABP React template starts from a different assumption: most business applications need the same infrastructure pieces, and those pieces should work together. + +Compared to a generic starter, ABP gives you tighter integration for: + +- auth and authorization +- generated API clients +- localization +- tenant-aware applications +- modular backend alignment +- admin capabilities +- solution-level conventions + +That makes it less minimal than a blank React scaffold, but much more useful for real ABP projects. + +## Final thoughts + +The ABP React template is not interesting because it says React on the label. It is interesting because it brings React into ABP's application model in a way that feels intentional. + +You get a modern frontend stack, source-owned customization, generated client integration, and the ABP features many teams actually need in production: permissions, localization, multi-tenancy, and admin tooling. + +If your team already values ABP on the backend and wants React on the frontend, this template is one of the fastest ways to get to a serious foundation without spending the first sprint rebuilding plumbing. + +## TL;DR + +- The ABP React template is available in ABP's modern template system, not classic templates. +- It uses a practical stack: React, TypeScript, Vite, TanStack Router/Query, shadcn/ui, Tailwind, Zod, and Axios. +- Key strengths are generated API clients, OIDC auth, permission-aware UI, localization, and multi-tenancy. +- The frontend is source-owned, which gives you flexibility but also requires discipline. +- It is a strong choice for ABP-based business apps, especially admin-heavy and SaaS-style applications. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/cover.png b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/cover.png new file mode 100644 index 0000000000..030338577f Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-1.png b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-1.png new file mode 100644 index 0000000000..32b829bbf4 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-2.png b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-2.png new file mode 100644 index 0000000000..11d686df90 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-3.png b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-3.png new file mode 100644 index 0000000000..91d7568b10 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-4.png b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-4.png new file mode 100644 index 0000000000..73bc2d57fc Binary files /dev/null and b/docs/en/Community-Articles/2026-06-08-getting-started-with-the-abp-react-template/inline-4.png differ diff --git a/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/Post.md b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/Post.md new file mode 100644 index 0000000000..5997617f4c --- /dev/null +++ b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/Post.md @@ -0,0 +1,1363 @@ +# Implementing Multi-Tenancy in ABP Framework: A Complete Practical Guide + +Multi-tenancy is one of those features that looks straightforward on a whiteboard and gets complicated the moment real customers, databases, authentication, billing, and background jobs enter the picture. + +If you are building a SaaS application on ASP.NET Core, you need more than a `TenantId` column scattered across a few tables. You need a consistent way to resolve the tenant for each request, isolate data safely, seed tenant-specific records, handle host-level administration, and support different deployment models as your product grows. + +This is where ABP Framework helps a lot. Multi-tenancy is built into the framework's core architecture: request pipeline, entity model, data filters, tenant store, identity integration, settings, features, and modules all understand the concept of host and tenant. + +In this guide, we will go from architecture to implementation. The focus is practical: how ABP multi-tenancy works, how to enable it correctly, how to model tenant-aware entities, how request resolution flows through the app, and how to build a real SaaS CRM application on top of it. + +## Introduction to Multi-Tenancy + +Multi-tenancy means a single software application serves multiple customers, where each customer is treated as a separate tenant. A tenant usually has its own users, roles, settings, data, and operational boundaries. + +In SaaS terms: + +- The **host** is the software provider, the platform owner. +- A **tenant** is a customer organization using the system. + +### Single-tenant vs multi-tenant architecture + +A **single-tenant** system typically gives each customer a separate deployed application instance, often with a separate database and infrastructure boundary. + +A **multi-tenant** system shares the application runtime and, depending on the model, may share databases too. + +**Single-tenant** usually gives: + +- simpler isolation reasoning +- easier customer-specific customization +- higher infrastructure cost +- more operational duplication + +**Multi-tenant** usually gives: + +- better resource efficiency +- easier centralized updates +- lower cost per customer +- more complexity around isolation and scaling + +### Why multi-tenancy matters for SaaS + +Most SaaS products eventually need: + +- centralized onboarding +- tenant-specific authentication and authorization +- subscription plans and features +- controlled data isolation +- operational efficiency at scale + +Without a solid multi-tenancy model, these become ad hoc implementations. That tends to create subtle security bugs and hard-to-maintain code. + +### Advantages and challenges + +**Advantages** + +- Better infrastructure utilization +- Centralized deployment and upgrades +- Lower operating cost per customer +- Easier platform-wide monitoring and governance +- Feature and setting management per tenant + +**Challenges** + +- Preventing cross-tenant data leakage +- Tenant-aware caching and background jobs +- Managing request resolution correctly +- Handling database-per-tenant operations +- Supporting host-side administration cleanly + +### Why ABP Framework simplifies it + +ABP does not treat multi-tenancy as a naming convention. It treats it as a first-class capability. + +You get: + +- built-in tenant resolution pipeline +- `ICurrentTenant` for runtime tenant context +- `IMultiTenant` support for entities +- automatic data filters +- host and tenant side concepts across modules +- tenant management module and tenant store abstraction +- identity, features, settings, and permissions that understand tenants + +That combination is what makes ABP especially useful for serious SaaS applications. + +## Understanding ABP Multi-Tenancy Architecture + +At the center of ABP multi-tenancy are a few concepts that appear everywhere in the application lifecycle. + +### Tenant concept + +A tenant is usually a customer organization. In a CRM product, one tenant might be `acme`, another might be `globex`. Each one has: + +- its own users +- its own roles +- its own application data +- optionally its own connection string +- optionally its own features and settings + +The host is not just another tenant. It is the platform owner context. + +### Host side vs tenant side + +ABP explicitly distinguishes between host-side and tenant-side operations. + +**Host side** typically includes: + +- creating and managing tenants +- viewing subscription status +- assigning features and plans +- managing platform-level settings +- running cross-tenant operations + +**Tenant side** typically includes: + +- managing tenant users and roles +- working with tenant business data +- updating tenant settings +- tenant-specific administration + +In shared database setups, host-side records usually have `TenantId == null`. Tenant-side records have a concrete `TenantId`. + +### `ICurrentTenant` + +`ICurrentTenant` is the runtime source of truth for tenant context. + +It exposes: + +- `Id` +- `Name` +- `IsAvailable` + +In application services, domain services, controllers, and many ABP base classes, it is already available or easy to inject. + +Example: + +```csharp +public class DashboardAppService : ApplicationService +{ + public string GetContextInfo() + { + if (!CurrentTenant.IsAvailable) + { + return "Host context"; + } + + return $"Tenant: {CurrentTenant.Name} ({CurrentTenant.Id})"; + } +} +``` + +If `CurrentTenant.Id` is `null`, you are in host context. + +### Tenant resolution pipeline + +Before your application logic runs, ABP tries to determine which tenant the request belongs to. + +ABP uses a set of tenant resolvers, executed in order. Common sources include: + +- current user claims +- query string parameter `__tenant` +- route value `__tenant` +- header `__tenant` +- cookie `__tenant` +- domain or subdomain pattern + +The middleware `UseMultiTenancy()` plugs this into the ASP.NET Core pipeline. + +Because diagram DSLs are not suitable here, the request flow is best explained in steps: + +1. An HTTP request reaches the ASP.NET Core pipeline. +2. ABP multi-tenancy middleware runs. +3. Configured tenant resolvers inspect the request. +4. If a tenant identifier is found, ABP loads tenant information from the tenant store. +5. `ICurrentTenant` is populated for the rest of the request scope. +6. Repository queries and data filters automatically use the current tenant context. +7. Authentication, authorization, settings, features, and caches can all behave tenant-aware. + +### `IMultiTenant` + +`IMultiTenant` marks an entity as tenant-aware. + +It defines: + +```csharp +public interface IMultiTenant +{ + Guid? TenantId { get; } +} +``` + +In practice, entities implementing this interface participate in ABP's multi-tenant data filtering behavior. + +### Data filters + +ABP automatically applies data filters to entities implementing `IMultiTenant`. In a shared database model, queries are filtered so the current tenant sees only its own records. + +That means code like this: + +```csharp +var products = await _productRepository.GetListAsync(); +``` + +will only return the current tenant's products when `Product` implements `IMultiTenant`. + +If you are on host side and intentionally need cross-tenant access, you can disable the filter temporarily: + +```csharp +using (_dataFilter.Disable()) +{ + var allProducts = await _productRepository.GetListAsync(); +} +``` + +This is powerful and dangerous. Use it carefully. + +### Tenant Management module + +ABP's Tenant Management module gives you a production-ready foundation for tenant administration. + +It provides: + +- tenant CRUD operations +- tenant connection strings +- tenant store integration +- management UI in ABP-based solutions +- admin user provisioning support + +In real projects, this removes a lot of plumbing work. + + + +![Generated illustration](inline-1.png) + +## Multi-Tenancy Models Supported by ABP + +ABP supports all common SaaS multi-tenancy models. + +### 1. Single database + +All tenants share one database and typically the same schema. Data is separated logically using `TenantId` and data filters. + +**How it works** + +- one database for host and tenant data +- tenant-aware tables contain a `TenantId` +- ABP filters queries automatically based on current tenant + +**Advantages** + +- simplest to start with +- cheapest operationally +- easiest schema migration story +- simpler reporting when all tenant data is in one place + +**Disadvantages** + +- strongest need for careful isolation +- noisy-neighbor effects at database level +- scaling limits can appear earlier +- large shared tables can become operational pain points + +### 2. Database per tenant + +Each tenant gets a dedicated database. The host may still use a separate shared database for platform-level data. + +**How it works** + +- tenant-specific connection strings are stored per tenant +- ABP resolves the current tenant, then resolves the tenant's database connection +- repositories work in the tenant's database context + +**Advantages** + +- stronger isolation +- easier compliance story for some customers +- easier tenant-specific restore and backup +- tenant-level scaling options + +**Disadvantages** + +- more complex provisioning +- harder cross-tenant reporting +- more migration orchestration +- greater operational overhead + +### 3. Hybrid model + +Some tenants share a database, others get dedicated databases. + +This is common in enterprise SaaS. + +**Typical scenario** + +- small and mid-market tenants use shared infrastructure +- premium or regulated customers get dedicated databases +- host still manages everything through the same application codebase + +**Advantages** + +- flexible cost model +- premium isolation for large customers +- efficient default for smaller tenants + +**Disadvantages** + +- highest operational complexity +- more provisioning paths to maintain +- more testing combinations + +### Comparison + +| Model | Database layout | Strengths | Weaknesses | Best fit | +|---|---|---|---|---| +| Single database | All tenants share one DB | Simple, cheap, easy migrations | Lower isolation, shared load | Early-stage SaaS, internal SaaS | +| Database per tenant | One DB per tenant | Strong isolation, restore flexibility | Higher ops cost, harder reporting | Enterprise SaaS, regulated environments | +| Hybrid | Shared for some, dedicated for others | Flexible pricing and isolation | Most complex to operate | Growing SaaS platforms | + +### When to use / When NOT to use + +**Use single database when:** + +- you are launching an MVP or early SaaS +- tenant counts are moderate +- compliance requirements are manageable +- operational simplicity matters most + +**Do not use single database when:** + +- customers require physical data isolation +- large tenants can dominate database resources +- tenant-specific backup and restore is mandatory + +**Use database per tenant when:** + +- compliance and isolation matter a lot +- customers pay enough to justify dedicated infrastructure +- you need tenant-level backup, restore, and scaling + +**Do not use database per tenant when:** + +- you are optimizing for low operational overhead +- your team is not ready to automate migrations and provisioning +- most tenants are very small and margins are tight + +**Use hybrid when:** + +- you want shared infrastructure by default +- you have a premium enterprise tier +- you need a migration path from shared to dedicated tenants + +**Do not use hybrid when:** + +- your platform operations are still immature +- you want to minimize architectural branching + + + +![Generated illustration](inline-2.png) + +## Enabling Multi-Tenancy in an ABP Application + +Multi-tenancy is off by default in the framework, although ABP startup templates commonly enable it for you. + +A clean approach is to centralize the flag in `MultiTenancyConsts`. + +### `MultiTenancyConsts` + +```csharp +namespace Acme.Crm; + +public static class MultiTenancyConsts +{ + public const bool IsEnabled = true; +} +``` + +### Configure `AbpMultiTenancyOptions` + +In your HTTP API Host module: + +```csharp +using Volo.Abp.MultiTenancy; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.IsEnabled = MultiTenancyConsts.IsEnabled; + }); +} +``` + +### Add middleware + +In `OnApplicationInitialization`: + +```csharp +public override void OnApplicationInitialization(ApplicationInitializationContext context) +{ + var app = context.GetApplicationBuilder(); + var env = context.GetEnvironment(); + + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + + app.UseRouting(); + app.UseAuthentication(); + + if (MultiTenancyConsts.IsEnabled) + { + app.UseMultiTenancy(); + } + + app.UseAuthorization(); + app.UseConfiguredEndpoints(); +} +``` + +A practical rule: place `UseMultiTenancy()` after authentication setup and before application endpoints. + +### Configuration example + +If you use ABP's default tenant store from configuration in a simple setup, you can define tenants in `appsettings.json`. + +```json +{ + "TenantManagement": { + "Tenants": [ + { + "Id": "11111111-1111-1111-1111-111111111111", + "Name": "acme" + }, + { + "Id": "22222222-2222-2222-2222-222222222222", + "Name": "globex" + } + ] + } +} +``` + +In real applications, the Tenant Management module is usually a better choice than static config. + +## Tenant Resolution Strategies + +Tenant resolution is where many real-world mistakes happen. The framework can only isolate data correctly if the tenant is resolved correctly. + +### Default resolvers + +ABP can resolve tenant information from: + +- authenticated user claims +- query string: `__tenant` +- route value: `__tenant` +- header: `__tenant` +- cookie: `__tenant` + +### Configure resolver options + +```csharp +using Volo.Abp.AspNetCore.MultiTenancy; +using Volo.Abp.MultiTenancy; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.AddDefaultResolvers(); + }); +} +``` + +### Subdomain resolution + +Subdomain-based tenant resolution is common in SaaS. + +Examples: + +- `acme.mycrm.com` +- `globex.mycrm.com` + +Configuration: + +```csharp +Configure(options => +{ + options.AddDomainTenantResolver("{0}.mycrm.com"); +}); +``` + +Now a request to `acme.mycrm.com` resolves tenant name `acme`. + +### Domain resolution + +You can also map full domains, especially for custom domains. + +For example, a tenant might use: + +- `crm.acme.com` +- `sales.globex.io` + +You typically handle these with custom tenant resolution logic backed by your own domain mapping table. + +### Header-based resolution + +Useful for internal APIs, gateways, or backend-to-backend communication. + +Example request: + +```http +GET /api/products +__tenant: acme +``` + +This is convenient, but do not trust arbitrary tenant headers from public traffic unless a trusted gateway injects them. + +### Query string resolution + +Useful for demos, diagnostics, or very simple integrations. + +Example: + +```text +https://api.mycrm.com/api/products?__tenant=acme +``` + +It works, but it is not usually the best production UX. + +### Route-based resolution + +You can support routes like: + +```text +/api/{__tenant}/products +``` + +This is more common in APIs than browser-based SaaS frontends. + +### Custom tenant resolver + +For custom logic, implement a tenant resolve contributor. + +```csharp +using System.Threading.Tasks; +using Volo.Abp.MultiTenancy; + +public class ApiKeyTenantResolveContributor : TenantResolveContributorBase +{ + public override string Name => "ApiKey"; + + public override Task ResolveAsync(ITenantResolveContext context) + { + var httpContext = context.GetHttpContext(); + var apiKey = httpContext?.Request.Headers["X-Api-Key"].ToString(); + + if (string.IsNullOrWhiteSpace(apiKey)) + { + return Task.CompletedTask; + } + + if (apiKey == "acme-key") + { + context.Handled = true; + context.TenantIdOrName = "acme"; + } + + return Task.CompletedTask; + } +} +``` + +Register it: + +```csharp +Configure(options => +{ + options.TenantResolvers.Insert(0, new ApiKeyTenantResolveContributor()); +}); +``` + +Putting your resolver at the beginning gives it priority. + +### How tenant identification flows through an HTTP request + +A practical request flow looks like this: + +1. Browser requests `https://acme.mycrm.com/api/app/customers`. +2. ASP.NET Core receives the request. +3. `UseMultiTenancy()` runs. +4. Domain resolver extracts `acme` from the host. +5. ABP loads tenant metadata from `ITenantStore`. +6. `ICurrentTenant.Id` is set for the request scope. +7. Authentication and authorization proceed in tenant context. +8. Repositories apply the tenant data filter. +9. Only `acme` data is returned. + +That is the core path you should have in mind when debugging tenant issues. + + + +![Generated illustration](inline-3.png) + +## Creating Tenant-Aware Entities + +The heart of tenant data isolation is entity design. + +### Using `IMultiTenant` + +Let's model a SaaS CRM with `Product`, `Customer`, and `Order`. + +```csharp +using System; +using Volo.Abp.Domain.Entities.Auditing; +using Volo.Abp.MultiTenancy; + +public class Product : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; set; } + public string Name { get; private set; } + public decimal Price { get; private set; } + + protected Product() + { + } + + public Product(Guid id, string name, decimal price, Guid? tenantId) + : base(id) + { + TenantId = tenantId; + Name = name; + Price = price; + } +} +``` + +```csharp +public class Customer : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; set; } + public string Name { get; private set; } + public string Email { get; private set; } + + protected Customer() + { + } + + public Customer(Guid id, string name, string email, Guid? tenantId) + : base(id) + { + TenantId = tenantId; + Name = name; + Email = email; + } +} +``` + +```csharp +public class Order : FullAuditedAggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; set; } + public Guid CustomerId { get; private set; } + public decimal TotalAmount { get; private set; } + + protected Order() + { + } + + public Order(Guid id, Guid customerId, decimal totalAmount, Guid? tenantId) + : base(id) + { + TenantId = tenantId; + CustomerId = customerId; + TotalAmount = totalAmount; + } +} +``` + +### Aggregate root considerations + +In a multi-tenant model: + +- aggregate roots should clearly belong to host or tenant side +- child entities usually follow the aggregate root's tenant boundary +- references between aggregates from different tenants should be avoided +- host-side entities should not accidentally depend on tenant-scoped data + +A simple rule is helpful: if an entity exists only inside a tenant's business workflow, make it tenant-aware. + +### Automatically assigning `TenantId` + +In application services, use `CurrentTenant.Id` when creating tenant-owned entities. + +```csharp +public class ProductAppService : ApplicationService +{ + private readonly IRepository _productRepository; + + public ProductAppService(IRepository productRepository) + { + _productRepository = productRepository; + } + + public async Task CreateAsync(string name, decimal price) + { + var product = new Product( + GuidGenerator.Create(), + name, + price, + CurrentTenant.Id + ); + + await _productRepository.InsertAsync(product, autoSave: true); + return product.Id; + } +} +``` + +### How ABP filters tenant data automatically + +Suppose `acme` is the current tenant. + +This code: + +```csharp +var customers = await _customerRepository.GetListAsync(); +``` + +will generate SQL conceptually similar to: + +```sql +SELECT * +FROM CrmCustomers +WHERE TenantId = @CurrentTenantId +``` + +If the filter is disabled from host context, the generated query may no longer include the tenant predicate. + +The exact SQL depends on EF Core and your provider, but the practical point is the same: ABP injects the tenant boundary for you. + +## Working with `ICurrentTenant` + +`ICurrentTenant` is not just for reading tenant info. It is also how you intentionally switch tenant context during controlled operations. + +### Reading current tenant information + +```csharp +public class TenantInfoAppService : ApplicationService +{ + public object GetCurrent() + { + return new + { + CurrentTenant.Id, + CurrentTenant.Name, + CurrentTenant.IsAvailable + }; + } +} +``` + +### Changing tenant context + +A host-side admin service may need to run work inside a specific tenant. + +```csharp +public class TenantReportingAppService : ApplicationService +{ + private readonly IRepository _customerRepository; + + public TenantReportingAppService(IRepository customerRepository) + { + _customerRepository = customerRepository; + } + + public async Task GetCustomerCountAsync(Guid tenantId) + { + using (CurrentTenant.Change(tenantId)) + { + return await _customerRepository.GetCountAsync(); + } + } +} +``` + +### Switching to host context + +```csharp +using (CurrentTenant.Change(null)) +{ + // host-side logic here +} +``` + +### Nested tenant scopes + +ABP restores the previous tenant automatically after the `using` block ends. + +```csharp +using (CurrentTenant.Change(tenantA)) +{ + // tenant A + + using (CurrentTenant.Change(tenantB)) + { + // tenant B + } + + // back to tenant A +} +``` + +This matters in background jobs, cross-tenant maintenance tasks, and provisioning routines. + +## Data Isolation Mechanisms in ABP + +ABP's multi-tenancy model is more than a `TenantId` field. + +### Automatic data filtering + +If an entity implements `IMultiTenant`, ABP applies a filter automatically. This reduces the amount of repetitive tenant checks you need to write manually. + +That said, you should still think in layers: + +- **Resolution** determines who the tenant is. +- **Filtering** limits data access. +- **Authorization** controls what the current user can do. +- **Database strategy** defines physical or logical isolation. + +These layers complement each other. + +### Tenant-specific repositories + +You usually do not need separate repository implementations just to filter by tenant. The standard repository already respects the active tenant context. + +But custom repository methods still need discipline. If you write raw SQL, disable filters, or query across host boundaries, you must preserve isolation intentionally. + +### Unit of Work integration + +ABP's Unit of Work operates inside the current tenant context. That means reads and writes in the same UoW use the same tenant scope unless you explicitly change it. + +This is one reason `CurrentTenant.Change(...)` is safer than trying to pass tenant identifiers manually through every service method. + +### Security implications + +Multi-tenancy bugs are often security bugs. + +Be especially careful with: + +- host-side screens that disable tenant filters +- header and query-string based tenant resolution in public endpoints +- cross-tenant exports and reports +- tenant-aware caches +- background jobs and event handlers that run without explicit tenant context + +A common mistake is assuming data filtering replaces authorization. It does not. + +## Seeding Tenant Data + +A good SaaS system usually needs both host seed data and tenant seed data. + +Examples: + +- host roles and platform settings +- tenant admin user +- default CRM stages +- default product catalog or sample records + +ABP uses `IDataSeedContributor` for this. + +### Basic seed contributor + +```csharp +using System; +using System.Threading.Tasks; +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp.Data; +using Volo.Abp.DependencyInjection; +using Volo.Abp.MultiTenancy; + +public class CrmDataSeedContributor : IDataSeedContributor, ITransientDependency +{ + private readonly ICurrentTenant _currentTenant; + private readonly IRepository _productRepository; + + public CrmDataSeedContributor( + ICurrentTenant currentTenant, + IRepository productRepository) + { + _currentTenant = currentTenant; + _productRepository = productRepository; + } + + public async Task SeedAsync(DataSeedContext context) + { + using (_currentTenant.Change(context?.TenantId)) + { + if (await _productRepository.GetCountAsync() > 0) + { + return; + } + + await _productRepository.InsertAsync( + new Product(Guid.NewGuid(), "Starter Plan", 49, _currentTenant.Id), + autoSave: true + ); + + await _productRepository.InsertAsync( + new Product(Guid.NewGuid(), "Growth Plan", 99, _currentTenant.Id), + autoSave: true + ); + } + } +} +``` + +### Host seed vs tenant seed + +Inside `SeedAsync`, `context.TenantId` tells you which scope you are seeding. + +- `null` means host context +- a concrete value means tenant context + +That makes it easy to branch logic: + +```csharp +public async Task SeedAsync(DataSeedContext context) +{ + using (_currentTenant.Change(context?.TenantId)) + { + if (_currentTenant.Id == null) + { + await SeedHostAsync(); + } + else + { + await SeedTenantAsync(_currentTenant.Id.Value); + } + } +} +``` + +### Per-tenant initialization + +For onboarding, a common pattern is: + +1. Create tenant. +2. Create tenant admin user. +3. Configure tenant connection string if needed. +4. Run migration for tenant database if dedicated. +5. Seed tenant defaults. +6. Enable tenant features. + +That workflow becomes especially important in database-per-tenant setups. + + + +## Multi-Tenant Authentication and Identity + +Identity is where host and tenant boundaries become visible to users. + +### Tenant-specific users and roles + +ABP Identity supports tenant-specific users and roles. + +- Host users have `TenantId == null` +- Tenant users have a tenant `TenantId` + +This allows the same email or username patterns to exist in separate tenant scopes, depending on your identity rules and configuration. + +### Permission definitions by side + +ABP permissions can be restricted by multi-tenancy side. + +Example: + +```csharp +using Volo.Abp.Authorization.Permissions; +using Volo.Abp.MultiTenancy; + +public class CrmPermissionDefinitionProvider : PermissionDefinitionProvider +{ + public override void Define(IPermissionDefinitionContext context) + { + var crmGroup = context.AddGroup("Crm"); + + crmGroup.AddPermission( + "Crm.Tenants.Manage", + multiTenancySide: MultiTenancySides.Host + ); + + crmGroup.AddPermission( + "Crm.Customers.Manage", + multiTenancySide: MultiTenancySides.Tenant + ); + } +} +``` + +This is a clean way to avoid accidentally exposing host admin actions to tenant users. + +### Login flow in a multi-tenant app + +A typical login flow works like this: + +1. User opens tenant URL such as `acme.mycrm.com`. +2. ABP resolves tenant `acme`. +3. Login request is processed within tenant context. +4. Identity validates the user against that tenant. +5. Claims are issued with tenant information. +6. Subsequent requests continue in the same tenant context. + +For host login: + +1. User opens host administration URL. +2. No tenant is resolved. +3. Login happens in host context. +4. Host-only permissions become available. + +### Tenant switching + +Tenant switching can mean different things: + +- a host admin acting on behalf of a tenant in backend services +- a user selecting a tenant context in a multi-organization portal +- changing browser origin or subdomain for tenant-specific UI access + +For backend logic, `CurrentTenant.Change(...)` is the mechanism. + +For frontend flows, tenant resolution strategy usually drives the user experience. + +## Database-Per-Tenant Configuration + +Database-per-tenant is where ABP's tenant abstractions become especially valuable. + +### Tenant-specific connection strings + +The Tenant Management module supports storing per-tenant connection strings. Once configured, ABP can use the tenant's own database automatically. + +Typical flow: + +- host creates tenant +- tenant record stores connection string override +- request resolves tenant +- connection string resolver uses tenant-specific value +- DbContext points to the tenant database + +### `ITenantStore` + +`ITenantStore` is the abstraction responsible for retrieving tenant configuration. + +That includes: + +- tenant id +- tenant name +- active status +- connection strings + +The default implementation may read from configuration or from the Tenant Management module database, depending on setup. + +### Example: tenant configuration in appsettings + +```json +{ + "Tenants": [ + { + "Id": "11111111-1111-1111-1111-111111111111", + "Name": "acme", + "ConnectionStrings": { + "Default": "Server=.;Database=Crm_Acme;Trusted_Connection=True;TrustServerCertificate=True" + } + }, + { + "Id": "22222222-2222-2222-2222-222222222222", + "Name": "globex", + "ConnectionStrings": { + "Default": "Server=.;Database=Crm_Globex;Trusted_Connection=True;TrustServerCertificate=True" + } + } + ] +} +``` + +### Production-ready considerations + +For production, prefer: + +- tenant metadata in a central host database +- automated tenant provisioning pipeline +- a migration runner for new and existing tenant databases +- secure connection string storage +- monitoring and health checks per tenant database + +### What changes operationally + +With one shared database, disabling the tenant filter can make host-wide queries possible. + +With separate databases, cross-tenant queries are fundamentally different. The host cannot query all tenant rows with one SQL statement because the data lives in different databases. + +That changes how you design: + +- reporting +- analytics +- support tooling +- exports +- migration scripts + +## Advanced Multi-Tenancy Scenarios + +Once the core application works, the interesting problems begin. + +### Background jobs in tenant context + +Background jobs often execute outside the original HTTP request. That means tenant context is not automatically available unless you pass and restore it. + +```csharp +public class RebuildCustomerStatsJob : AsyncBackgroundJob +{ + private readonly ICurrentTenant _currentTenant; + private readonly IRepository _customerRepository; + + public RebuildCustomerStatsJob( + ICurrentTenant currentTenant, + IRepository customerRepository) + { + _currentTenant = currentTenant; + _customerRepository = customerRepository; + } + + public override async Task ExecuteAsync(Guid tenantId) + { + using (_currentTenant.Change(tenantId)) + { + var count = await _customerRepository.GetCountAsync(); + // Rebuild stats for this tenant + } + } +} +``` + +If you queue jobs without tenant identity, you will eventually process data in the wrong context. + +### Distributed events + +Distributed event handlers should also be tenant-aware. + +A practical pattern is to include tenant id in the event payload and restore it in the handler before performing repository operations. + +### Caching per tenant + +Cache keys must include tenant identity when the cached value is tenant-specific. + +Bad: + +- `dashboard-summary` + +Good: + +- `tenant:{tenantId}:dashboard-summary` + +This sounds obvious, but cross-tenant cache leakage is a very real failure mode. + +### Feature management + +ABP feature management is a natural fit for SaaS plans. + +Use features for things like: + +- max number of users +- advanced reporting availability +- API access +- storage limits + +A tenant on a basic plan and a tenant on an enterprise plan can run the same codebase with different capabilities. + +### Setting management + +Settings are another strong tenant-aware capability. + +Examples: + +- default currency +- email sender name +- CRM pipeline defaults +- localization preferences + +Settings should be tenant-scoped when they represent tenant configuration, not platform-wide behavior. + +### Audit logging + +Audit logs should always preserve tenant identity. That makes support and incident investigation much easier. + +When reviewing logs, you should be able to answer: + +- which tenant performed the operation +- whether it happened in host or tenant context +- which user executed it + +### Localization + +Localization becomes multi-tenant when tenants can override culture, language preferences, or content. Keep shared localization resources separate from tenant-specific content whenever possible. + +### Common pitfalls + +A few pitfalls show up repeatedly in real projects: + +- tenant resolution order produces unexpected `CurrentTenant.Id == null` +- public APIs trust `__tenant` header without gateway validation +- seed logic is not idempotent and creates duplicates +- background jobs run without restored tenant context +- raw SQL bypasses tenant filtering +- cache keys omit tenant id +- host admin screens disable filters too broadly +- database-per-tenant migrations are not automated + +## Building a Sample SaaS CRM Application + +Let's put the concepts together into a practical example. + +### Business scenario + +We are building a SaaS CRM platform with: + +- host administration +- tenant administration +- customer management +- product catalog +- order management +- subscription management + +### Host administration responsibilities + +The host side manages the platform itself. + +Typical host features: + +- create tenant +- suspend or reactivate tenant +- assign subscription plan +- configure dedicated database +- view platform metrics +- trigger tenant provisioning + +### Tenant administration responsibilities + +Each tenant manages its own organization. + +Typical tenant features: + +- invite users +- manage roles +- configure CRM settings +- manage customers and sales pipeline +- view tenant-specific reports + +### Suggested module boundaries + +A practical application split might look like this: + +- **SaaS/Host module**: tenant lifecycle, subscriptions, plans +- **Identity module**: users, roles, permissions +- **CRM module**: customers, contacts, products, orders +- **Billing module**: plan, invoice metadata, subscription status +- **Reporting module**: tenant-level analytics + +### Example tenant onboarding flow + +Suppose a new tenant signs up: `acme`. + +1. Host creates a `Tenant` record. +2. Subscription plan is assigned. +3. If enterprise tier, a dedicated database is created. +4. Migrations run for the tenant database if needed. +5. Tenant admin user is provisioned. +6. CRM defaults are seeded. +7. Features are assigned based on plan. +8. Tenant accesses `acme.mycrm.com`. + +### Example application service for tenant onboarding + +```csharp +public class TenantProvisioningAppService : ApplicationService +{ + private readonly ITenantRepository _tenantRepository; + private readonly IDataSeeder _dataSeeder; + + public TenantProvisioningAppService( + ITenantRepository tenantRepository, + IDataSeeder dataSeeder) + { + _tenantRepository = tenantRepository; + _dataSeeder = dataSeeder; + } + + public async Task ProvisionAsync(Guid tenantId) + { + var tenant = await _tenantRepository.GetAsync(tenantId); + + await _dataSeeder.SeedAsync(new DataSeedContext(tenant.Id)); + } +} +``` + +In a real solution, provisioning usually includes database creation, migration, admin user setup, and feature initialization as well. + +### How the pieces fit together + +In the CRM app: + +- tenant is resolved from subdomain +- identity authenticates users within the tenant +- entities implement `IMultiTenant` +- repositories automatically filter by tenant +- host users manage tenant lifecycle +- features and settings control plan differences +- background jobs and event handlers restore tenant context explicitly + +That is the practical ABP multi-tenancy story end to end. + +## Best Practices for ABP Multi-Tenant Applications + +Here are 15+ best practices that hold up well in production. + +1. **Decide host vs tenant ownership early.** Not every entity should implement `IMultiTenant`. +2. **Choose the database model intentionally.** Start simple, but plan the migration path. +3. **Prefer subdomain resolution for browser-based SaaS.** It is usually the cleanest user experience. +4. **Do not trust public tenant headers blindly.** Accept them only behind trusted infrastructure. +5. **Keep tenant resolution order explicit.** Unexpected resolver precedence causes hard-to-debug bugs. +6. **Use `CurrentTenant.Change(...)` for cross-tenant work.** Do not fake tenant context with ad hoc parameters. +7. **Make seeding idempotent.** Seed contributors should safely run more than once. +8. **Include tenant id in cache keys.** Always. +9. **Be cautious when disabling `IMultiTenant` filters.** Limit scope and review security impact. +10. **Define permissions with the right `MultiTenancySides`.** Host and tenant actions should be separated clearly. +11. **Automate tenant database migrations.** Manual DB-per-tenant operations do not scale. +12. **Monitor by tenant.** Errors, latency, and usage metrics should be attributable to tenant context. +13. **Design indexes around tenant access patterns.** Shared-database tables often need `(TenantId, ...)` composite indexes. +14. **Avoid cross-tenant joins in business logic.** They are usually a sign of a leaking domain boundary. +15. **Test host context explicitly.** Many bugs appear only when `CurrentTenant.Id` is null. +16. **Test tenant switching and nested scopes.** Especially in background and integration flows. +17. **Preserve tenant id in audit logs and events.** It helps debugging, support, and compliance. +18. **Plan backup and restore by tenancy model.** Shared and dedicated databases require different operational playbooks. +19. **Keep raw SQL rare and reviewed.** Repository filters do not protect careless SQL. +20. **Treat multi-tenancy as a security concern, not just an architecture pattern.** Because in practice, it is both. + +## Conclusion + +ABP Framework gives you a strong, practical multi-tenancy foundation. The important part is that its support is not isolated in one package or middleware. It is woven through the framework: request resolution, current tenant context, repositories, data filters, identity, tenant management, features, settings, and background processing. + +That matters because real SaaS applications do not fail on the happy path. They fail in the edge cases: host-side screens, cache leakage, background jobs, custom resolvers, and rushed provisioning logic. + +If you understand the host vs tenant model clearly and use ABP's abstractions as intended, you can build a multi-tenant application that stays maintainable as your product grows from a few customers to many. + +Start with a simple shared-database model if it fits. Move to dedicated databases where needed. Keep tenant context explicit. Respect the boundaries. ABP does the heavy lifting, but architecture discipline is still your job. + +## TL;DR + +- ABP multi-tenancy gives you built-in tenant resolution, `ICurrentTenant`, `IMultiTenant`, data filters, and tenant management support. +- Shared DB is the easiest starting point; DB-per-tenant and hybrid models fit stronger isolation and enterprise needs. +- Correct tenant resolution is the foundation of data isolation, authentication, and authorization. +- Use `CurrentTenant.Change(...)` for controlled cross-tenant work, especially in jobs, seeders, and host-side services. +- Production success depends on secure resolvers, tenant-aware caching, automated migrations, and strict host/tenant boundaries. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/cover.png b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/cover.png new file mode 100644 index 0000000000..def7467e73 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png new file mode 100644 index 0000000000..3940d506be Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png new file mode 100644 index 0000000000..9c0d224922 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png new file mode 100644 index 0000000000..b0a8cb5a96 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-09-implementing-multitenancy-in-abp-framework-a-complete/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/abp-agent-mode-picker.png b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/abp-agent-mode-picker.png new file mode 100644 index 0000000000..e4ac0af1fe Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/abp-agent-mode-picker.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/abp-agent-plan-actions.png b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/abp-agent-plan-actions.png new file mode 100644 index 0000000000..ef99ac7ee6 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/abp-agent-plan-actions.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/cover.png b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/cover.png new file mode 100644 index 0000000000..ef6b3dd2a6 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/post.md b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/post.md new file mode 100644 index 0000000000..82fed5324d --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-1-agent-plan-ask-abp-studio-ai/post.md @@ -0,0 +1,105 @@ +# Deep Dive on ABP AI Agent #1: Agent, Plan and Ask Modes + +There is a small question I like to answer before I type anything into **ABP Agent**: + +**Do I want an answer, a plan, or action?** + +That question looks simple, but it changes the whole experience. Sometimes I am only trying to understand why a module is structured a certain way. Sometimes I already know the direction, but I want the implementation path checked before touching files. And sometimes the task is clear enough that I want ABP Agent to do the work, run the checks, and iterate with me. + +That is where the three modes in ABP Studio AI become more than labels. They help me choose the right level of trust, risk, and action for the moment. + +![ABP Agent mode picker showing Agent, Plan, and Ask](abp-agent-mode-picker.png) + +## Ask Mode: When I Want To Understand + +**Ask** is the mode I reach for when I want to stay in learning mode. + +It is useful when I am reading a solution and want to ask questions like: + +* What is this module responsible for? +* Why is this permission checked here? +* How does this application service relate to the domain layer? +* What would happen if I changed this setting, dependency, or flow? +* Which ABP concept should I use for this requirement? + +The important part is that Ask mode is read-only. I can explore the codebase, ABP concepts, architecture, or possible approaches without worrying that files will be changed as a side effect of the conversation. + +That makes it a comfortable starting point. I do not need to prepare a perfect prompt. I can ask a rough question, follow up with more context, and slowly turn uncertainty into something clearer. + +For me, Ask mode is especially helpful when I join a solution after some time away. Instead of jumping between files and trying to rebuild the story manually, I can ask ABP Agent to explain the shape of the solution in the language of ABP: modules, layers, permissions, application services, entities, settings, events, and runtime pieces. + +## Plan Mode: When I Want To Think Before Changing Code + +**Plan** is the mode I use when the next step is probably implementation, but I do not want to start editing yet. + +This is the middle ground between a conversation and a code change. ABP Agent can inspect the solution in a read-only way, ask clarifying questions when the requirement is not clear enough, and produce a structured plan before any file is modified. + +That changes the feeling of working with AI. Instead of saying "go build this" and reviewing only the result, I can review the approach first: + +* Which files will likely be affected? +* Which ABP layers are involved? +* Does the implementation path match the existing solution style? +* Are there missing decisions before the work starts? +* Is this a small change, or is it actually a larger workflow? + +This is useful for changes that cross boundaries: adding a new entity, adjusting an application service, introducing a permission, changing a UI flow, or touching more than one module. Those are exactly the moments where I want a second pass before code starts moving. + +When a plan is active, ABP Studio gives me clear actions around it. I can view the plan, detach it if it is no longer the right direction, or apply it with Agent mode when I am ready to move from planning to implementation. + +![ABP Agent plan actions for viewing, detaching, or applying a plan](abp-agent-plan-actions.png) + +The small detail I like here is that the plan does not disappear into the chat history. It becomes something I can review and intentionally carry into the next step. + +## Agent Mode: When I Am Ready For Action + +**Agent** is the mode I choose when I am ready to let ABP Agent work on the solution. + +This is the action mode. ABP Agent can edit files, run commands, build projects, use ABP Studio tasks, and iterate when something fails. It is the right choice when the task is clear enough and I am comfortable letting the agent make changes that I will review afterward. + +For small trusted tasks, I may go directly to Agent mode: + +* Add a missing localization entry +* Fix a straightforward build error +* Update a simple DTO mapping +* Add a validation rule that matches an existing pattern +* Apply a plan that I have already reviewed + +For larger work, I prefer not to start here. Agent mode is powerful, and power is better when it is intentional. If I am not sure about the shape of the change, I usually start with Ask or Plan first. + +## A Practical Workflow + +The modes are most useful when I treat them as a workflow, not as three disconnected buttons. + +For larger changes, my usual flow is: + +1. **Ask** to understand the area and the existing conventions. +2. **Plan** to turn the requirement into a reviewable implementation path. +3. **Agent** to apply the plan, build, and iterate. + +For learning, I often stay entirely in Ask mode. If I am trying to understand ABP multi-tenancy behavior, module dependencies, permission definitions, or why a solution is organized a certain way, there is no need to involve file changes. + +For small tasks, I may go directly to Agent mode. The key is that I already know what I want, the risk is low, and the expected result is easy to review. + +Here is the simple rule I keep in mind: + +| Situation | Mode I Choose | Why | +| --- | --- | --- | +| I need an explanation | Ask | It keeps the conversation read-only. | +| I need a direction before implementation | Plan | It gives me a reviewable path before changes. | +| I am ready for ABP Agent to work | Agent | It can edit, build, run tasks, and iterate. | + +## Why This Matters + +AI-assisted development can feel too fast when the tool moves from idea to code before I have decided what kind of help I actually need. + +The three modes slow that moment down in a good way. They let me say: + +* "Just explain this." +* "Think through the change first." +* "Now implement it." + +That separation makes the work feel more intentional. It also makes the output easier to review, because the mode already tells me what kind of result I should expect. + +Ask gives me understanding. Plan gives me a path. Agent gives me action. + +Used together, they make ABP Studio AI feel less like a single big button and more like a development partner that can adapt to the level of confidence I have at each step. diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-catalog.png b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-catalog.png new file mode 100644 index 0000000000..8cdcc12bf0 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-catalog.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-selector.png b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-selector.png new file mode 100644 index 0000000000..84c8d4161f Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-selector.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-settings-agents.png b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-settings-agents.png new file mode 100644 index 0000000000..5acd071643 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-settings-agents.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-settings-git-review.png b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-settings-git-review.png new file mode 100644 index 0000000000..0ede751e7f Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/abp-agent-model-settings-git-review.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/cover.png b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/cover.png new file mode 100644 index 0000000000..49e2b7d868 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/post.md b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/post.md new file mode 100644 index 0000000000..ef54e2c01c --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-2-supported-ai-models-abp-studio-ai/post.md @@ -0,0 +1,138 @@ +# Deep Dive on ABP AI Agent #2: Supported AI Models in ABP Studio + Usage Recommendations + +There is one question I ask almost as often as "Which mode should I use?": + +**Which model should do this work?** + +At first, it is tempting to answer that question by always choosing the strongest model in the list. That feels safe. If a model is more capable, why not use it for everything? + +In real work, I do not think about it that way. + +When I use **ABP Studio AI**, the model choice is part of the workflow. Some tasks need careful reasoning. Some need speed. Some need a large context window. Some need image support because the browser or a screenshot is involved. Some are small text-processing tasks where using the most capable model would only make the work slower and more expensive. + +So I treat model selection as a practical decision, not a trophy selection. + +## What ABP Studio Supports Today + +ABP Studio gives me a curated model setup by default. It keeps the first experience simple, while still letting me choose from a broader model catalog when I want to tune the setup for a specific kind of work. + +The important word here is **focused**. + +ABP Studio does not treat every model as an equally good choice for agent work. A coding agent needs things like a useful context window, tool support, text output, and reliable behavior in repeated agent loops. Studio keeps the model experience closer to that reality. + +The built-in model set currently includes: + +| Model | How I think about it | +| --- | --- | +| Claude Sonnet 4.6 | The default main model for day-to-day Ask, Plan, and Agent work. | +| Claude Haiku 4.5 | A fast supporting model for research, browser work, and lightweight text processing. | +| Claude Opus 4.7 | A stronger option when the task needs deeper reasoning or more careful review. | +| GPT-5.5 | Another strong option for main conversations or review-style work. | +| GLM-5.1 | A text/code option for tasks that do not need image input. | + +I do not read this list as a ranking. I read it as the default toolbox. + +And it is not a closed box. If I need a different model for a specific task, I can open the Models settings, search the catalog, filter by category, and add more models to my selection. + +![ABP Studio Models settings showing the selectable model catalog](abp-agent-model-catalog.png) + +That is an important distinction. The built-in models are there so I can start with sensible defaults. They are not there to force every team, every solution, or every workflow into the same model choices. + +## The Main Model + +The main model is the one I feel most directly in the conversation. + +It is used when I ask questions, create plans, or let ABP Agent work through an implementation. This is the model behind the normal flow of the chat. + +![ABP Agent model selector showing the current conversation model](abp-agent-model-selector.png) + +For most work, I keep a balanced model as the main model. A Sonnet-style model is a good default because it is capable enough for real development tasks without making every small question feel heavy. + +This is the model I use for: + +* Understanding a module or package +* Planning a feature before editing code +* Applying a reviewed plan +* Fixing ordinary build or test failures +* Making changes where the expected result is easy to review + +When the task gets broader, I become more intentional. + +If I am asking ABP Agent to reason across several modules, plan a risky refactor, review architecture, or inspect a subtle regression, I am more willing to switch to a stronger model. The extra capability is useful when the cost of a shallow answer is high. + +For a quick localization change or a small DTO update, that same choice can be wasteful. The strongest model is not always the best model for the moment. + +## Role-Based Models + +One detail I like in ABP Studio AI is that model selection is not only one global dropdown. + +Studio separates the main conversation model from supporting model roles. That means I can keep the main model strong enough for the conversation while using lighter models for background work. + +![ABP Agent model settings for main, research, browser, and text processor models](abp-agent-model-settings-agents.png) + +The roles are easier to understand if I describe them by how they feel in daily use. + +**Main Model** is the model I am actively talking to. It carries the normal Ask, Plan, and Agent experience. + +**Research Model** is for research and ABP documentation searcher work. I usually keep this lightweight because research often involves gathering, narrowing, and summarizing context before the main model decides what to do with it. + +**Browser Model** is used by the browser subagent in Agent mode. This role should stay fast and practical. When browser screenshots are involved, I choose a model that supports image input. A text-only model may be fine for code, but it is not the right fit when the work depends on seeing the UI. + +**Text Processor Model** is for smaller language tasks such as summarizing errors, generating commit messages, or consolidating learned lessons. This is exactly where I do not want to spend the most capable model every time. + +The Git Review model is separate too. + +![ABP Agent model settings for Git Review model selection](abp-agent-model-settings-git-review.png) + +For AI Review, I like the "Ask me every time" behavior. Some reviews are routine. Some reviews deserve a stronger model because the change is large, security-sensitive, or touches architecture. Asking each time keeps that decision close to the actual change. + +If a team wants consistent review behavior, a fixed review model also makes sense. The key is that Git Review does not have to silently follow the same model I use for ordinary chat. + +## How I Choose In Practice + +For quick questions, I use the default main model. + +If I am asking "Where is this permission defined?" or "Why does this module reference that package?", I do not need to overthink the model. I want a clear answer and maybe a few source references. + +For planning larger work, I use a stronger main model when the decision matters. + +Plan mode is where the model can save me from an expensive wrong turn. If the change crosses layers, modules, permissions, UI, or database behavior, I prefer a model that can hold more context and reason carefully. I still narrow the scope where possible, because a focused prompt usually beats a huge unfocused one. + +For implementation, I care about reliability more than raw size. + +Agent mode is not only about generating code. It is about reading the solution, editing files, running checks, seeing failures, and trying again. A good main model should follow instructions consistently and use tools well. For supporting roles, I usually keep the lighter defaults. + +For UI and browser tasks, I check image support. + +If the task involves screenshots, browser interaction, visual verification, or UI state, the browser model needs to be able to understand images. This is one reason I do not treat every text/code model as interchangeable. + +For reviews, I choose based on risk. + +A small formatting or localization change does not need the same review setup as a large change in authorization, multi-tenancy, persistence, or distributed behavior. For deeper reviews, I am willing to use a stronger model because the goal is not speed. The goal is to catch what I missed. + +For cost and latency, I avoid using the strongest model everywhere. + +This is not only about credits. It is also about pace. If every background task uses a heavy model, the development loop feels slower. Keeping lightweight models for lightweight jobs makes ABP Studio AI feel more responsive. + +## A Simple Rule + +The model name matters less than the job. + +When I choose a model in ABP Studio AI, I usually ask: + +| Situation | Model choice I prefer | +| --- | --- | +| Normal Ask, Plan, or Agent work | Balanced main model | +| Broad planning or risky implementation | Stronger main model | +| Research and documentation lookup | Lightweight supporting model | +| Browser tasks with screenshots | Vision-capable browser model | +| Error summaries and commit messages | Lightweight text processor model | +| Important AI Review | Stronger model or ask each time | + +That keeps the experience practical. + +Modes decide how much action I want: Ask, Plan, or Agent. + +Models decide which brain should handle the work. + +When those two choices are made intentionally, ABP Studio AI feels less like one generic AI button and more like a set of tools I can tune for the task in front of me. diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/POST.md b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/POST.md new file mode 100644 index 0000000000..1440f5061d --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/POST.md @@ -0,0 +1,143 @@ +# Deep Dive on ABP AI Agent #3: Rules, Skills and Lessons + +Every new chat starts from zero. + +The model can write the API, the permissions, and the UI. What disappears between sessions is everything specific to *this* solution: your naming rules, your feature checklist, the demo-data fix from yesterday. You end up re-teaching before you start building. + +That is not an intelligence problem. The model is already capable enough. What does not carry over is the setup around it. + +## Agent, Model, and Harness + +Three terms get mixed up constantly. Keeping them separate makes everything else in this article click. + +**The model** is the LLM: the weights, the training data, the reasoning engine. You do not get to change it. You pick which one to use, and that is about it. + +**The harness** is everything wrapped around the model so it can actually finish work in *your* environment: the system prompt, the tools it can call, the files it may read, the checks that run on its output, the limits on what it may touch, and the instructions injected into every session. A raw model is not an agent. An agent is the model plus the harness. If you are not the model, you are building the harness. + +**The agent** is the whole system: model plus harness, running in a loop until the task is done. The behaviour you experience is dominated by the harness, not just the model. [Addy Osmani](https://addyosmani.com/blog/agent-harness-engineering/) puts the same idea plainly: *a decent model with a great harness beats a great model with a bad harness.* The gap between what today's models can do and what you actually see them do in your codebase is mostly a harness gap. + +The habit that makes a harness good is simple: treat every mistake as a reason to update the setup, not just to fix the output in chat. Each time the agent gets something wrong, change what it always knows, can look up, or carries forward so it cannot repeat the same error. Do that consistently and the agent stops repeating mistakes and starts working the way your team works. + +In **ABP Studio AI Coding Agent**, the harness includes three pieces that hold what the agent knows about your solution: **Rules**, **Skills**, and **Lessons**. They live under **Settings > Rules & Skills**. + +![The Rules & Skills settings page in ABP Studio](rules-and-skills-settings.png) + +## Rules: The House Rules On The Wall + +A **Rule** is a standing instruction that the harness injects into the agent's context on every turn of every session. In harness-engineering terms, it is always-on context injection: the same role as an `AGENTS.md` or `CLAUDE.md` at the root of a repo, except scoped to your solution or your profile inside ABP Studio. + +Think of the house rules pinned to a kitchen wall: how we do things here, every shift, no exceptions. Unlike a glance at a poster, though, a Rule is not ambient background. It is read on every turn, so it costs context budget every time the agent acts. + +ABP Agent already follows the framework's own conventions by default. It goes through the data layer instead of hitting the database directly, uses the built-in permission system instead of hand-rolled checks, and reads user-facing text from the translation files instead of hardcoding it. You do not write those down. + +Rules are where *your* conventions go. The ones the framework cannot guess because they belong to your solution and your team. The good part is that these read like plain conventions any developer would recognize, not framework trivia: + +* New code goes in the same place, with the same naming, as the code already around it. +* Every endpoint that changes data checks permissions before it does anything. +* Money is stored in minor units (cents), never as a floating-point number. +* API errors use our standard response shape, never ad-hoc JSON. + +With those on the wall, I stop repeating them. Instead of writing this: + +```text +Add a Category screen. Use our data layer, do not query the database +directly. Check permissions on every write. Keep money in cents. Put the +files where the other features live. +``` + +I can write this: + +```text +Add a Category screen. +``` + +The conventions are not renegotiated, one prompt at a time, in every session. The agent applies them the way a teammate who has read the contributor guide would. + +This matters more than it looks. A model with no standing rules does not stay neutral. It falls back on the defaults from its training data. Ask a generic model for "an endpoint that returns categories" and you often get one with the database query written straight into the handler, because that is the most common shape on the public internet. Rules steer the agent's output back toward *your* codebase. + +One caution: treat the rule list like a pilot's checklist, not a style guide. A Rule is injected on every turn, so keep the list short. Every line should earn its place, ideally traceable to a real failure or a hard constraint you cannot ignore. If a line does not change what the agent produces, it is noise, and it dilutes the rules that actually matter. + +You also choose where a rule is saved. Global rules sit under your user profile and apply to every solution on your machine. Solution rules apply only to the current solution, and only while it is open. + +## Skills: Recipes You Pull Off The Shelf + +A **Skill** is the same kind of note as a Rule, but loaded only when the task calls for it. The harness keeps a short description of each skill in context at all times; the agent reads the full text only when that description matches what you asked it to do. Harness engineers call this **progressive disclosure**: reveal instructions and detail only when they are needed, instead of stuffing everything into the opening prompt. + +A recipe is not pinned to the wall. It sits in a drawer, and the cook pulls it out only when making that dish. That is a Skill. + +In ABP Studio, a rule and a skill are the same kind of note with one switch between them. + +![Creating a rule or a skill: the Always Apply toggle decides which one it is](create-rule-skill-dialog.png) + +You write a name (which becomes the file name) and some content, then set **Always Apply**. Turn it on and the note is a Rule, always in context. Turn it off and the note is a Skill, fetched on demand. So if a skill turns out to be something the agent should never skip, you flip one switch and it becomes a rule. + +My favorite example of a skill is a "build a feature end to end" checklist: the ordered steps your team follows to ship one complete feature. The data model comes first, then the data access layer, then the application service, then the API, then the translations, then the UI, and finally the demo data. Write it once, and the agent follows it whenever it builds a feature, instead of inventing its own order each time. + +Writing a skill is like writing an onboarding note for a new teammate. You are not making them smarter. You are saving them the week it would take to work out how your team does this one thing. + +A skill can be long without slowing anything down. The agent sees only the short description of each skill at all times, and reads the full text only when the description matches the task. The detail stays in the drawer until it is needed. + +Skills are also portable. A skill is plain Markdown, so you can import one written elsewhere instead of retyping it. + +![Importing skills from .md files into a solution or your global profile](import-rules.png) + +You point the importer at a file or a folder of `.md` files and choose whether they go into the current solution or your global profile. A procedure one person worked out can travel to the rest of the team, or to your next solution. + +A simple test for which one to reach for: + +* If it should hold no matter what you are doing, it is a **Rule**. ("Always return errors in our standard shape.") +* If it is a procedure you follow only for a certain kind of task, it is a **Skill**. ("Here is our checklist for adding a feature end to end.") + +## Lessons: What The Agent Learns On Its Own + +Rules and Skills are written by a person. **Lessons** are written by the agent. + +Think of a shift handoff log in the kitchen: after something goes wrong, someone writes down what happened and what to do differently next time. The next cook reads it before repeating the same work. In ABP Studio, you correct the mistake; the agent records the verified fix so future sessions do not trip over it again. That entry is a Lesson. + +When the agent gets something wrong and is corrected, by you, by a failing build, or by the official ABP documentation, it can record the correction as a short, verified note. The harness carries that note into later turns and later sessions as high-priority context. That is the `ai-learned-lessons` entry you saw in the settings list, growing as the agent works in your solution. + +The idea behind it is simple: when the agent gets something wrong, fix it once so it never gets it wrong the same way again. You already do a version of this when you edit a notes file by hand. Lessons do the recording for you, at the moment of the correction, when the reason is still fresh and you would otherwise forget to write it down. + +Here is the shape of a real one. I ask the agent to add a `Category` screen. It builds the data model, the API, and the UI, but forgets to grant the new permission in the demo data. The screen compiles, the API responds, everything looks finished, and the only symptom is that real users get "access denied." I correct it, the agent fixes the demo data, and it records a note: in this solution, a new permission is not done until it is granted in the demo data. Next time, it remembers. + +A Lesson is not a general fact about ABP. The documentation already covers that, and the agent reads it. A Lesson is a solution-specific, verified correction: the kind of knowledge a team usually keeps in people's heads and loses when they move on. Here it is written down the moment it is learned, instead of weeks later, if ever. + +## When To Use Which? + +Once the three are clear, they sort themselves out: + +| Mechanism | Who writes it | When it loads | Answers | +| --- | --- | --- | --- | +| **Rules** | You | Always, every turn | "What must always be true here?" | +| **Skills** | You | When relevant to the task | "How do we do this kind of task?" | +| **Lessons** | The agent | In later sessions, as high-priority context | "What did we get wrong before in this solution?" | + +They feed into each other. A Lesson that keeps coming back is a sign it should be promoted. If the agent records the same correction again and again, it is no longer a one-off note. It belongs in a Rule, if it is an always-true convention, or in a Skill, if it is a procedure. Knowledge tends to move from Lessons toward Rules and Skills: the agent finds the pattern by tripping over it, and you write it down properly once it has earned the spot. + +Keep an eye on the budget, because all three share the same limited space, the context window. Rules cost the most, since they are always present, so an overstuffed rule list weighs down every turn and crowds out the rules that matter. Skills are cheaper, paid for only when used, which is a good reason to move anything situational out of Rules and into a Skill. Lessons add up too, so clear out the stale ones now and then. The point is not to write down everything you know. It is to write down the few things that change what the agent produces, and put each one where it loads at the right time. + +## Why This Is Different From Generic Coding Agents? + +To be fair, the ideas themselves are not unique to ABP. Tools like Cursor, Claude Code, Codex, and Windsurf are strong general-purpose coding tools, and they already have always-on instruction files and on-demand skill files. If all you compare is whether a tool can hold rules and skills, there is no real difference, and I would not pretend otherwise. + +The difference is in the two places where a generic tool has to guess. + +The first is memory of its own mistakes. In most tools, remembering a past mistake means you stop and edit a memory file by hand. Lessons remove that step. The agent records the correction itself, the moment it happens, so the knowledge survives without you having to maintain it. + +The second, and the one that matters most, is what all of this sits on. A generic instruction file can say "use the data layer," but the tool still has to read your files and guess what the data layer is and where it lives. ABP Agent does not guess. It starts every session with an ABP-aware map of your solution, and when it is unsure how something should be done, it checks the official ABP documentation instead of the average of the public internet. So the rules and skills you write are not hints dropped into a tool that barely understands the project. They are backed by one that already knows the framework underneath them. + +There is also a smaller convenience worth a line: a rule and a skill are the same note with one switch between them, scoped to the solution or your profile from the same place, instead of two separate file formats to keep track of. + +## Conclusion + +It is best to see the three as one system, not three switches. + +* **Rules** hold the conventions you refuse to repeat. +* **Skills** hold the procedures you want to reuse. +* **Lessons** hold the corrections the agent learns as it works. + +Together they answer the blank-memory problem. They do not give the model new weights. They inject, at the start of each session, the smallest useful set of instructions so the agent can work as if it has been here before. + +A generic agent with no harness tuning stays roughly as capable on its thousandth task in your codebase as on its first. With Rules, Skills, and Lessons, ABP Agent accumulates solution-specific knowledge over time, especially through Lessons and the promotions you make from them. + +That is the real value: **not just an AI that writes code, but one that learns how your solution is built and keeps that knowledge from one session to the next.** diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/cover-image.png b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/cover-image.png new file mode 100644 index 0000000000..f88dd33b79 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/cover-image.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/create-rule-skill-dialog.png b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/create-rule-skill-dialog.png new file mode 100644 index 0000000000..0d874ae897 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/create-rule-skill-dialog.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/import-rules.png b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/import-rules.png new file mode 100644 index 0000000000..6e5f10dab0 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/import-rules.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/rules-and-skills-settings.png b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/rules-and-skills-settings.png new file mode 100644 index 0000000000..d66fdda94b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-3-rules-skills-lessons/rules-and-skills-settings.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/POST.md b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/POST.md new file mode 100644 index 0000000000..1f736795d7 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/POST.md @@ -0,0 +1,275 @@ +# Deep Dive on ABP AI Agent #4: Integrated ABP Studio Tools + +When I use an AI coding agent, there is a point where plain code awareness is not enough. + +The agent may understand the project structure. It may read the failing method. It may even guess the most likely cause of an error. But in a real development session, I usually need more than a guess. I need the latest exception, the request that caused it, the logs around it, the application that is running, the containers it depends on, the tasks I can execute, and the build result after a fix. + +That is where **ABP AI Coding Agent** becomes different from a generic coding assistant. It is not only connected to files. It is connected to **ABP Studio**. + +ABP Studio already knows the solution, run profiles, runnable applications, containers, tasks, monitoring data, and build actions. ABP AI Coding Agent can use that context through integrated tools when those tools are enabled. So instead of copying exception details, terminal output, container names, or build logs into the chat manually, I can let the agent work with the same ABP Studio environment I am using. + +![ABP AI Coding Agent with tools](tools-with-agent.png) + +> **Note:** ABP AI Coding Agent is available directly to ABP license holders. License holders have predefined credits so they can try it without setting up a separate AI workflow first. When those credits run out, they can buy more and continue using the same integrated experience. + +## Why Integrated Tools Matter + +Most coding agents start from the same place: **source code**. + +That is useful, but ABP development is not only source code. A running ABP solution has applications, modules, services, containers, database connections, migrations, logs, exceptions, requests, tasks, and build steps. When these pieces are outside the agent's reach, the developer becomes the bridge: + +* Copy this exception. +* Paste that log. +* Run this build. +* Check that container. +* Explain which application is currently running. +* Tell the agent what failed after the last change. + +Integrated ABP Studio tools reduce that manual work. They let the agent ask ABP Studio for runtime and solution information directly, within the permission boundary I choose. + +The important detail is that this access is still explicit. Tools can be enabled or disabled. If I do not want the agent to use a tool, I can keep it disabled. If I want the agent to troubleshoot with runtime information, I can enable the relevant tools and ask for a more complete investigation. + +That gives me a practical balance: the productivity of automation, with a visible boundary around what the agent can use. + +## Tool Access: What The Agent Is Allowed To Use + +The tools view is the control point. + +This is where ABP Studio shows the integrated tools that can be used by ABP AI Coding Agent. Some tools are for reading runtime information. Some are for interacting with applications. Some are for containers, tasks, or build actions. + +![ABP AI Coding Agent tools overview](abp-agent-tools-overview.png) + +> The names are intentionally direct. A monitoring tool that gets exceptions is about exceptions. A build tool is about build validation. A task tool is about ABP Studio tasks. That makes the tool list easy to understand even before using it in a real prompt. + +For me, the key idea is not the individual button names. It is the permission model: + +* If a tool is disabled, the agent should not act as if it has that information. +* If a tool is enabled, the agent can use it as part of the current session. +* If a task needs runtime evidence, I can enable only the tools needed for that task. + +This makes ABP AI Coding Agent feel more intentional than a black box. I can decide when it should stay in code reasoning and when it should use ABP Studio's runtime view of the solution. + +## Monitoring Tools + +Monitoring tools are the first group I reach for when something fails at runtime. + +![ABP AI Coding Agent monitoring tools](abp-agent-monitoring-tools.png) + +These tools help the agent inspect what happened while the application was running. In practice, this means information like **exceptions**, **logs**, **events**, and **request details**. + +This is a big difference from a generic coding agent. Without monitoring tools, the agent can read the code and make a reasonable guess. With monitoring tools, it can work from the actual failure. + +For example, if a page throws an exception, I can ask: + +```text +Get the latest exception from ABP Studio Monitoring and explain what failed. +``` + +If the exception tool is enabled, the agent can use that runtime signal. It can look at the exception message, stack trace, request context, and related code. Then it can connect the runtime failure to the implementation. + +That changes the debugging loop: + +1. Trigger the problem. +2. Ask the agent to inspect the runtime evidence. +3. Let it find the related code. +4. Apply the fix. +5. Validate again. + +The developer no longer needs to manually copy the exception from one place and paste it into another. ABP Studio becomes part of the agent's working context and give it ***harness***! + +## Application Tools + +Application tools connect the agent to the applications defined in the active ABP Studio run profile. + +![ABP AI Coding Agent application tools](abp-agent-application-tools.png) + +This matters because ABP solutions often contain more than one runnable application. A layered solution may have a web application, an API host, a DbMigrator, and other executable projects. A microservice solution may have several services with different roles. + +ABP Studio already understands these applications through the solution and run profile. When application tools are available, the agent does not need to rediscover everything from file names or ask me which project is running. It can use ABP Studio's view of the solution. + +That is useful for prompts like: + +```text +Check which application is running and use the relevant runtime information to investigate the problem. +``` + +The benefit is not only convenience. It also reduces mistakes. The agent can reason from the same run profile that I use in ABP Studio, instead of guessing from the repository structure alone. + +## Container Tools + +Many ABP applications depend on infrastructure services while running locally. + +![ABP AI Coding Agent container tools](abp-agent-container-tools.png) + +A solution may need SQL Server, PostgreSQL, Redis, RabbitMQ, OpenIddict-related services, or other containers depending on the template and modules. When something fails, the cause is not always in application code. Sometimes a required container is not running. Sometimes the application cannot reach a dependency. Sometimes the runtime error is only a symptom of an infrastructure problem. + +Container tools give the agent a way to include that part of the environment in the investigation. + +Instead of asking the agent to guess why a database connection fails, I can let it check the container context that ABP Studio already has. The agent can then distinguish between: + +* a code problem, +* a configuration problem, +* a missing or stopped container, +* or a dependency that is running but unhealthy. + +This is one of the places where ABP Studio integration is especially valuable. General coding agents can help with Docker files or connection strings, but they usually do not know the current ABP Studio container state unless I copy it into the prompt. ABP AI Coding Agent can work closer to the actual local development environment. + +## Task Tools + +ABP Studio tasks are another part of the development workflow that should not live outside the agent. + +![ABP AI Coding Agent task tools](abp-agent-task-tools.png) + +Tasks can represent common solution actions. They may run commands, scripts, or workflow steps that are already configured for the solution. If the team uses ABP Studio tasks to standardize local development, the agent should be able to understand and use that same layer. + +That means I can ask for a workflow instead of a raw command: + +```text +Use the available ABP Studio tasks to validate this change. +``` + +The agent can work with the task names and outputs rather than asking me to remember the exact command. This is helpful in larger solutions where the correct validation step is not obvious from a single project file. + +It also keeps the agent aligned with the team's development path. If ABP Studio has the task, the agent can follow that path instead of inventing a one-off command. + +## Build Tools + +Build tools close the loop after an implementation or fix. + +![ABP AI Coding Agent build tools](abp-agent-build-tools.png) + +The agent should not only change files. It should also help verify that the change still builds. + +In a generic coding agent flow, validation often depends on shell access and manually chosen commands. That can work, but it leaves more room for guessing. Which project should be built? Which solution file should be used? Is there an ABP Studio-specific build action already configured? + +With ABP Studio build tools, the agent can use the build context exposed by the platform. That makes prompts like this more natural: + +```text +Apply the fix and run the available build validation. +``` + +For small changes, this may simply confirm that the project compiles. For larger changes, it can become part of a broader loop with tasks, application checks, and monitoring tools. + +The important part is that the agent can move from implementation to validation without requiring me to manually transfer output between tools. + +## A Practical Tool Access Walkthrough + +Let me make this more concrete with a small debugging scenario. + +In the sample application, I deliberately added a runtime exception to the `UpdateAsync` method of `BookAppService.cs`: + +```csharp +throw new Exception("Sample exception for demonstrating integrated tools!"); +``` + +Then I started the application from ABP Studio and triggered the related request from the browser. The only purpose of this setup is to create a real runtime failure that ABP Studio Monitoring can capture. + +The interesting part is not the exception itself. The interesting part is how the agent behaves when the monitoring tool is disabled, and how that changes when the tool is enabled. + +### First, Without The Exception Tool + +For the first run, I kept the monitoring tool that retrieves exceptions disabled. + +![ABP AI Coding Agent with exception monitoring tool disabled](disabled-monitoring-tools.png) + +Then I asked: + +```text +Can you get the latest exception from ABP Studio Monitoring and explain what failed? +``` + +At this point, the agent did not have direct access to the exception tool. So it tried to reason around the problem in other ways. It looked for available information, tried to inspect logs from files, and checked the codebase to understand what might be happening. + +![ABP AI Coding Agent result without exception tool access](without-tool-result.png) + +That is still useful in some cases, but it is not the best debugging flow. The agent is spending time and context trying to reconstruct a runtime failure indirectly. It may eventually find the suspicious code, but it is working from weaker evidence. + +This is exactly why tool access matters. Without the monitoring tool, the agent can reason from files. With the monitoring tool, it can inspect the actual runtime failure. + +### Then, With The Exception Tool Enabled + +For the second run, I enabled the monitoring tool that can retrieve exceptions, such as `get_exceptions`. + +![ABP AI Coding Agent with exception monitoring tool enabled](enabled-monitoring-tools.png) + +Then I asked: + +```text +Now the get_exceptions tool is enabled. Please get the latest exception from ABP Studio Monitoring, identify the failing code path, and suggest the smallest fix. +``` + +This time, the behavior was very different. The agent directly used the integrated exception tool, retrieved the exception details from ABP Studio Monitoring, and connected the runtime error to the failing code path. + +![ABP AI Coding Agent using get_exceptions result](with-tool-result-1.png) + +It also used the enabled logging tool to verify the surrounding context instead of guessing from the source code alone. + +![ABP AI Coding Agent correlating exception with logs](with-tool-result-2.png) + +That is the workflow I want from an integrated coding agent. It does not only say "this code looks suspicious." It checks the exception, follows the evidence, finds the source of the problem, and proposes the smallest fix. + +It is also faster and more efficient. The agent does not need to spend as many tokens searching for indirect clues because ABP Studio can provide the runtime signal directly. + +### Adding Logs And Requests + +After that, I asked the agent to use the available monitoring tools together: + +```text +Use the available monitoring tools to check the related logs and recent requests for this failure. Tell me whether they confirm the same root cause. +``` + +At this point, the agent used the enabled tools for exceptions, requests, and logs. + +![ABP AI Coding Agent checking monitoring tools together](step-3-1.png) + +![ABP AI Coding Agent reviewing exception, request, and log details](step-3-2.png) + +This is where the ABP Studio integration becomes even more valuable. A runtime problem is rarely just one line of code. There is usually a request, a log entry, an exception, and a running application context around it. + +When these tools are available together, the agent can correlate them. It can say, "this request caused this exception, the logs confirm it, and this code path is responsible." + +That is much better than asking the developer to copy each piece manually into the chat. + +### Validating The Fix + +Finally, I asked the agent to validate the result: + +```text +Run the available build or application validation tools and confirm that the problem is fixed. +``` + +The agent used ABP Studio tools to stop the application, build it, and run it again. + +![ABP AI Coding Agent validating the fix with ABP Studio tools](validate-the-fix.png) + +This completes the loop. The agent did not only identify the problem. It used the integrated tools to move through the full flow: + +1. Read the runtime exception. +2. Correlate it with logs and requests. +3. Find the failing code path. +4. Apply or suggest the focused fix. +5. Validate the application again. + +That is the difference I want to highlight in this article. ABP AI Coding Agent is not only a model that can edit files. When ABP Studio tools are enabled, it can participate in the same development workflow I use: observing the running application, understanding the failure, fixing the code, and validating the result. + +## Why This Is Different From Generic Coding Agents + +Tools like Cursor, Claude Code, and Codex are powerful. They can read code, edit files, run commands, and help with many software projects. + +**ABP AI Coding Agent has a different advantage: it is built for the ABP development experience.** + +It is aware of ABP concepts, ABP solution structure, ABP Studio run profiles, application metadata, containers, monitoring, tasks, and build actions. It is also backed by the ABP Platform: ABP Framework, ABP Commercial, ABP Suite, ABP Studio, and the workflows that connect them. + +That platform context matters. When I am building an ABP solution, I do not only want a model that can write C# or TypeScript. I want an assistant that understands the way ABP applications are structured and the way ABP Studio runs them. + +**That makes the starting point simple:** _open the ABP solution, use ABP Studio, [choose the right mode](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-1-agent-plan-and-ask-modes-62wteg9t), enable the tools needed for the task, and work with the agent inside the platform._ + +## Conclusion + +Integrated tools make ABP AI Coding Agent more than a chat window next to the code. They give it a controlled way to work with the same ABP Studio context I already use: **applications**, **containers**, **monitoring**, **tasks**, and **build actions**. + +-> **That helps the agent move from "I think this might be the problem" to "I checked the runtime evidence, found the related code, applied the fix, and validated it."** + +That is the real value of this part of ABP Studio AI. It brings the coding agent closer to the full development experience, from understanding the solution to running it, observing it, fixing it, and checking the result. + +As ABP Studio evolves, more tools can be added to this workflow. That means the agent can become more useful over time without changing the basic idea: _ABP AI Coding Agent works best when it is not isolated from the platform, but integrated into it._ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-application-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-application-tools.png new file mode 100644 index 0000000000..34845eac5b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-application-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-build-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-build-tools.png new file mode 100644 index 0000000000..d1d4559ca1 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-build-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-container-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-container-tools.png new file mode 100644 index 0000000000..ac9c9f9e5a Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-container-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-monitoring-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-monitoring-tools.png new file mode 100644 index 0000000000..73fc3d5355 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-monitoring-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-task-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-task-tools.png new file mode 100644 index 0000000000..89239146fc Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-task-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-tools-overview.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-tools-overview.png new file mode 100644 index 0000000000..5d666173ba Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/abp-agent-tools-overview.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/cover-image.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/cover-image.png new file mode 100644 index 0000000000..7cf80f3905 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/cover-image.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/disabled-monitoring-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/disabled-monitoring-tools.png new file mode 100644 index 0000000000..cc84d05d25 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/disabled-monitoring-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/enabled-monitoring-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/enabled-monitoring-tools.png new file mode 100644 index 0000000000..d2dd9df33b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/enabled-monitoring-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/step-3-1.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/step-3-1.png new file mode 100644 index 0000000000..f6eb90c3ec Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/step-3-1.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/step-3-2.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/step-3-2.png new file mode 100644 index 0000000000..d457d9f220 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/step-3-2.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/tools-with-agent.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/tools-with-agent.png new file mode 100644 index 0000000000..7b0f88ac73 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/tools-with-agent.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/validate-the-fix.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/validate-the-fix.png new file mode 100644 index 0000000000..99a46deb60 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/validate-the-fix.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/with-tool-result-1.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/with-tool-result-1.png new file mode 100644 index 0000000000..ca86fcb3d4 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/with-tool-result-1.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/with-tool-result-2.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/with-tool-result-2.png new file mode 100644 index 0000000000..843b4ac856 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/with-tool-result-2.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/without-tool-result.png b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/without-tool-result.png new file mode 100644 index 0000000000..b381c31fba Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-4-tools/without-tool-result.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/add-mcp-server.png b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/add-mcp-server.png new file mode 100644 index 0000000000..766e0f55a2 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/add-mcp-server.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/add-seo-analyzer-mcp-server.png b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/add-seo-analyzer-mcp-server.png new file mode 100644 index 0000000000..1e98f568da Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/add-seo-analyzer-mcp-server.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/cover-image.png b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/cover-image.png new file mode 100644 index 0000000000..f4baa39fd2 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/cover-image.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/mcp-servers-empty.png b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/mcp-servers-empty.png new file mode 100644 index 0000000000..ea4785c009 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/mcp-servers-empty.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/post.md b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/post.md new file mode 100644 index 0000000000..a28a96edcd --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/post.md @@ -0,0 +1,315 @@ +# Deep Dive on ABP AI Agent #5: MCP (Model Context Protocol) + +When I use an AI coding agent inside ABP Studio, most of the work starts inside the solution. + +The agent can read the code. It can edit files. It can use the ABP Studio tools I enabled. It can build the solution, run tasks, start applications, inspect containers, and check monitoring data when something fails. [In the previous article of this](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-4-integrated-abp-studio-tools-be2xa2om) series, we focused on exactly that: the integrated tools that connect the agent to the ABP Studio development environment. + +But there is another point where plain solution awareness is not enough. + +Sometimes the information I need is not in the repository. It is not in the running application. It is not in the build output, container state, or ABP Studio monitoring screen. + +It may be in a live Prometheus workspace. It may be in Google Search Console. It may be in an SEO analyzer, a documentation system, a database, a customer support tool, or another service that has nothing to do with the ABP solution itself. + +That is where **MCP** becomes useful. + +MCP, short for **Model Context Protocol**, gives ABP AI Coding Agent a standard way to reach external tools and data sources. It does not replace the built-in ABP Studio tools. It extends the agent beyond the solution boundary when the task depends on something outside that boundary. + +> **Note:** ABP AI Coding Agent is available directly to ABP license holders. License holders have predefined credits so they can try the integrated experience without setting up a separate AI workflow first. MCP is one of the ways this experience can be extended when the agent needs access to systems outside ABP Studio. + +## Why MCP Matters + +Most coding agents start from the same place: **the files they can see**. + +That is a good start, but real development work often needs context from somewhere else: production metrics, SEO data, analytics, search performance, customer records, internal APIs, or product knowledge. + +If the agent cannot reach those systems, the developer becomes the bridge: + +- Copy this metric result. +- Paste that SEO report. +- Export this analytics data. +- Summarize this dashboard. +- Explain which production signal matters. +- Tell the agent what the external system says. + +That works, but it is not the best workflow. The more information I manually copy into the chat, the easier it is to miss something, simplify too much, or give the agent an outdated snapshot. + +MCP reduces that manual work. It lets the agent ask an external system for context directly, within the permission boundary I configure. + +The important detail is that MCP is not "the agent can do anything now." It is a controlled extension point. A server is connected. Its tools are listed. Individual tools can be enabled or disabled. The agent can only use what is available in the current session. + +That gives me a practical balance: the ABP-aware development experience stays in ABP Studio, and external context can be added only when the task needs it. + +## What MCP Actually Is + +MCP is an open standard for connecting external tools and data to AI agents. + +Instead of every tool inventing its own integration for every agent, MCP defines a common shape. A program that exposes tools or resources through this standard is called an **MCP server**. An agent that understands MCP can connect to that server and use what it provides. + +For me, the easiest way to think about it is simple: + +- ABP Studio tools connect the agent to the ABP development environment. +- MCP servers connect the agent to systems outside that environment. + +The server might expose a tool for querying Prometheus, checking Search Console data, running an SEO audit, inspecting a database, or calling an internal API. The exact capability depends on the server. + +MCP is not a prompt, a rule, a skill, or a lesson. Those shape what the agent knows or how it behaves. MCP changes what the agent can reach. + +That makes MCP more like equipment than instruction. It gives the agent access to a tool or data source that was previously outside its working area. + +There are already many community and vendor MCP servers for different systems. A useful place to discover examples is the [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) repository, which collects MCP servers across many categories. + +For concrete examples, there are MCP servers for [Prometheus metrics](https://github.com/pab1it0/prometheus-mcp-server), [AWS Managed Prometheus](https://github.com/awslabs/mcp/tree/main/src/prometheus-mcp-server), and [SEO analysis](https://github.com/g-battaglia/mcp-seo). The exact server you choose depends on your environment, but the pattern is the same: expose a focused external capability to the agent through MCP. + +## When You Actually Need It + +Most of the time, I would not start with MCP. + +For normal ABP development, the built-in tools are usually the right first layer. The agent can already work with the solution, run profiles, applications, containers, tasks, builds, monitoring data, and documentation. If the task is completely inside the ABP solution, MCP may not add anything. + +MCP becomes useful when the task crosses the solution boundary. + +For example, I may ask: + +```text +Run an SEO audit for https://abp.io, summarize the weak areas, and suggest which content or technical improvements would matter most. +``` + +Without MCP, I would need to open a separate SEO tool, run the audit, copy the results, and paste them into the chat. With the right MCP server enabled, the agent can call the SEO tool directly and reason from the structured result. + +Or I may ask: + +```text +Connect to our Prometheus MCP server, check the error rate and p95 latency for the AuthServer over the last 30 minutes, and tell me whether the last deployment changed anything. +``` + +That is a very different kind of task. The answer is not in the source code alone. It lives in a monitoring system. Prometheus MCP servers exist for this kind of workflow; for example, some expose tools for instant PromQL queries, range queries, metric discovery, and target inspection. + +Another realistic prompt could be: + +```text +Use Search Console data to find pages that lost traffic this month, then inspect the related docs pages and suggest focused improvements. +``` + +Again, the important part is not that the agent magically knows everything. The important part is that I can connect a specific external system, expose a specific set of tools, and let the agent use them when they are relevant. + +If the work starts outside the codebase but ends inside the codebase, MCP can help connect those two parts of the workflow. + +## Setting Up An MCP Server + +MCP servers are configured under **Settings > MCP Servers**. + +When no server is connected, the page is intentionally simple. It is an empty list waiting for the first server. That is important because MCP should be explicit. If I have not connected a server, the agent should not behave as if it has access to that external system. + +![The MCP Servers page in ABP Studio, before any server is added](mcp-servers-empty.png) + +When I add a server, ABP Studio asks how it should connect. + +There are two main connection types: + +- **Stdio:** ABP Studio runs the MCP server as a local process. I provide the command, arguments, and environment variables the server needs. +- **HTTP:** ABP Studio connects to an MCP server over the network. I provide the URL and any required headers. + +![Adding an MCP server: pick stdio or HTTP, then provide the command, arguments, and environment variables](add-mcp-server.png) + +This is useful because different MCP servers are packaged in different ways. Some are local command-line programs. Some are hosted services. Some need environment variables for tokens or configuration. + +In the example below, I am adding an HTTP MCP server named **SEO Analyzer**. It exposes a small set of SEO-related tools through a remote MCP endpoint. + +![Adding the SEO Analyzer MCP server over HTTP](add-seo-analyzer-mcp-server.png) + +ABP Studio does not require every server to be created manually from scratch. If I already use MCP elsewhere, I can import existing configuration from tools like Cursor, Claude, VS Code, Windsurf, or a plain MCP server JSON file. It can also export configuration in the standard `mcpServers` JSON shape. + +That matters because MCP is an open ecosystem. The same server definition can often move between tools. ABP Studio becomes another place where I can use that server, but now in the context of an ABP-aware agent. + +## What A Connected Server Shows + +After a server is connected, ABP Studio shows the important parts of the connection. + +I can see whether the server is connected, how many tools it exposes, which tools are available, and whether it provides resources. I can also inspect resources directly from the settings page. + +![A connected SEO Analyzer MCP server and its available tools](seo-analyzer-mcp-tools.png) + +This visibility matters because an MCP server is not just a checkbox. It is a surface area. It may expose one tool or many. Some tools may be read-only, and some may perform actions outside the repository. + +The agent does not need me to call those tools manually. I describe the task, and if the tool is available and relevant, the agent can decide to use it. That is why a prompt can stay natural: + +```text +Read the product requirement from the connected knowledge base and compare it with the current implementation. +``` + +The prompt does not need to become a tool invocation script. The agent still owns the reasoning loop. MCP only gives it a new place to look. + +## Tool Access: What The Agent Is Allowed To Use + +The most important part of MCP in ABP Studio is not only connecting servers. It is controlling what the agent is allowed to use. + +Individual tools can be disabled. If a tool is disabled, it is not offered to the agent. The agent should not plan around it, call it, or assume it has access to it. + +That is useful for safety, but also for quality. + +![Disabling individual tools exposed by the SEO Analyzer MCP server](seo-analyzer-mcp-tools-disabled-indivually.png) + +Every enabled tool becomes part of the menu the agent considers. If a server exposes ten tools but the current task only needs two, I usually prefer to enable only those two. A shorter tool list is easier for the agent to choose from. It also makes the session easier for me to reason about. + +The permission model is simple: + +- If a server is not connected, the agent cannot use it. +- If a server is disabled, the agent cannot use its tools. +- If an individual tool is disabled, the agent cannot use that tool. +- If the session is not in Agent mode, MCP tools are not available. + +That last point is important. MCP tools are available in **Agent mode only**. + +Plan and Ask modes are read-only by design. They are useful for understanding, planning, and discussing changes, but they do not receive MCP tools. If I want the agent to call an external MCP tool, I need to work in Agent mode. + +This keeps the model consistent with the rest of the ABP AI Coding Agent experience. The mode determines what kind of work the agent is allowed to perform. + +## Keeping MCP Safe + +MCP is powerful because it lets an AI agent reach systems outside the solution. + +That is also why it needs care. + +An MCP server is a program. It may read files, call APIs, query databases, send requests, or perform actions depending on how it was built. The agent is not inventing those capabilities. It is using what the server exposes. + +So trust matters at two levels. + +First, I need to trust the actions. If a tool can update an issue, send a message, change a record, or trigger a workflow, that is a real side effect. + +Second, I need to trust the descriptions. When an MCP server connects, the names and descriptions of its tools become part of what the model can read. A careless or hostile server can use that text to influence the model before I even write my prompt. + +That means MCP safety is not only about "what can this tool do?" It is also about "what instructions or descriptions does this server place in front of the model?" + +Two habits keep this manageable: + +- Connect only servers I trust. +- Disable tools the agent should not use for the current task. + +This sits on top of the agent's normal guardrails. Shell commands, URL fetches, downloads, and other sensitive actions can still require permission. Also, the tool list is fixed for a running session, so changing a server in the middle of a session does not quietly alter the tool surface already given to that session. + +That is the behavior I want from this kind of integration. MCP can extend the agent, but it should do so through visible, intentional configuration. + +## A Practical MCP Walkthrough + +Let me make this more concrete with a small scenario. + +Imagine I am working on the public website or documentation side of an ABP-based product. The task is not a compiler error or a failing unit test. I want to understand how the website looks from an SEO perspective and what I would improve first. + +Without MCP, I would open a separate SEO tool, run the audit, wait for the result, copy the score, paste the table into the chat, and then ask the agent to interpret it. That is not terrible, but it turns me into a copy-paste integration layer. + +With an SEO Analyzer MCP server connected, I can start from a better prompt: + +```text +Please rate the SEO work on the https://abp.io website on a scale of 1 to 10. I'd also like to know what you would do if you were in charge. +``` + +At that point, the agent can use the SEO Analyzer MCP tool instead of guessing from general SEO knowledge alone. It can call the audit tool, read the structured result, and turn it into a concrete improvement plan. + +![ABP AI Coding Agent using the SEO Analyzer MCP server](using-mcp.png) + +The value is not only that the agent saved me a few seconds. The value is that the agent starts from live tool output instead of a manually summarized report. + +### First, Without The MCP Server + +If no SEO MCP server is connected, the agent cannot run the audit directly. + +It may still give a reasonable answer from general knowledge. It may say that the site should have good titles, descriptions, headings, performance, backlinks, structured data, and content targeting. That advice can be useful, but it is generic. + +For example, I might write: + +```text +Review the SEO of abp.io and tell me what to improve. +``` + +The agent can reason about common SEO practices, but it does not have a fresh audit result. It does not know which categories scored well, which areas are weak, or whether the live page data confirms the concern. + +This is similar to debugging without monitoring tools. The agent can reason, but it is reasoning from weaker evidence. + +### Then, With The MCP Server Enabled + +Now imagine the SEO Analyzer MCP server is connected, enabled, and the relevant audit tool is enabled. + +I can ask: + +```text +Run an audit on https://abp.io, rate the result, and suggest the highest-impact improvements. +``` + +This time the agent can gather the external context first. In the screenshot, the server exposes tools like `run_audit_anonymous`, `run_audit`, `get_audit`, `list_audits`, `get_audit_pdf`, and `get_organic_traffic`. The agent uses the audit tool and then explains the result in human terms. + +That changes the workflow: + +1. Run the external SEO audit. +2. Read the score and category breakdown. +3. Identify the weakest areas. +4. Suggest concrete technical or content improvements. +5. If needed, inspect the related website or documentation files. + +The agent is no longer guessing from best practices alone. It can connect the outside report to the actual website and then, if the relevant files are in the solution, help improve them. + +### Another Example: Live Monitoring + +SEO is only one example. Monitoring is another strong fit for MCP. + +Prometheus MCP servers can expose tools for PromQL instant queries, range queries, metric discovery, targets, and server information. That means I can ask operational questions in natural language while the agent queries the monitoring system through MCP. + +For example: + +```text +Use the Prometheus MCP server to check p95 latency, request rate, and error rate for the public web application after the last deployment. If something changed, identify the most likely area to inspect in the ABP solution. +``` + +That does not mean the agent should blindly change production behavior. It means the agent can start from live evidence: metrics, trends, targets, and recent changes. Then it can use ABP Studio context to inspect the related application, module, or configuration. + +### Combining MCP With ABP Studio Tools + +The best part is that MCP does not replace the ABP Studio tools from the previous article. It works beside them. + +In a real workflow, MCP may provide the outside signal, and ABP Studio tools may provide the inside development loop: + +1. MCP brings in the external context. +2. ABP-aware reasoning maps it to the solution. +3. ABP Studio tools help implement and validate the change. + +That is where the integration becomes more useful than a generic MCP checkbox. The agent is connected to an external tool while still understanding the ABP development environment. + +## How MCP Fits With Everything Else + +MCP is an open standard, so connecting an MCP server is not an ABP-only idea. + +Tools like Cursor, Claude, VS Code extensions, and other AI coding environments can also use MCP. That is part of its appeal. Teams can build or adopt a server once and use it across different tools. + +What makes MCP especially useful in ABP Studio is the company it keeps. ABP AI Coding Agent already understands the ABP solution structure, application layers, modules, migrations, proxies, build actions, run profiles, containers, monitoring data, and official ABP documentation. MCP adds the outside world to that picture. + +So I do not need to choose between: + +- an agent that understands ABP, +- and an agent that can reach my team's external systems. + +The better experience is both together, under visible configuration. Put simply: + +- Built-in ABP Studio tools handle the solution and runtime environment. +- MCP servers handle external tools and data sources. +- Rules, skills, and lessons shape how the agent behaves. +- Agent mode decides whether tool use is available for the session. + +Each part has a different role. Keeping those roles clear makes the agent easier to trust. This is also why I would start small in a real team workflow: one low-risk, high-value server, probably a read-only analytics, documentation, or monitoring server, with only the tools that support a clear workflow enabled. + +MCP by itself is a protocol. The difference in ABP Studio is that MCP becomes part of an ABP development session. The agent can read an external SEO report or monitoring signal, but it can also understand which ABP application, module, page, or configuration owns the behavior and validate the change with ABP Studio tools. + +Most real tasks are not only "call an external tool." They are more like: + +1. Understand the requirement from outside the repository. +2. Find where that behavior lives in the ABP solution. +3. Make the smallest correct change. +4. Validate it in the same development environment. + +MCP helps with the first part. ABP Studio AI helps connect the rest. + +**That makes MCP valuable not because it is another tool list, but because it extends the ABP AI Coding Agent beyond the repository without disconnecting it from the ABP workflow.** + +## Conclusion + +MCP is the agent's connection to everything that is not already inside the ABP solution. + +You will not need it for every task. But when the work depends on SEO data, live metrics, external documentation, internal services, or team knowledge, MCP gives the agent a standard way to reach that context. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/seo-analyzer-mcp-tools-disabled-indivually.png b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/seo-analyzer-mcp-tools-disabled-indivually.png new file mode 100644 index 0000000000..e1b631f99c Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/seo-analyzer-mcp-tools-disabled-indivually.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/seo-analyzer-mcp-tools.png b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/seo-analyzer-mcp-tools.png new file mode 100644 index 0000000000..2160b389e0 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/seo-analyzer-mcp-tools.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/using-mcp.png b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/using-mcp.png new file mode 100644 index 0000000000..68810c6915 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-5-mcp/using-mcp.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/cover-image.png b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/cover-image.png new file mode 100644 index 0000000000..67e2819cac Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/cover-image.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-commit-message.gif b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-commit-message.gif new file mode 100644 index 0000000000..553e5b2b78 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-commit-message.gif differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-review-details.png b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-review-details.png new file mode 100644 index 0000000000..8e4c43718d Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-review-details.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-review.png b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-review.png new file mode 100644 index 0000000000..572ec3d4b7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-ai-review.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-branch-and-stash.png b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-branch-and-stash.png new file mode 100644 index 0000000000..5f5d9078a9 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-branch-and-stash.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-changes-and-diff.png b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-changes-and-diff.png new file mode 100644 index 0000000000..dabd936b88 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-changes-and-diff.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-diff-comments.png b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-diff-comments.png new file mode 100644 index 0000000000..5ace3ff8eb Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-diff-comments.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-initialize-repository.png b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-initialize-repository.png new file mode 100644 index 0000000000..fcf2ad3929 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/git-initialize-repository.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/post.md b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/post.md new file mode 100644 index 0000000000..18036a1da3 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-6-abp-studio-git-integration/post.md @@ -0,0 +1,212 @@ +# Deep Dive on ABP AI Agent #6: ABP Studio Git Integration + +When I use an AI coding agent, I do not only care about whether it can change files. + +I care about what happens around those changes. + +Which branch am I on? What exactly changed? Can I review the diff before I commit? Did I accidentally touch a file from another package? Is my branch behind the default branch? If a pull request already has feedback, can I bring that context back into the coding session without copying every comment by hand? + +That is where Git integration in **ABP Studio** becomes important. + +Git is not just the final step after the agent finishes. For me, it is the confidence layer around the whole workflow. It helps me keep AI-assisted work reviewable, recoverable, and connected to the same team process I already use every day. + +![ABP Studio Git Integration cover](cover-image.png) + +## Git In The AI Workflow + +Most development work is not a straight line from prompt to done. + +I may ask ABP Agent to make a small change, then review the diff and adjust the direction. I may ask it to address feedback from a pull request. I may start from a GitHub issue, create a branch, let the agent investigate, and then decide which changes are ready to commit. + +In all of those moments, Git gives me a practical boundary: + +* this is the branch I am working on, +* these are the files that changed, +* this is the diff I need to review, +* this is the commit I am about to create, +* and this is the context I want to send back to the team. + +Without a Git-aware workflow, AI changes can feel a little too loose. The agent may be productive, but I still need a clean way to inspect, group, commit, push, and discuss the result. + +ABP Studio Git Integration brings that loop into the same place where I already work with the solution and the agent. + +## Initializing Git For A Solution + +The Git panel starts with the active solution. + +If the solution is not a Git repository yet, ABP Studio does not pretend otherwise. It shows a simple empty state and lets me initialize Git from there. I can choose the initial branch name, create a `.gitignore`, and create the first commit. + +![Initializing Git for an ABP solution in ABP Studio](git-initialize-repository.png) + +That is useful for new ABP solutions because the first Git step is part of the project setup, not something I need to remember after the fact. + +If I want to put the solution on GitHub, Studio can also help with that path. After connecting my GitHub account, I can publish the repository under my account or an organization, choose the repository name, add a description, and decide whether it should be private. + +The small but important detail is that Git becomes part of the solution experience early. I do not need to move from ABP Studio to a separate Git tool just to create the repository before I start working with ABP Agent. + +## Changed Files And Diff Review + +Once Git is active, the Git panel becomes the place I check after an agent session or a manual edit. + +I can see the current branch, remote state, changed files, and the selected file diff. The changes are not only a flat list. In an ABP solution, they can be grouped in a way that follows the solution structure, so changes under different packages or solution areas are easier to scan. + +![Changed files and diff review in ABP Studio Git Integration](git-changes-and-diff.png) + +That grouping matters in real ABP work. + +If I asked ABP Agent to adjust a public web page, but I see changes in an admin package, I immediately know to slow down and review why. If a change touches a contract package and a UI package, the grouping helps me understand that relationship before I commit. + +The diff viewer is also part of the same loop. I do not need to leave the workspace just to answer the basic review question: + +```text +What did this task actually change? +``` + +That is the question I want to answer before a commit, especially when AI helped produce the diff. + +## Selected Files And Commit Messages + +Committing is not only pressing a button. + +I still want to choose which files belong together. I still want the commit message to match the change. I still want to avoid committing work on a protected branch by accident. + +ABP Studio keeps that flow visible. I can select the files I want, write a summary and description, and commit to the current branch. When AI is enabled, Studio can generate a commit message from the selected diffs. + +![Generating a commit message from selected changes](git-ai-commit-message.gif) + +I like this because it keeps the AI help close to the actual diff. + +A generic prompt like "write a commit message" depends on what I paste into the chat. In Studio, the commit message generator can work from the selected files. That makes the result more focused, and I still stay in control because the generated text lands in the commit fields before I use it. + +The protected branch warning is another important part of the experience. If the current branch should not receive direct commits, Studio makes that visible and pushes me toward the safer workflow: create a branch, review the diff, then commit there. + +That is the right kind of guardrail. It does not make Git complicated. It makes the normal team habit harder to miss. + +## Branching, Stashing, And Syncing + +AI-assisted development often starts with a branch decision. + +Sometimes I am starting fresh from the default branch. Sometimes I am building on work already in my current branch. Sometimes I have local changes and need to switch context without losing them. + +ABP Studio exposes those decisions in the Git panel. + +I can create a branch, switch branches, update from the default branch, fetch, pull, push, and see whether I am ahead or behind. If I switch branches while I have local changes, Studio asks what should happen to that work: leave it behind as a stash or bring it with me. + +![Branch switching and stashed changes in ABP Studio](git-branch-and-stash.png) + +That choice is more important than it looks. + +When I am working with an agent, I do not want local changes to silently follow me into the wrong branch. I also do not want to lose half-finished work just because I need to inspect another issue. The stash flow turns that into an explicit decision. + +The same idea applies to sync. + +If my branch is behind, I can update before I continue. If I have local commits, I can push them. If a merge or pull produces conflicts, Studio shows the conflicted files and gives me a path to resolve, abort, continue, or send the conflict context to ABP Agent. + +That keeps the Git workflow close to the coding workflow. I can move from change to review to sync without mentally switching tools. + +## AI Review And Manual Diff Comments + +There is a moment before a commit where I often want a second look. + +Not a full pull request review. Not a long architecture discussion. Just a focused pass over the files I selected: + +```text +Does this diff contain something suspicious? +Did the agent miss a small edge case? +Is there a line I should check again before committing? +``` + +ABP Studio supports that with AI review on selected Git changes. + +![AI review suggestions on selected Git changes](git-ai-review.png) + +![AI review suggestions on selected Git changes](git-ai-review-details.png) + +AI review is not the only way to leave notes on a diff. I can also write my own comments directly on changed lines while I am reviewing. + +![Manual comments on Git diff in ABP Studio](git-diff-comments.png) + +The useful part is that the review is attached to the diff. Suggestions and notes appear near the changed lines, and if there is something I want the agent to handle, I can send those review notes to ABP Agent. + +That changes the feel of the workflow. + +Instead of asking the agent to code and then manually re-explaining my review comments, I can turn the review result back into a task. Whether a note comes from AI review or from something I wrote myself, the agent gets the file, line, and note context. I still review the result, but I spend less time copying context between places. + +Git also helps with recovery. In a Git repository, ABP Studio can offer **Back to this point** in the agent conversation. For me, that is a comfort feature: if an agent turn takes the work in the wrong direction, I can return to an earlier point instead of manually untangling every changed file. + +I still treat Git commits as the real checkpoints for team work. But during a live agent session, being able to go back to a previous point makes experimentation feel less risky. + +## GitHub Issue Context + +Many tasks do not start as a prompt. They start as an issue. + +The issue has the requirement, comments, labels, screenshots, and sometimes a conversation about what is expected. If that context stays only in the browser, I have to copy it into the agent manually. + +ABP Studio can bring GitHub issues into the Git area. + +I can filter issues, open one, read the description and comments, create a branch for that issue, and send the issue context to ABP Agent. + + + +That makes the workflow feel natural: + +1. Pick the issue. +2. Create a branch for it. +3. Send the relevant context to ABP Agent. +4. Let the agent inspect the solution and implement the change. +5. Review the Git diff before committing. + +The important detail is that the agent starts from the same context I would start from as a developer. It sees the issue title, description, labels, included comments, and attached images when they are part of the selected context. + +That is much better than writing a vague prompt that tries to summarize the issue from memory. + +## Pull Request Feedback Context + +Pull request feedback is another place where Git integration helps the AI workflow. + +When I open a pull request inside ABP Studio, I can see the PR title, branches, comments, reviews, and requested changes. If I am not on the PR branch, Studio can switch to it. Then I can choose which comments or requested changes should be included and send that context to ABP Agent. + + +This is the workflow I want when a reviewer asks for changes: + +* read the feedback, +* switch to the right branch, +* include only the relevant comments, +* send the request to ABP Agent, +* review the resulting diff, +* commit and push. + +The include and exclude controls matter here. Not every PR comment should become an agent instruction. Some comments are discussion, some are already resolved, and some are optional. I want to choose what becomes context. + +That keeps the agent from treating the entire PR timeline as one undifferentiated command. I can shape the task before sending it. + +## Git Integration In The Deep Dive Series + +In the earlier articles, we looked at modes, tools, MCP, scopes, and workflows. + +Git integration connects those ideas to the normal development lifecycle. + +* **Ask and Plan** help me understand and shape the work. +* **Agent mode** can make the change. +* **Tools** help the agent use ABP Studio context. +* **Scopes** keep the working area focused. +* **Workflows** make repeated actions predictable. +* **Git integration** lets me review, recover, commit, push, and collaborate around the result. + +That last part is easy to underestimate. + +The value of an AI coding agent is not only how quickly it can modify files. The value is whether I can bring those modifications into a professional development workflow without losing control. + +Git is the structure that makes that possible. + +## Conclusion + +ABP Studio Git Integration makes ABP Agent feel more grounded. + +It gives me a clear path from issue to branch, from agent work to diff review, from selected files to commit, and from pull request feedback back into the agent. + +For everyday work, that means fewer context switches. For AI-assisted work, it means more confidence. + +I can let the agent help, but I do not have to accept the result blindly. I can inspect the diff, ask for a review, commit intentionally, push when ready, and keep the whole process connected to GitHub and the team workflow. + +That is the part I value most: **Git integration turns AI output into reviewable development work.** diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/ai-agent-panel.png b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/ai-agent-panel.png new file mode 100644 index 0000000000..c0fcd9a3e7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/ai-agent-panel.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/auth-identity-scope.png b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/auth-identity-scope.png new file mode 100644 index 0000000000..1fb92ec9ca Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/auth-identity-scope.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/post.md b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/post.md new file mode 100644 index 0000000000..4b9aa4b8d7 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/post.md @@ -0,0 +1,157 @@ +# Deep Dive on ABP AI Agent #7: Scopes + +When I use an AI coding agent in a real ABP solution, I do not always want it to see everything. + +That may sound strange at first. More context usually feels better. But in a large solution, more context can also mean more noise, more unrelated files, and more chances for the agent to drift into an area that is not part of the task. + +If I am working on the public side of a modular application, I do not want the agent to redesign the admin side. If I am changing a Catalog module, I do not want it to spend half the session reasoning about Identity, SaaS, or Payment code. If I am fixing one microservice, I do not want the agent to treat the whole platform as editable surface area. + +That is where **AI Scopes** become one of the most important control features in **ABP Studio AI Coding Agent**. + +## Why Scopes Matter? + +Most AI coding agents are very good at reading a folder and making changes. That is useful, but an ABP solution is rarely just a folder. + +An ABP solution can contain modules, packages, applications, gateways, background workers, database projects, shared contracts, UI projects, and infrastructure configuration. In a microservice solution, the repository may contain multiple independently meaningful services. In a modular monolith, a single solution may still have clear business boundaries. + +-> In those situations, the question is not only: **Can the agent understand the solution?** ❌ + +-> The better question is: **Which part of the solution should the agent be allowed to work with for this task?** ✅ + +AI Scopes answer that question directly. + +They let me choose the accessible area before the session starts. The agent can then focus on the relevant module, package, solution area, or external folder instead of treating the entire repository as equally relevant. + +For me, that changes the feeling of using an AI agent. It is no longer "here is my whole codebase, please be careful." It becomes "here is the part of the system this task belongs to, work inside that boundary." + +## What An AI Scope Controls? + +An AI Scope **restricts which directories the agent can access during a session**. + +![Auth and Identity scope configuration in ABP Studio](auth-identity-scope.png) + +Depending on the task, a scope can include: + +* the whole solution, +* selected modules, +* selected packages, +* selected external folders, +* or a focused combination of these. + +The important part is that this is not only a prompt suggestion. It is part of the session context and file access boundary. File paths used by the agent are validated against the resolved scope. If a file is outside the accessible directories, the agent should not treat it as part of the editable workspace. + +Scopes also work together with `.abpignore`. Even if a file is under an accessible directory, files excluded by `.abpignore` remain blocked. That gives teams two useful layers: + +* **Scopes** decide which solution areas are relevant to the task. +* **`.abpignore`** protects files that should stay inaccessible, such as secrets, certificates, environment files, or other sensitive local data. + +This is a practical control model. I can narrow the agent's working area without pretending that the repository is smaller than it really is. + +## Scope Is Locked To The Session + +Another detail I like is that scope belongs to the AI Agent session. + +The first message of a session locks the configuration that affects the system prompt, including the active AI Scope. If a background session continues running and I change the foreground scope later, that running session does not silently change its context. + +That matters when multiple sessions are active. + +![Selected AI scope shown in the agent session panel](selected-scope.png) + +Imagine I have one session working on a Catalog module and another session answering questions about the whole solution. Those sessions should not accidentally share a changing boundary. Each one should keep the scope it started with. + +This makes scopes more predictable. I can choose the scope intentionally at the beginning of the work and trust that the session is tied to that decision. + +## Focused Autonomy + +Scopes are not about making the agent weaker. They are about making autonomy more focused. + +When I narrow the scope, I am not saying the agent is less capable. I am saying the task has a boundary. + +For example: + +```text +Use the Public AI Scope. +Add a small validation improvement to the public product search flow. +Do not inspect or change the Admin side unless you find a direct contract dependency. +``` + +That kind of prompt becomes much stronger when the selected scope already matches the instruction. The agent receives both the natural-language task and the platform-level boundary. + +This is especially useful for ABP because ABP applications are built around clear concepts: modules, layers, packages, application services, repositories, DTOs, permissions, localization resources, DbContexts, and run profiles. A scope can follow those boundaries instead of relying only on a long prompt. + +## What Scopes Help Prevent? + +Scopes help reduce a few common AI-agent failure modes. + +- First, they reduce **unrelated exploration**. The agent does not need to spend time discovering files that have nothing to do with the task. +- Second, they reduce **accidental edits**. When a task belongs to one module, the agent should not casually change another module just because it found a similar type there. +- Third, they improve **reviewability**. If I scoped the task to `Catalog`, and the diff changes `Identity`, that is immediately suspicious. The boundary makes the review easier. +- Fourth, they support **parallel work**. Different sessions can be scoped to different areas, which is useful when independent tasks are running in the same solution. + +This is one of the places where ABP AI Coding Agent feels different from a generic coding tool. The feature is not only "the model can read fewer files." It is integrated into ABP Studio's understanding of the solution. + +## Scopes And ABP Solution Architecture + +ABP already encourages clear boundaries. + +In a layered module, the Domain layer should not depend on the Application layer. HTTP API projects should depend on contracts, not implementation projects. Entity Framework Core and MongoDB integrations should stay behind the domain abstractions. A reusable module should be understandable as a module, not only as a set of files. + +AI Scopes fit naturally into that mindset. + +If I am working on a Domain change, I can keep the scope close to the module and its required shared contracts. If I am working on UI behavior, I can include the UI package and the related contract package. If I am working on a microservice, I can scope the agent to that service and only add external folders when they are truly required. + +That means the agent's working area can follow the same mental model I already use as an ABP developer: + +```text +What bounded area owns this change? +Which packages are needed to make it safely? +Which parts of the system should stay out of this session? +``` + +## Scopes And Workflows Work Better Together + +- Scopes define **where** the agent can work. +- Workflows define **what deterministic actions** should happen around that work. + +![ABP AI Coding Agent panel showing scopes and workflows combined](scopes-openning.png) + +That combination is powerful. For example, I can scope the agent to the `Catalog` module and use a workflow that builds the affected package, regenerates proxies if contracts changed, and restarts the related application. + +The scope keeps the coding session focused. The workflow keeps the verification loop repeatable. + +This is the larger ABP Studio AI story. It is not only an AI chat window. It is an agent inside a platform that already understands ABP solutions, run profiles, tools, workflows, Git state, and runtime signals. + +## Why This Is Different From Generic Coding Agents? + +Tools like Cursor, Claude Code, Codex, and Windsurf are strong general-purpose coding tools. They can read files, edit code, run shell commands, and help with many projects. + +**ABP AI Coding Agent is different because it is built around ABP Studio's view of an ABP solution.** + +Scopes are a good example of that difference. + +In a generic tool, I can try to simulate scope with a prompt: + +```text +Only work in this folder. +``` + +That is helpful, but it is still mostly an instruction. In ABP Studio, scope is part of the agent session and file access model. It can be selected intentionally before the work starts, stored with the session, and combined with `.abpignore`, workflows, tools, plans, and run profile context. + +For professional ABP teams, that matters. The goal is not to give an AI agent unlimited access and hope the prompt is clear enough. The goal is to create a controlled development loop where the agent understands the system, works in the right area, uses the right tools, and produces a diff that is easier to trust. + +## Conclusion + +AI Scopes make ABP Studio AI Coding Agent feel more deliberate. + +They let me say: + +* this is the part of the solution that matters, +* this is the boundary for the current session, +* this is the context the agent should focus on, +* and everything else should stay outside unless we intentionally expand the scope. + +That is exactly the kind of control I want when using AI in real ABP solutions. + +The agent can still be powerful. It can still plan, edit, build, run tools, and iterate. But with scopes, that power is pointed at the right part of the system. + +That is the real value: **not just more AI autonomy, but better-shaped AI autonomy for ABP development.** diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/scopes-openning.png b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/scopes-openning.png new file mode 100644 index 0000000000..6297b817e8 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/scopes-openning.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/selected-scope.png b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/selected-scope.png new file mode 100644 index 0000000000..b9039e28c2 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-7-scopes/selected-scope.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/cover-image.png b/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/cover-image.png new file mode 100644 index 0000000000..4ba1f3f4c8 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/cover-image.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/model-settings.png b/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/model-settings.png new file mode 100644 index 0000000000..1f130d4888 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/model-settings.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/post.md b/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/post.md new file mode 100644 index 0000000000..67f9279082 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-8-parallel-agent-execution/post.md @@ -0,0 +1,90 @@ +# Deep Dive on ABP AI Agent #8: Parallel Agent Execution + +Real work rarely lines up one task at a time. + +While the agent is busy adding a feature, a question comes up about a different module. A review is waiting. A small fix would take two minutes, but the agent is in the middle of something else. With a single session, you wait. You watch one task finish before you can start the next, even when the two have nothing to do with each other. + +ABP Studio does not make you wait. It can run several agent sessions at the same time, each on its own task. + +## Parallel Agent Sessions + +A session is one conversation with the agent. It has its own history, its own mode, its own model, its own scope, and its own workflow. ABP Studio keeps multiple sessions per solution, and they can run in parallel. + +There is a limit, and it is there on purpose. By default you can run up to **3 sessions at once**, and you can set that anywhere from **1 to 5**. When you send more prompts than there are open slots, the extra ones are queued and start as soon as a slot frees up. + +So "parallel" here is not a trick of switching back and forth quickly. The sessions actually run at the same time, up to the limit you choose. + +## Parallel Session Use Cases + +The point is to stop letting one task block another. A few ways it plays out: + +* One session implements a feature while another answers questions about a different part of the solution. +* Two unrelated modules get worked on at once, each in its own session. +* One session writes the code while another reviews a diff or does research. + +Because each session is separate, you can even point them at different parts of the solution and give them different jobs: + +```text +Session 1 (Agent): Add a Category screen to the Catalog module. +Session 2 (Ask): Explain how permissions flow from the API to the UI. +``` + +The first one edits files. The second one only reads and answers. They do not interfere, because they are different sessions with different settings. + +## Per-Session Settings Isolation + +This is the part that makes parallel work predictable instead of chaotic. + +When a session sends its first message, two things happen at different levels. The session permanently locks its **scope** and **workflow**—these stay fixed for the entire session lifetime and cannot be changed once the first message is sent. On the other hand, the **model**, **mode**, and **active tools** are snapshotted fresh at each run (each turn the agent takes), so they reflect whatever is configured at the moment the run starts but remain stable for its duration. + +That matters the moment you have more than one session open. Say one session is running in the background, scoped to the `Catalog` module. You switch the foreground to a different scope to start a second task. The background session does not notice. It keeps the scope and workflow it was locked to, and each of its runs uses whatever model and tools were configured at the moment that run began. + +Without this, parallel sessions would quietly corrupt each other every time you changed a setting. With it, each session is a sealed unit of work. + +## The Prompt Queue + +You do not have to wait for a session to be idle to line up its next step. + +While a session is running, you can queue more prompts on it. They attach to the same session and are sent one after another, each after the current turn finishes. The queue keeps the session's settings, so a queued prompt runs with the same mode, scope, model, workflow, and active plan as the rest of that session. + +This works together with the concurrency limit. Prompts that cannot start right away, because every slot is busy, simply wait their turn instead of failing. + +## Keeping Parallel Work Safe + +Running several sessions at once is powerful, and it also gives you a new way to get in your own way: two sessions editing the same files. + +ABP Studio helps here, but it does not pretend the problem away. It tracks file changes, so if one session edited a file after another session read it, the second is told to read it again before overwriting. It also serializes operations that cannot safely overlap, such as adding a migration while a build is running, so two sessions do not run conflicting `dotnet` commands at the same time. And because each session tracks its own pending questions, one session waiting on your input does not freeze the others. + +Still, the simplest rule is the best one: keep parallel Agent-mode sessions on separate parts of the solution. This is exactly where scopes earn their place. Give each session its own scope, and they stay in their own lanes by design instead of by luck. + +## A Second Kind Of Parallel: Subagents + +There is also a smaller, quieter form of parallel work that happens inside a single session. + +When the agent needs to look something up, it can fan out multiple **subagents** in a single turn: read-only helpers that research in parallel and return their results before the main agent continues. There are a few kinds, each with a narrow job: + +* one that researches your solution and code, +* one that searches the web, +* one that searches and reads the official ABP documentation. + +These research-style subagents (code research, web search, documentation search) are read-only—they cannot modify files or solution state. They only read, gather, and hand back a short summary. That keeps the main session's context clean, because the digging happens elsewhere and only the answer comes back. (Note that the browser subagent is an exception: it is stateful and can mutate the shared browser session.) + +ABP Studio can use a separate model for research subagents, configured apart from your main one. A fast, cheap model is the right choice for this kind of lookup work. + +![Model Settings: the research model used by subagents is set separately from the main model](model-settings.png) + +So there are two scales of parallel here. Sessions run independent tasks side by side. Subagents run read-only research inside one task. Both keep the slow parts from blocking the useful parts. + +## ABP Studio Parallel Execution Model + +Plenty of tools let you open more than one chat, and that is genuinely useful. So the idea of running agents in parallel is not, by itself, an ABP feature. + +The difference is that each session here carries the context of an ABP solution and stays inside it. A session locks its scope and workflow permanently, and snapshots its model and tools per run, so background work does not drift when you change the foreground. Studio coordinates the operations that would otherwise collide, like builds and migrations, across all the running sessions. And scopes give each session a clear boundary, so parallel does not turn into a pile of agents editing the same files. + +In short, the parallelism is not just several chat windows. It is several controlled, solution-aware sessions that know how to stay out of each other's way. + +## Conclusion + +Parallel execution is about respecting how work actually arrives: more than one thing at a time, often unrelated. + +ABP Studio lets you run several agent sessions together, each sealed to its own settings, with a queue for what comes next and guardrails for the places where parallel work could collide. Inside each session, subagents add a second layer of parallel research without cluttering the main task. diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/ai-agent-panel.png b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/ai-agent-panel.png new file mode 100644 index 0000000000..c0fcd9a3e7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/ai-agent-panel.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/post.md b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/post.md new file mode 100644 index 0000000000..5d739b1588 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/post.md @@ -0,0 +1,209 @@ +# Deep Dive on ABP AI Agent #9: Workflows + +There is a pattern I see in almost every real development session. + +The interesting part is the code change, but the repeated part is everything around it: + +* start the containers, +* build the affected packages, +* add a migration if the model changed, +* regenerate proxies if the API contract changed, +* restart the application, +* run the validation task, +* check the logs when something fails... + +When I work alone, I can do those steps manually. When I work with an AI coding agent, I do not want to keep pasting the same checklist into every prompt. I want the tool to understand that this solution has a normal way of preparing, validating, and recovering after changes. + +That is the point of **ABP Studio AI Agent Workflows**. + +![ABP Studio AI Agent Workflows overview](workflow.jpg) + +Workflows let me define repeatable actions around an agent run. The model can focus on the ambiguous part, understanding the requirement and changing the code, while ABP Studio handles the deterministic parts that should happen before or after the work. + +That combination is one of the clearest differences between **ABP AI Coding Agent** and a generic coding assistant. It is not only an editor with a chat panel. It is an agent inside a platform that **already knows how to build, run, migrate, generate proxies, manage containers, execute tasks, and inspect runtime signals.** + +## Why Workflows Matter? + +LLMs are powerful because they can reason through unclear requirements and modify code across files. But many development steps should not be creative. + +If the team always builds a package after an application service change, that should be predictable. If API contract changes require proxy generation, that should not depend on whether I remembered to mention it. If a local run needs containers before the application starts, that setup should not be reinvented in every prompt. + +Workflows give ABP Studio a place to encode those repeatable steps. + +_**Choose a Workflow and Scope before sending your prompt:**_ + +![Opening the workflow settings panel in ABP Studio](workflows-openning.png) + +_**The selected workflow can be configured through Workflow Settings, where you can create, edit, and manage reusable workflows for common development tasks:**_ + +![ABP AI Agent workflow settings](workflow-settings.png) + +For me, the value is not only automation. It is also consistency. + +Instead of asking: + +```text +Please implement this, and then build, and maybe regenerate proxies, +and restart the app, and also add a migration if needed. +``` + +I can configure the workflow once and let the agent session carry that context. + +![Sample ABP AI Agent workflow configuration](sample-workflow-1.png) + +That makes the prompt cleaner: + +```text +Add the missing status filter to the order list. +Use the selected workflow for validation after the change. +``` + +The workflow becomes part of the development environment, not a long instruction I repeat manually. + +## Before And After The Agent Works + +An AI Agent workflow has two sides: + +* **Before steps** prepare the environment before the agent starts coding. +* **After steps** guide the validation and follow-up work after the main task is complete. + +Before steps run automatically in **Agent** mode. They are useful for setup actions that should happen before the model receives control, such as starting containers or running a preparation task. + +Plan and Ask modes are read-only, so they do not execute before steps. That separation is important. If I am only asking a question or asking for a plan, I do not want Studio to start applications or run mutation-oriented tooling. + +After steps are injected into the agent instructions as post-task guidance. The agent is expected to run the relevant post-steps after completing the work, but it can skip actions that do not apply. + +For example, if my workflow includes "Add Migration" but the change does not touch the EF Core model, the agent should not create an empty migration just because the workflow exists. The workflow gives deterministic options, but the agent still uses the actual change to decide what is relevant. + +## What A Workflow Can Do? + +Workflow actions are built around the things ABP developers already do in ABP Studio. + +![ABP AI Agent workflow actions](workflow-actions.png) + +The supported actions include: + +* **Build** the solution, selected modules, selected packages, or configured targets. +* **Start Application** for selected applications, folders, or all runnable applications. +* **Stop Application** when validation needs a clean state. +* **Restart Application** after code changes. +* **Start Containers** for databases, caches, message brokers, or other dependencies. +* **Stop Containers** when the workflow needs to clean up. +* **Run Task** for configured ABP Studio tasks. +* **Add Migration** when entity changes require a database migration. +* **Generate C# Proxies** after contract changes. +* **Generate Angular Proxies** after API changes consumed by Angular clients. + +That list is very ABP-specific. + +A generic coding tool can run shell commands, and that is useful. But ABP Studio workflows know about ABP Studio concepts: applications, containers, run profile tasks, packages, modules, migrations, and proxy generation. The agent can use those as first-class actions instead of trying to infer everything from terminal commands. + +## Personal And Shared Workflows + +Workflows can be personal or shared. + +![Sharing an ABP AI Agent workflow with the team via run profile](shared-with-team.png) + +- A **personal workflow** is stored locally under the solution workspace. It is useful for my own development habits. Maybe I like restarting a specific app after each agent turn. Maybe I have a local task that only makes sense on my machine. +- A **shared workflow** is stored with the active run profile. That makes it suitable for source control and team usage. + +This is where workflows become more than a convenience feature. A team can encode its normal AI-agent validation path into the solution itself. + +For example: + +```text +Before: +- Start required containers +- Run the prepare-local-environment task + +After: +- Build affected packages +- Generate Angular proxies when contracts changed +- Restart the Web and API applications +- Run the smoke-test task +``` + +Every developer using that run profile can work with the same repeatable loop. The workflow does not replace code review or testing, but it raises the baseline for what happens after the agent touches code. + +## Workflows Make AI More Deterministic Where It Should Be + +- I do not want the model to creatively decide whether my team usually runs proxy generation. I want the workflow to encode that. +- I do not want every prompt to include a long validation checklist. I want the workflow to carry it. +- I do not want an agent to guess which applications belong to the local run. I want ABP Studio's run profile to provide that context. + +This is why workflows are such a strong fit for ABP Studio AI Coding Agent. The model stays flexible where flexibility helps, and the platform stays deterministic where determinism matters. + +The result is a cleaner division of responsibility: + +| Responsibility | Best handled by | +| --- | --- | +| Understanding the requirement | AI Agent | +| Finding and editing relevant code | AI Agent | +| Starting known containers | Workflow | +| Running known tasks | Workflow | +| Adding migrations when needed | Agent using workflow action | +| Generating proxies when contracts change | Agent using workflow action | +| Building affected packages | Workflow / Studio tools | +| Investigating runtime failures | Agent using monitoring tools | + +## Workflows And Scopes Together + +Workflows are even better when combined with AI Scopes. + +Scopes define where the agent can work. Workflows define what repeatable actions should happen around that work. + +For example, I can select a `Catalog` scope and a workflow that: + +* builds the `Catalog` package, +* regenerates proxies if contracts changed, +* restarts the public web app, +* checks recent exceptions after restart. + +That is a focused agent loop. The agent does not need the whole repository, and the validation path does not need to be invented from scratch. + +This is the kind of full flow that makes ABP AI Coding Agent feel different from tools that only operate at the file-and-terminal level. + +## Why This Is Different From Generic Coding Agents + +Generic coding agents can be excellent: Cursor, Claude Code, Codex, Windsurf, and similar tools can read code, edit files, run shell commands, and help across many kinds of projects. + +But ABP Studio AI Coding Agent is built for a different experience: **It works inside ABP Studio, where the solution already has run profiles, applications, containers, tasks, modules, packages, migrations, proxy generation, monitoring, Git integration, and ABP-aware analysis.** + +Workflows use that platform context. + +Instead of saying: + +```text +Run whatever commands seem appropriate. +``` + +I can say: + +```text +Use the selected ABP Studio workflow. +``` + +That is a very different contract. The workflow is _visible, configurable, repeatable, and tied to the solution_. + +For ABP teams, this matters because the development process is not only code generation. It is code generation plus build, migration, proxy generation, application restart, runtime observation, and review. + +ABP Studio AI Coding Agent is designed for that full loop. + +## Conclusion + +Workflows make ABP Studio AI Coding Agent more practical for real development. + +They let me move repeated setup and validation steps out of my prompt and into the platform: + +* start what needs to be running, +* build what needs to be built, +* generate what needs to be regenerated, +* migrate when a model change requires it, +* restart the relevant apps, +* and continue the debugging loop with runtime evidence. + +That is why I see workflows as one of the features that makes ABP AI Coding Agent feel complete. + +The agent is not isolated from the development environment. It works inside ABP Studio, with the same solution structure, run profile, tools, and team workflow that I already use. + +That is the difference: **not just AI-generated code, but an AI-assisted ABP development flow from change to validation.** diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/sample-workflow-1.png b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/sample-workflow-1.png new file mode 100644 index 0000000000..b834ee979b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/sample-workflow-1.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/shared-with-team.png b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/shared-with-team.png new file mode 100644 index 0000000000..08257f286b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/shared-with-team.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow-actions.png b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow-actions.png new file mode 100644 index 0000000000..08d906d188 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow-actions.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow-settings.png b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow-settings.png new file mode 100644 index 0000000000..e539c3cf65 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow-settings.png differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow.jpg b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow.jpg new file mode 100644 index 0000000000..f7b8e5774b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflow.jpg differ diff --git a/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflows-openning.png b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflows-openning.png new file mode 100644 index 0000000000..6297b817e8 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-18-deep-dive-9-workflows/workflows-openning.png differ diff --git a/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/Post.md b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/Post.md new file mode 100644 index 0000000000..2fd61ac23e --- /dev/null +++ b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/Post.md @@ -0,0 +1,645 @@ +Multi-tenancy sounds simple until the first real requirement lands: tenant-specific data isolation, host-only features, separate databases for a few big customers, and an admin panel that still feels like one product. + +ABP Framework gives you most of the plumbing out of the box, but the important part is knowing which pieces to enable, which defaults to trust, and where teams usually get into trouble. This article walks through a practical implementation approach for ABP Framework v8+ and the latest branch, covering shared database, separate database, and hybrid setups. + +## What ABP Multi-Tenancy Actually Gives You + +ABP's multi-tenancy support is not just a `TenantId` convention. It includes: + +- tenant context management +- automatic data filtering for multi-tenant entities +- tenant resolution from web requests +- host vs tenant side separation +- permission scoping by tenancy side +- tenant-aware connection string resolution +- tenant management infrastructure + +The first switch is explicit. + +```csharp +Configure(options => +{ + options.IsEnabled = true; +}); +``` + +Technically, multi-tenancy is disabled by default, although ABP startup templates usually enable it for you. + +ABP models two sides: + +- Host: the system owner, platform operator, or SaaS provider +- Tenant: the customer using the system + +A `TenantId` value of `null` typically means the data belongs to the host side. + +## Choose the Right Database Architecture First + +Before writing entities or resolvers, decide how tenant data will be stored. This choice affects migrations, operations, support cost, and sometimes your pricing model. + +### 1. Shared Database + +All tenants share the same database and tables. Isolation is enforced with `TenantId` and ABP's built-in data filters. + +Why teams choose it: + +- simplest deployment model +- lowest infrastructure cost +- easiest to operate in early-stage SaaS products +- one migration pipeline + +Trade-offs: + +- large tables grow quickly +- indexing becomes more important +- noisy-neighbor performance is more likely +- stricter discipline is required to avoid cross-tenant mistakes + +This is usually the best default unless you already know you need stronger isolation. + +### 2. Separate Database per Tenant + +Each tenant gets its own database. Host data is usually kept in a central database, while tenant-specific data goes to per-tenant databases. + +Why teams choose it: + +- stronger data isolation +- easier tenant-specific backup and restore +- cleaner compliance story +- large tenants can scale independently + +Trade-offs: + +- more provisioning logic +- more migration complexity +- more operational overhead +- onboarding a tenant is no longer just inserting a row + +### 3. Hybrid Model + +Some tenants use the shared database, while others get dedicated databases. + +This is often the most realistic long-term model: + +- small customers stay in shared infrastructure +- enterprise customers get isolated databases +- you can promote selected tenants later + +Trade-offs: + +- highest implementation and operational complexity +- migrations and seeding need stronger discipline +- debugging environment-specific issues becomes harder + + + +![Generated illustration](inline-1.png) + +## Implement Tenant-Aware Entities Correctly + +In ABP, tenant-scoped entities implement `IMultiTenant`. + +```csharp +using Volo.Abp.Domain.Entities; +using Volo.Abp.MultiTenancy; + +public class Product : AggregateRoot, IMultiTenant +{ + public Guid? TenantId { get; set; } + public string Name { get; private set; } + public decimal Price { get; private set; } + + private Product() + { + } + + public Product(Guid id, string name, decimal price, Guid? tenantId) + : base(id) + { + TenantId = tenantId; + Name = name; + Price = price; + } +} +``` + +Once an entity implements `IMultiTenant`, ABP automatically filters queries according to the current tenant. + +That means this kind of repository call is already tenant-aware in normal application flow: + +```csharp +var products = await _productRepository.GetListAsync(); +``` + +### The nullable `TenantId` detail matters + +`TenantId` is nullable by design because host-owned data is valid in ABP. + +That is useful, but also easy to misuse. + +If an entity is truly tenant-only, do not casually allow `TenantId = null`. Enforce the rule in your constructor, factory method, or domain service. + +Example: + +```csharp +public Order(Guid id, Guid tenantId, string orderNo) : base(id) +{ + TenantId = tenantId; + OrderNo = orderNo; +} + +public Guid? TenantId { get; private set; } +public string OrderNo { get; private set; } +``` + +For tenant-only aggregates, this small constraint prevents a surprising number of data leakage bugs. + +## Use `ICurrentTenant` for Context-Aware Logic + +`ICurrentTenant` is the central service for reading or temporarily changing tenant context. + +```csharp +public class ProductAppService : ApplicationService +{ + public async Task GetTenantInfoAsync() + { + if (CurrentTenant.IsAvailable) + { + return $"TenantId: {CurrentTenant.Id}, Name: {CurrentTenant.Name}"; + } + + return "Host context"; + } +} +``` + +The more interesting capability is context switching. + +```csharp +using (_currentTenant.Change(tenantId)) +{ + var count = await _productRepository.GetCountAsync(); +} +``` + +This is useful for: + +- background jobs that process one tenant at a time +- host-side reporting across tenants +- tenant seeding during onboarding +- maintenance tasks and migrations + +### A practical warning + +Switching tenant context is powerful. It is also a common source of subtle bugs when developers mix host and tenant operations in the same method. Keep tenant context scopes short and obvious. + +## How Tenant Resolution Works in ABP + +ABP determines the active tenant through a chain of tenant resolvers. Out of the box, the default contributors are checked in this order: + +1. Current user claims +2. Query string, using `__tenant` by default +3. Route value +4. Header +5. Cookie + +In practice, this means a request can become tenant-aware even before your application service runs. + +### Default key configuration + +If you want to change the default `__tenant` key: + +```csharp +Configure(options => +{ + options.TenantKey = "tenant"; +}); +``` + +This is fine, but if you have a frontend client, especially Angular, the client must use the same tenant key. Otherwise the backend and frontend silently disagree about tenant resolution. + +### Domain and subdomain based resolution + +ABP also supports domain or subdomain-based tenant resolution. + +```csharp +Configure(options => +{ + options.AddDomainTenantResolver("{0}.myapp.com"); +}); +``` + +This is usually the cleanest user experience for SaaS applications because the tenant is implied by the hostname. + +Use it when: + +- each tenant has a branded subdomain +- the URL should define tenant context naturally +- you want fewer explicit tenant parameters in requests + +Be careful with: + +- reverse proxies and forwarded headers +- wildcard DNS and TLS certificates +- authentication server issuer validation in wildcard domain scenarios +- local development setup + +If you use OpenIddict or token validation with wildcard domains, make sure issuer validation is configured for that pattern. This is one of the most common production surprises in subdomain-based multi-tenant setups. + +### Fallback tenant + +ABP can also use a fallback tenant. + +That can be convenient in development or in a constrained deployment model, but it comes with an important trade-off: you effectively reduce or hide host context behavior. Use fallback tenants deliberately, not as a shortcut for resolver problems. + + + +![Generated illustration](inline-2.png) + +## Custom Tenant Resolvers for Real Projects + +Sooner or later, one tenant comes from a gateway header, another from a custom route pattern, and a third from a legacy integration. + +ABP allows custom tenant resolvers by implementing a contributor. + +```csharp +using System.Threading.Tasks; +using Volo.Abp.MultiTenancy; + +public class XTenantHeaderResolveContributor : TenantResolveContributorBase +{ + public const string HeaderName = "X-Tenant-Code"; + + public override string Name => "XTenantHeader"; + + public override Task ResolveAsync(ITenantResolveContext context) + { + var httpContext = context.GetHttpContext(); + var tenantCode = httpContext?.Request.Headers[HeaderName].ToString(); + + if (!tenantCode.IsNullOrWhiteSpace()) + { + context.Handled = true; + context.TenantIdOrName = tenantCode; + } + + return Task.CompletedTask; + } +} +``` + +Then register it in tenant resolve options. + +The main rule here is simple: prefer one primary strategy. A long resolver chain with multiple overlapping sources makes support harder. + +## Configure `DbContext` for Host and Tenant Sides + +When you move beyond a single shared database, `DbContext` design becomes a core architecture decision. + +ABP supports defining which side a context belongs to: + +- `Both` +- `Host` +- `Tenant` + +This matters when you want host-only tables to stay out of tenant databases, or when tenant databases should contain only selected modules. + +### Why this matters + +Suppose your host side includes tenant management, audit administration, and platform billing, but tenant databases should only include business tables and tenant-facing identity data. + +If you blindly configure every module in every context, your tenant databases will accumulate tables they should never have had. + +### Practical approach + +For a shared database setup, one `DbContext` with `Both` is often enough. + +For separate or hybrid databases, a common approach is: + +- one host/shared `DbContext` +- one tenant-only `DbContext` +- selective module configuration per context + +The important implementation detail is not just the side flag. It is also controlling which `builder.ConfigureXyz()` calls are applied in each context. + +For example, do not configure host-only modules in the tenant-only context. + +## Shared Database Setup: The Best Starting Point + +If you are implementing multi-tenancy for the first time in ABP, start with the shared database model unless you have a strong reason not to. + +A practical setup looks like this: + +1. Enable multi-tenancy +2. Make tenant-owned entities implement `IMultiTenant` +3. Use standard ABP repositories +4. Resolve tenant from user, subdomain, or request key +5. Keep host-owned data with `TenantId = null` +6. Define permissions with proper tenancy sides + +Example entity creation inside a tenant context: + +```csharp +public class ProductManager : DomainService +{ + public async Task CreateAsync(string name, decimal price) + { + var product = new Product( + GuidGenerator.Create(), + name, + price, + CurrentTenant.Id + ); + + return await _productRepository.InsertAsync(product); + } +} +``` + +This works well because ABP naturally fills the application flow with tenant context. + +### Performance tips for shared database mode + +As tenant count grows: + +- index `TenantId` on large tables +- include `TenantId` in common query patterns +- monitor large shared tables early +- be careful with cross-tenant reporting queries +- verify all custom SQL is tenant-aware + +ABP helps with filtering, but it does not replace database design. + +## Separate Database per Tenant in ABP + +This is where ABP becomes especially useful, because it can resolve the active tenant and then use tenant-specific connection strings. + +The Tenant Management module stores tenant metadata, including optional connection strings. + +At a high level, the flow is: + +1. Resolve the current tenant +2. Load tenant configuration +3. Determine the right connection string +4. Build the `DbContext` against the host or tenant database +5. Apply data filters inside that database scope as needed + +### What is available out of the box + +ABP supports the architecture and connection-string-based separation. + +Version-wise, the latest ABP docs reflect improved support in open source for separate database per tenant. However, managing tenant connection strings from the UI remains tied to SaaS/PRO features. In open source, teams often provide this through custom admin screens, configuration management, or provisioning services. + +### What changes operationally + +With per-tenant databases, you now need a plan for: + +- database creation during tenant onboarding +- migrations for new and existing tenant databases +- tenant-specific seeding +- backups and restore procedures +- monitoring failed or drifted tenant databases + +This is the real cost of stronger isolation. + + + +![Generated illustration](inline-3.png) + +## Hybrid Multi-Tenancy: Shared by Default, Dedicated When Needed + +Hybrid architecture is often the most business-friendly model. + +A common pattern looks like this: + +- default all new tenants to shared database +- move larger or regulated tenants to dedicated databases +- keep host/platform data in a central database + +This lets you defer infrastructure cost until a tenant actually needs isolation. + +The challenge is not whether ABP supports it. It does. The challenge is operational consistency: + +- how a tenant is promoted from shared to dedicated +- how data is moved safely +- how migrations stay aligned across both models +- how support engineers know which storage model a tenant uses + +If you choose hybrid, document the lifecycle, not just the code. + +## Tenant Management, Onboarding, and Connection Strings + +ABP's Tenant Management module is the starting point for tenant administration. + +It gives you tenant records and a standard place to store metadata. In more advanced solutions, that metadata is often extended with: + +- edition or plan +- onboarding status +- provisioning result +- custom domains +- support tier +- infrastructure notes + +For separate database scenarios, onboarding usually means more than creating a tenant row. It often includes: + +1. create tenant record +2. assign connection string if needed +3. create database or schema +4. run migrations +5. seed tenant data +6. create admin user +7. confirm domain or resolver setup + +Treat onboarding as a workflow, not a controller action. + +## Permissions and Authorization in a Multi-Tenant App + +ABP permissions can be scoped with `MultiTenancySides`. + +That is important because host users and tenant users often should not even see the same capabilities. + +Example definition: + +```csharp +context.AddGroup(MyPermissions.GroupName) + .AddPermission( + MyPermissions.HostDashboard, + multiTenancySide: MultiTenancySides.Host + ) + .AddPermission( + MyPermissions.TenantDashboard, + multiTenancySide: MultiTenancySides.Tenant + ); +``` + +This is one of the easiest wins in ABP multi-tenancy. Use it early. + +### Why it matters in practice + +Without side-aware permission definitions: + +- host-only menus can appear in tenant UI +- tenant-only features can leak into host administration +- tests become confusing because behavior differs by login context + +Also remember that usernames can collide across tenants. That is normal in multi-tenant identity models. What matters is the combination of user identity and tenant context. + +## Migrations and Data Seeding Without Regret + +Multi-tenant EF Core migrations are straightforward in theory and messy in real systems if you skip the design phase. + +### Shared database + +This is simplest: + +- one database +- one main migration flow +- host and tenant data usually seeded into the same database with different contexts or `TenantId` semantics + +### Separate or hybrid databases + +Now you need to answer: + +- which context owns which schema +- which migration runs against host DB +- which migration runs against tenant DBs +- when new tenants receive schema updates +- how failed migrations are retried + +### Seeding strategy + +A practical model is: + +- seed host-level data in the host database +- seed tenant defaults when a tenant is created +- perform tenant seeding inside `CurrentTenant.Change(tenantId)` scopes where appropriate + +Example: + +```csharp +using (_currentTenant.Change(tenantId)) +{ + await _dataSeeder.SeedAsync(new DataSeedContext(tenantId)); +} +``` + +That keeps seeding logic tenant-aware and consistent with the rest of the application. + +## Common Pitfalls That Break Multi-Tenancy + +Most ABP multi-tenancy bugs are not framework bugs. They are design mistakes. + +### 1. Tenant-only entity accidentally allows host ownership + +If `TenantId` stays nullable for a strictly tenant-owned entity, host-side records can slip in. That often leads to confusing query behavior and data mixing. + +### 2. Custom SQL bypasses tenant filtering + +ABP filters repository and LINQ queries for `IMultiTenant` entities. Your raw SQL does not magically become safe. Always include tenant scope explicitly when writing custom SQL. + +### 3. Host-only modules end up in tenant databases + +This usually happens when all module mappings are copied into every `DbContext`. Be intentional about which modules are configured where. + +### 4. Resolver strategy is inconsistent + +For example: + +- frontend sends `tenant` +- backend expects `__tenant` +- API gateway injects a header +- auth claims still refer to a different tenant source + +You can spend hours debugging what is really just inconsistent tenant resolution. + +### 5. Subdomain authentication is not fully configured + +Wildcard domains, issuer validation, proxy headers, and cookie domains all need a coherent setup. Subdomain multi-tenancy is elegant, but only after it is fully wired. + +### 6. Shared database performance is ignored too long + +If every large table relies on `TenantId` filters, indexing and query shape matter. This usually becomes painful gradually, then suddenly. + +## When to Use Shared, Separate, or Hybrid + +### Use shared database when + +- you are building a standard SaaS product +- operational simplicity matters most +- tenants are relatively small +- strict physical isolation is not required +- you want the fastest path to production + +### Use separate databases when + +- customers require stronger isolation +- you need tenant-level backup and restore +- data volume varies significantly between tenants +- some tenants need independent scaling or maintenance windows +- compliance requirements push you there + +### Use hybrid when + +- most tenants fit shared infrastructure +- a few enterprise tenants need dedicated storage +- you want to defer cost while preserving an upgrade path +- your team can handle extra migration and operational complexity + +### When NOT to over-engineer it + +Do not start with hybrid just because it sounds flexible. + +If you are early-stage and do not yet have hard isolation requirements, shared database with good tenant discipline is usually the better engineering decision. + +## A Practical Implementation Plan + +If you want a sane rollout path, use this order: + +### Phase 1: Enable and model multi-tenancy + +- enable `AbpMultiTenancyOptions` +- implement `IMultiTenant` on tenant-owned entities +- review aggregate rules around nullable `TenantId` +- define host vs tenant permissions correctly + +### Phase 2: Pick one tenant resolution strategy + +- prefer subdomain or authenticated user claim for web apps +- keep request key resolution for APIs or development +- make frontend and backend tenant key configuration consistent + +### Phase 3: Start with shared database + +- launch with shared DB unless requirements force separation +- add indexes and monitoring early +- verify custom queries are tenant-safe + +### Phase 4: Prepare for separation only where needed + +- isolate `DbContext` boundaries cleanly +- separate host-only module configuration from tenant-only configuration +- design onboarding and migration workflows +- add support for per-tenant connection strings when the business actually needs it + +This path keeps your first release simple without blocking future isolation models. + +## Final Thoughts + +ABP Framework removes a lot of the repetitive work in multi-tenant .NET applications, but it does not remove architectural choices. You still need to decide how tenants are resolved, where data lives, which modules belong to which side, and how strict your isolation really needs to be. + +The best ABP multi-tenancy setups are usually boring in the right places: + +- one clear tenant resolution strategy +- strict entity rules +- explicit host vs tenant boundaries +- a simple default database model +- operational workflows designed before enterprise tenants arrive + +That is what keeps a multi-tenant system maintainable after the demo phase. + +## TL;DR + +- Enable ABP multi-tenancy explicitly, then model tenant-owned entities with `IMultiTenant` and disciplined `TenantId` rules. +- Start with a shared database unless you already need stronger isolation, compliance, or tenant-level scaling. +- Use `ICurrentTenant` and a clear tenant resolution strategy to keep application logic predictable. +- For separate or hybrid databases, control `DbContext` boundaries, module mappings, migrations, and onboarding workflows carefully. +- Define permissions with `MultiTenancySides` so host and tenant experiences stay clean and secure. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/cover.png b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/cover.png new file mode 100644 index 0000000000..b0e2b14a68 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-1.png b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-1.png new file mode 100644 index 0000000000..b0be708000 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-2.png b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-2.png new file mode 100644 index 0000000000..0483d13091 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-3.png b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-3.png new file mode 100644 index 0000000000..6e12a4f4d8 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-how-to-implement-multitenancy-with-abp-framework/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/Post.md b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/Post.md new file mode 100644 index 0000000000..be87f21390 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/Post.md @@ -0,0 +1,607 @@ +Background jobs are one of those features that look simple at first and become operationally important very quickly. Sending emails, generating reports, syncing with third-party APIs, cleaning expired data, and processing imports should not block your HTTP requests. + +ABP gives you a clean abstraction for background jobs, and Hangfire gives you a production-friendly execution engine with persistence, retries, queues, and a dashboard. The useful part is that you can keep your application code aligned with ABP’s abstractions while swapping in Hangfire as the actual runner. + +In this article, I’ll walk through how to implement background jobs with ABP and Hangfire, when to use each piece, and where teams usually get tripped up. + +## Why use Hangfire instead of ABP's default background job manager? + +ABP already has a built-in background job system, and it is perfectly fine for simple cases. But it helps to understand what you are trading. + +### ABP default job manager + +By default, ABP background jobs are: + +- Enqueued through `IBackgroundJobManager` +- Executed in-process +- FIFO-oriented +- Single-threaded by default +- Retried automatically with increasing delays +- Stored through ABP's background job store + +This is good when: + +- Your app is small or moderate in workload +- You want minimal setup +- You do not need a dashboard +- You do not need advanced queue management + +### Hangfire integration + +When you add `Volo.Abp.BackgroundJobs.HangFire`, ABP can keep the same `IBackgroundJobManager` programming model, but Hangfire becomes the execution backend. + +That gives you: + +- Durable job storage +- Better operational visibility through the Hangfire dashboard +- Multiple worker servers +- Queue-based processing +- Recurring jobs and scheduling features +- A mature retry and monitoring model + +In practice, Hangfire is the better choice when background processing is part of the actual system design, not just a convenience. + +### Quick comparison + +Use ABP default when: + +- You want the simplest possible setup +- Background jobs are low volume +- A single app instance is enough +- You do not need a dashboard or queue controls + +Use Hangfire when: + +- You need reliability across restarts +- You run multiple instances +- You need recurring jobs or queue isolation +- You want to inspect failures and retries visually +- Background processing is operationally important + + + +![Generated illustration](inline-1.png) + +## Defining a background job in ABP + +The nice part of ABP is that your job code does not need to know about Hangfire. + +Start with a job arguments class: + +```csharp +public class EmailSendingArgs +{ + public string To { get; set; } = string.Empty; + public string Subject { get; set; } = string.Empty; + public string Body { get; set; } = string.Empty; +} +``` + +Then create the job itself: + +```csharp +using System.Threading.Tasks; +using Volo.Abp.BackgroundJobs; +using Volo.Abp.DependencyInjection; + +public class EmailSendingJob : AsyncBackgroundJob, ITransientDependency +{ + private readonly IEmailSender _emailSender; + + public EmailSendingJob(IEmailSender emailSender) + { + _emailSender = emailSender; + } + + public override async Task ExecuteAsync(EmailSendingArgs args) + { + await _emailSender.SendAsync( + args.To, + args.Subject, + args.Body + ); + } +} +``` + +This job works with ABP’s job abstraction regardless of whether the runtime backend is the default implementation or Hangfire. + +To enqueue it: + +```csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.BackgroundJobs; + +public class NotificationAppService : ApplicationService +{ + private readonly IBackgroundJobManager _backgroundJobManager; + + public NotificationAppService(IBackgroundJobManager backgroundJobManager) + { + _backgroundJobManager = backgroundJobManager; + } + + public async Task QueueWelcomeEmailAsync(string email) + { + await _backgroundJobManager.EnqueueAsync( + new EmailSendingArgs + { + To = email, + Subject = "Welcome", + Body = "Your account is ready." + }, + priority: BackgroundJobPriority.Normal, + delay: TimeSpan.FromMinutes(1) + ); + } +} +``` + +A few practical notes: + +- `delay` is useful for short deferrals and back-office workflows. +- `priority` is part of ABP’s abstraction. How it maps operationally depends on the provider. +- Keep argument objects small and serializable. +- Do not pass EF entities or large object graphs into jobs. + +## Setting up Hangfire in an ABP application + +To integrate Hangfire, install the package and wire it into your ABP module. + +### 1. Add the package + +Using ABP CLI: + +```bash +abp add-package Volo.Abp.BackgroundJobs.HangFire +``` + +Or with NuGet: + +```bash +Install-Package Volo.Abp.BackgroundJobs.HangFire +``` + +### 2. Add the module dependency + +Typically this goes into your host module, such as `HttpApiHostModule`: + +```csharp +using Volo.Abp.BackgroundJobs.Hangfire; + +[DependsOn( + typeof(AbpBackgroundJobsHangfireModule) +)] +public class MyProjectHttpApiHostModule : AbpModule +{ +} +``` + +### 3. Configure Hangfire services + +In `ConfigureServices`: + +```csharp +using Hangfire; +using Microsoft.Extensions.Configuration; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + var configuration = context.Services.GetConfiguration(); + + context.Services.AddHangfire(config => + { + config.UseSqlServerStorage( + configuration.GetConnectionString("Default") + ); + }); +} +``` + +If you use PostgreSQL, Redis, or another Hangfire storage provider, configure that instead. The storage decision matters because all servers that process jobs must share the same backing store. + +### 4. Enable the Hangfire dashboard + +In `OnApplicationInitialization`: + +```csharp +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; + +public override void OnApplicationInitialization(ApplicationInitializationContext context) +{ + var app = context.GetApplicationBuilder(); + + app.UseAuthentication(); + app.UseAuthorization(); + + app.UseAbpHangfireDashboard(); +} +``` + +The dashboard middleware should be added after authentication and authorization middleware. + +At this point, jobs enqueued through `IBackgroundJobManager` should use Hangfire as long as the integration is correctly activated. + + + +![Generated illustration](inline-2.png) + +## End-to-end example: offloading a report export + +A common use case is exporting a report that may take several seconds or minutes. + +Instead of generating the file during the HTTP request: + +- Save an export request record +- Enqueue a background job +- Let the job generate the file +- Notify the user when it is ready + +### Arguments + +```csharp +public class ReportExportJobArgs +{ + public Guid ExportRequestId { get; set; } + public Guid UserId { get; set; } +} +``` + +### Job implementation + +```csharp +using System.Threading.Tasks; +using Volo.Abp.BackgroundJobs; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Uow; + +public class ReportExportJob : AsyncBackgroundJob, ITransientDependency +{ + private readonly IReportExportAppService _reportExportAppService; + + public ReportExportJob(IReportExportAppService reportExportAppService) + { + _reportExportAppService = reportExportAppService; + } + + public override async Task ExecuteAsync(ReportExportJobArgs args) + { + await _reportExportAppService.GenerateAsync(args.ExportRequestId, args.UserId); + } +} +``` + +### Enqueue from app service + +```csharp +public async Task RequestExportAsync() +{ + var exportRequestId = GuidGenerator.Create(); + + await _backgroundJobManager.EnqueueAsync( + new ReportExportJobArgs + { + ExportRequestId = exportRequestId, + UserId = CurrentUser.GetId() + } + ); + + return exportRequestId; +} +``` + +This pattern scales much better than holding open a web request while doing CPU-heavy or IO-heavy work. + +## Retries, exceptions, and cancellation + +ABP and Hangfire both care about retries, but you should still design jobs carefully. + +### How ABP behaves + +With ABP background jobs: + +- Unhandled exceptions trigger retries +- Retry intervals increase over time +- Default implementation uses exponential backoff behavior +- Jobs may eventually time out or be marked abandoned depending on configuration + +### What this means for your code + +A job should be: + +- Idempotent whenever possible +- Safe to retry +- Explicit about transient vs permanent failures + +For example, sending the same payment capture twice is dangerous. Sending the same “your report is ready” notification twice is annoying but manageable. Design around the difference. + +### Cancellation handling + +If you use `ICancellationTokenProvider`, be deliberate. If cancellation means “try again later,” let the exception flow. If cancellation means “stop and do not retry,” return gracefully. + +Example: + +```csharp +using System.Threading; +using System.Threading.Tasks; +using Volo.Abp.BackgroundJobs; +using Volo.Abp.Threading; + +public class DataSyncJob : AsyncBackgroundJob +{ + private readonly ICancellationTokenProvider _cancellationTokenProvider; + + public DataSyncJob(ICancellationTokenProvider cancellationTokenProvider) + { + _cancellationTokenProvider = cancellationTokenProvider; + } + + public override async Task ExecuteAsync(int args) + { + var cancellationToken = _cancellationTokenProvider.Token; + + cancellationToken.ThrowIfCancellationRequested(); + + await Task.Delay(500, cancellationToken); + } +} +``` + +### Practical guidance + +- Keep jobs short and composable +- Persist progress if the job is large +- Use domain/application services inside jobs instead of putting business logic directly into the job class +- Log enough context to diagnose retries and failures + +## Recurring jobs and periodic work + +Not every background task is a one-time job. + +There are two different patterns: + +- Background jobs: one-off, delayed, or fire-and-forget work +- Background workers: periodic or recurring work + +In ABP, recurring processing is usually modeled with background workers rather than standard background jobs. + +### When to use a worker instead of a job + +Use a worker when you need: + +- A scheduled cleanup task +- A recurring sync with another system +- Polling behavior +- A cron-like schedule + +### Hangfire-backed recurring worker + +With Hangfire integration, you can derive from `HangfireBackgroundWorkerBase` and provide a cron expression. + +```csharp +using System.Threading.Tasks; +using Volo.Abp.BackgroundWorkers.Hangfire; + +public class ExpiredSessionsCleanupWorker : HangfireBackgroundWorkerBase +{ + private readonly ISessionCleanupService _sessionCleanupService; + + public ExpiredSessionsCleanupWorker(ISessionCleanupService sessionCleanupService) + { + _sessionCleanupService = sessionCleanupService; + + RecurringJobId = "expired-sessions-cleanup"; + CronExpression = "0 * * * *"; + } + + public override async Task DoWorkAsync() + { + await _sessionCleanupService.CleanupAsync(); + } +} +``` + +A few details matter here: + +- `RecurringJobId` should be stable and unique. +- `CronExpression` controls the schedule. +- Hangfire recurring scheduling is minute-based in normal use, so do not expect second-level precision. + +### Background jobs vs background workers + +A simple rule: + +- If a user action creates work to do later, use a background job. +- If the system itself needs to run something on a schedule, use a background worker. + + + +![Generated illustration](inline-3.png) + +## Queue isolation and scaling across multiple instances + +Once you run more than one application instance, background processing becomes an architecture concern rather than a coding detail. + +### Shared storage is required + +If multiple nodes are going to process Hangfire jobs, they must share the same Hangfire storage. + +Typical setups include: + +- Multiple web instances + one shared SQL Server storage +- Web instances enqueueing jobs + dedicated worker instances processing them +- Separate deployment slots or services sharing the same Hangfire backend + +### Disabling execution on some nodes + +Sometimes you want your web app to enqueue jobs but not execute them. + +ABP supports this: + +```csharp +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp.BackgroundJobs; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.IsJobExecutionEnabled = false; + }); +} +``` + +This is useful when: + +- You run dedicated worker processes +- You want predictable resource allocation +- You do not want front-end nodes competing for background work + +### Queue prefixing in clustered environments + +If multiple applications share the same Hangfire storage, isolate queues intentionally. + +For Hangfire integration in ABP, use `AbpHangfireOptions.DefaultQueuePrefix` to avoid queue collisions between different applications or environments. + +That matters more than teams expect. Without isolation, staging and production can end up looking at the same queues if storage is misconfigured. + +### Queue routing + +Hangfire supports multiple queues, and ABP’s Hangfire integration can route jobs based on conventions or attributes. + +In some scenarios, you may want specific jobs to go to specific queues, for example: + +- `emails` +- `exports` +- `integration` +- `critical` + +This is especially helpful when one queue can become noisy and starve more important work. + + + +![Generated illustration](inline-4.png) + +## Securing the Hangfire dashboard + +The Hangfire dashboard is extremely useful, but it is also an operations surface. Do not expose it casually. + +ABP provides authorization support for the dashboard via `AbpHangfireAuthorizationFilter`. + +A typical setup is to: + +- Require authentication +- Restrict by permission or role +- Optionally consider tenant-specific access rules + +Example: + +```csharp +app.UseAbpHangfireDashboard("/hangfire", new DashboardOptions +{ + Authorization = new[] + { + new AbpHangfireAuthorizationFilter(requiredPermissionName: "Administration.Hangfire") + } +}); +``` + +Even if your app is internal, treat the dashboard like an admin area: + +- Put it behind authorization +- Avoid exposing it publicly without network restrictions +- Audit who can retry or inspect jobs + +## Common pitfalls and behavior differences + +This is the part that usually saves the most time. + +### 1. Jobs still land in `AbpBackgroundJob` instead of Hangfire + +If Hangfire is not properly activated, ABP may continue using its native background job storage and you will see jobs in the `AbpBackgroundJob` table instead of Hangfire storage. + +Check these first: + +- The `Volo.Abp.BackgroundJobs.HangFire` package is installed +- `AbpBackgroundJobsHangfireModule` is added in `[DependsOn]` +- `AddHangfire(...)` is configured correctly +- The application starts with the expected module graph + +If any of those are missing, you may think you are using Hangfire while you are actually still on the default provider. + +### 2. Passing large or complex objects into jobs + +Keep job args small. Prefer identifiers over rich objects. + +Good: + +- `OrderId` +- `UserId` +- `ExportRequestId` + +Bad: + +- Full EF entities +- Large DTO graphs +- Objects with lazy-loading behavior or runtime-only state + +### 3. Non-idempotent job logic + +Retries will happen. If running the same job twice can corrupt data, redesign the workflow. + +Common fixes: + +- Add a processed flag +- Use unique constraints where appropriate +- Check prior execution status before applying side effects +- Make external calls with idempotency keys when supported + +### 4. Assuming recurring jobs run with exact timing + +Hangfire recurring jobs are cron-based and typically evaluated on minute boundaries. That is fine for most scheduled business work, but it is not a real-time scheduler. + +### 5. Ignoring queue isolation in multi-app environments + +If several apps share one Hangfire store, queue naming and prefixing must be explicit. Otherwise, one application can accidentally process another application's jobs. + +## When to use / When NOT to use ABP + Hangfire + +### Use ABP + Hangfire when + +- You want ABP-friendly job abstractions with a stronger execution backend +- You need operational visibility and retry inspection +- You run multiple instances or worker nodes +- You have recurring background tasks +- Your jobs are part of business-critical workflows + +### Do NOT use it when + +- The work must complete synchronously before responding to the user +- The task is so trivial that plain in-memory processing is enough +- You need event streaming rather than job scheduling +- You need ultra-low-latency real-time processing with very tight timing guarantees + +For many line-of-business systems, ABP + Hangfire hits a very practical middle ground: easy enough to implement, strong enough to operate. + +## A production-minded implementation checklist + +Before shipping, verify these points: + +- Jobs are enqueued through `IBackgroundJobManager` unless you explicitly need Hangfire-specific APIs +- Job arguments are small and serializable +- Job logic is retry-safe and preferably idempotent +- Hangfire storage is shared by all processing nodes +- Dashboard access is restricted +- Queue names or prefixes are isolated per app/environment +- Long-running jobs are split into manageable steps where possible +- You know which nodes execute jobs and which only enqueue them + +## TL;DR + +- ABP gives you a clean background job abstraction; Hangfire gives you the production-grade execution engine. +- Keep using `IBackgroundJobManager` for most jobs so your application code stays provider-independent. +- Use background jobs for one-off work and Hangfire-backed background workers for recurring tasks. +- In multi-instance deployments, shared storage, queue isolation, and dashboard security are not optional. +- If jobs still go to `AbpBackgroundJob`, your Hangfire integration is probably not fully activated. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/cover.png b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/cover.png new file mode 100644 index 0000000000..933dd3399c Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-1.png b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-1.png new file mode 100644 index 0000000000..62cec256e6 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-2.png b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-2.png new file mode 100644 index 0000000000..1d04df4a76 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-3.png b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-3.png new file mode 100644 index 0000000000..a22d1c5d24 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-4.png b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-4.png new file mode 100644 index 0000000000..04444db117 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-22-implementing-background-jobs-with-abp-and-hangfire/inline-4.png differ diff --git a/docs/en/Community-Articles/2026-06-23-deep-dive-index/Post.md b/docs/en/Community-Articles/2026-06-23-deep-dive-index/Post.md new file mode 100644 index 0000000000..b3672e120c --- /dev/null +++ b/docs/en/Community-Articles/2026-06-23-deep-dive-index/Post.md @@ -0,0 +1,41 @@ +# Deep Dive on ABP AI Agent: The Complete Series + +ABP Studio is a development platform built around ABP Framework. With the introduction of **ABP AI Coding Agent**, it became something more: a platform where an AI agent works inside the same environment you already use to build, run, monitor, and ship ABP solutions. + +![ABP Studio with ABP AI Agent](abp-studio-new-design.png) + +General-purpose AI coding tools are excellent for horizontal, file-shaped work. They read source files, edit them, and run shell commands. But ABP solutions are **system-shaped**, not just file-shaped. A typical ABP solution is split across multiple modules and layers with strict dependency rules, composed of many runnable units (HTTP services, gateways, identity servers, background workers, Docker containers), and built on a strong set of conventions: aggregate roots, repositories, application services, DTOs, permissions, localization, event bus, distributed cache, and background jobs. + +A generic agent has none of that vocabulary. It does not know what a module is, which project is the Domain layer, or that an `ApplicationService` should not depend on a `DbContext` directly. It cannot start your microservices, gateway, and auth server together. It cannot tell you that the latest edit caused a runtime exception in the Identity service, because it has no concept of a running application. + +ABP AI Coding Agent was built to close exactly that gap. The agent is born inside a platform that already understands modules, run profiles, builds, migrations, proxies, Docker containers, monitoring, and Git workflows, and it uses every one of them. + +We wrote a **nine-part deep dive series** to explain how each part of this system works, not as a product tour, but as a practical look at the decisions, controls, and architecture behind the experience. + +## The Series + +1. **[Agent, Plan and Ask Modes](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-1-agent-plan-and-ask-modes-62wteg9t)** — The three interaction modes that control how much action the agent is allowed to take: **Ask** for understanding (read-only), **Plan** for designing the approach before editing, and **Agent** for full implementation with builds, tools, and iteration. + +2. **[Supported AI Models + Usage Recommendations](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-2-supported-ai-models-in-abp-3krbc7yc)** — How ABP Studio separates models by role (main, research, browser, text processor, Git review) and why treating model selection as a practical decision based on the task leads to a better balance of capability, speed, and cost. + +3. **[Rules, Skills and Lessons](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-3-rules-skills-and-lessons-ai6kxubt)** — The three mechanisms that give the agent solution-specific memory: **Rules** (always-on conventions), **Skills** (on-demand procedures), and **Lessons** (corrections the agent records and carries forward). + +4. **[Integrated ABP Studio Tools](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-4-integrated-abp-studio-tools-be2xa2om)** — The tools that connect the agent to ABP Studio's runtime environment: monitoring (exceptions, logs, requests), applications, containers, tasks, and build actions, with a practical walkthrough showing the difference between debugging with and without tool access. + +5. **[MCP (Model Context Protocol)](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-5-mcp-model-context-protocol-trb9o4ev)** — How MCP extends the agent beyond the solution boundary to reach external systems like Prometheus, SEO analyzers, or documentation services, with per-tool enable/disable controls and stdio/HTTP server support. + +6. **[ABP Studio Git Integration](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-6-abp-studio-git-integration-09tr41ec)** — The full Git loop inside ABP Studio: branching, diffing, AI-generated commit messages, AI code review on staged changes, GitHub issue context for starting tasks, and pull request feedback for addressing reviewer comments. + +7. **[Scopes](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-7-scopes-tfqtkdzu)** — How AI Scopes restrict the agent's working area to specific modules, packages, or solution areas, reducing unrelated exploration, preventing accidental edits, and making diffs easier to review. + +8. **[Parallel Agent Execution](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-8-parallel-agent-execution-1o0cik6g)** — Running multiple agent sessions at the same time, each with its own mode, model, scope, and workflow, plus read-only research subagents that fan out inside a single session. + +9. **[Workflows](https://abp.io/community/articles/deep-dive-on-abp-ai-agent-9-workflows-7jo1adb1)** — Repeatable before/after steps that wrap agent runs: start containers, build packages, add migrations, generate proxies, restart applications, and run validation tasks, so the agent focuses on the code change while the platform handles the deterministic parts. + +## The Bigger Picture + +Each article focuses on one feature, but the real value comes from how they work together. + +Modes decide how much action the agent takes. Models decide which brain handles the work. Rules, Skills, and Lessons shape what the agent knows. Tools and MCP extend what it can reach. Scopes define where it can work. Workflows define what happens around the work. Git Integration makes the result reviewable and recoverable. Parallel Execution lets multiple tasks move forward at the same time. + +That is the ABP AI Coding Agent experience: **not a single AI button, but a set of controls built into a platform that already understands how ABP solutions are developed, run, and maintained.** diff --git a/docs/en/Community-Articles/2026-06-23-deep-dive-index/abp-studio-new-design.png b/docs/en/Community-Articles/2026-06-23-deep-dive-index/abp-studio-new-design.png new file mode 100644 index 0000000000..d74add4b2d Binary files /dev/null and b/docs/en/Community-Articles/2026-06-23-deep-dive-index/abp-studio-new-design.png differ diff --git a/docs/en/Community-Articles/2026-06-23-deep-dive-index/cover.png b/docs/en/Community-Articles/2026-06-23-deep-dive-index/cover.png new file mode 100644 index 0000000000..9d0d5f5987 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-23-deep-dive-index/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-24-Meet-ABP-at-WeAreDevelopers-World-Congress-2026/post.md b/docs/en/Community-Articles/2026-06-24-Meet-ABP-at-WeAreDevelopers-World-Congress-2026/post.md new file mode 100644 index 0000000000..cd816964d0 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-24-Meet-ABP-at-WeAreDevelopers-World-Congress-2026/post.md @@ -0,0 +1,22 @@ +We are happy to announce that the ABP team will be heading to Berlin for WeAreDevelopers World Congress 2026, one of the largest gatherings of software developers and technology professionals in Europe. + +Taking place from **8-10 July 2026**, the event brings together thousands of developers, architects, engineering leaders, startups, and technology companies to explore the latest trends, tools, and ideas shaping the future of software development. + +We're excited to be part of this global community once again and look forward to connecting with developers from around the world. + +## **Visit Us at the Event\!** + +If you're attending WeAreDevelopers World Congress, make sure to stop by **Hall A, Booth A-41** and meet the ABP team. + +We'll be showcasing the latest developments across the ABP ecosystem, including ABP Framework, ABP Studio, and our newest AI-powered development capabilities. Whether you're building enterprise applications, modernizing existing systems, or exploring new approaches to software development, we'd love to hear about your projects and challenges. + +Our team will be available throughout the event for product demos, technical discussions, and conversations about modern .NET development, modular architecture, microservices, and AI-assisted software development. + +## **See You in Berlin** + +Nothing replaces meeting developers face-to-face\! + +Whether you're already using ABP, evaluating it for a future project, or simply curious about what we're building, we'd be happy to meet you. + +See you in **Hall A, Booth A-41** at WeAreDevelopers World Congress 2026\! + diff --git a/docs/en/Community-Articles/2026-06-25-ABP-Bootcamp-AI-Assisted-Application-Development-with-ABP/post.md b/docs/en/Community-Articles/2026-06-25-ABP-Bootcamp-AI-Assisted-Application-Development-with-ABP/post.md new file mode 100644 index 0000000000..912ab75d30 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-25-ABP-Bootcamp-AI-Assisted-Application-Development-with-ABP/post.md @@ -0,0 +1,86 @@ +AI is changing how software is built. Today, developers can generate features, services, tests, and even entire applications in minutes. Tasks that once took hours can now be completed with a single prompt. + +But speed is no longer the biggest challenge.Reliability is. + +AI generates probabilistic answers. Production software requires deterministic behavior. When developers receive different implementations for the same problem, applications become harder to maintain, harder to scale, and more difficult to evolve over time. + +Building software with AI is a lot like constructing a building with power tools.The tools make construction faster. They do not make poor foundations safer. + +In fact, they allow mistakes to spread much faster. + +The architectural decisions made during the first few months of a project often determine its long-term success. Security, modularity, authorization, maintainability, and development conventions become part of the foundation that everything else depends on. + +This is where ABP comes in. + +For more than a decade, we've been helping development teams build enterprise-grade .NET applications on solid architectural foundations. Today, companies around the world continue to build and maintain production systems with ABP, even as AI becomes an increasingly important part of the software development process. + +We didn't start thinking about AI yesterday. + +We've integrated AI into our own development workflows, evolved our startup templates, created AI-specific development rules, and built ABP Studio AI Agent to help developers work more effectively with ABP-based applications. + +To help developers learn these practices, we're excited to announce our latest bootcamp: + +## **AI-Assisted Application Development with ABP** + +This live, instructor-led bootcamp is not about generating code faster. + +It's about learning how to build applications faster while maintaining architectural consistency, code quality, and long-term maintainability. + +Over three days of hands-on sessions, you'll learn practical AI-assisted engineering workflows using ABP Studio AI Agent and discover how to combine AI productivity with proven software engineering practices. + +## **Bootcamp Details** + +**Dates:** August 25-27, 2026 +**Time:** 17:00-19:00 UTC each day +**Duration:** 6 hours total +**Format:** Live online sessions via Google Meet +**Price:** $399 (discounted from $799) + +*\*Participants who do not already have access to ABP Studio AI Agent will receive **complimentary trial access** **for the duration of the bootcamp**. Additional AI credits will be provided when needed.* + +## **What You'll Learn** + +Throughout the bootcamp, you'll explore real-world AI-assisted software development workflows, including: + +* Using AI to accelerate application development with ABP +* Working effectively with the ABP Studio AI Agent +* Generating features, services, and application components faster +* Understanding how AI can assist with implementation, debugging, and code exploration +* Applying AI-assisted engineering practices in real ABP projects +* Combining developer expertise with AI capabilities to improve productivity + +The focus will be on practical examples, live demonstrations, and hands-on exercises that you can immediately apply in your own projects. + +## **Why Learn From the ABP Team?** + +Many AI development courses teach how to generate code. + +This bootcamp focuses on something more important: how to generate code that remains maintainable, scalable, and consistent as your application grows. + +The ABP team has spent more than 10 years building and evolving one of the most widely used application frameworks in the .NET ecosystem. + +We've worked closely with development teams across industries, helped companies build production systems, and recently invested heavily in AI-powered development tools such as ABP Studio AI Agent. + +The lessons shared in this bootcamp come directly from our own experience building software with AI, not from theoretical examples or isolated experiments. + +You'll learn the same principles, workflows, and practices we use to combine AI-assisted development with real-world software engineering. + +## **Who It's For** + +This bootcamp is ideal for: + +* ABP developers who want to increase productivity with AI +* Software developers interested in AI-assisted software development +* Teams exploring how AI can improve their development workflows +* Technical leaders evaluating AI-powered development practices +* Anyone looking to stay ahead as software engineering continues to evolve + +## **Reserve Your Spot** + +AI-assisted software development is quickly becoming an essential skill for modern development teams. + +This bootcamp is designed to help you understand not only how AI tools work, but how to use them effectively within a real-world application development framework. + +Join us and learn how to build applications faster with ABP and AI. + +Registration is now open, fill the form: [https://docs.google.com/forms/d/e/1FAIpQLSdREtytTXXEfnOrwuMeTnXs7O10LcVXo-dlyhUNVTX\_dMZriw/viewform?usp=publish-editor](https://docs.google.com/forms/d/e/1FAIpQLSdREtytTXXEfnOrwuMeTnXs7O10LcVXo-dlyhUNVTX_dMZriw/viewform?usp=publish-editor) diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/Post.md b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/Post.md new file mode 100644 index 0000000000..4337be1c66 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/Post.md @@ -0,0 +1,226 @@ + + + + +# My Speaker's View of CONVEX Summit 2026 Madrid + +Hi, I'm here for another conference reviews. This time I attended [Convex Summit 2026 Developer](https://www.convexsummit.com/) conference, held in the capital city of Spain, Madrid. It was my first talk in Madrid. The organizer [Plain Concepts](https://www.plainconcepts.com/) arranged a 2 days conf with 3 parallel sessions. 2 of the sessions were in Spanish and one of them was English. The conf dates were 17, 18 June 2026. It was in a very big cinema. In Lithuania I also spoke in a cinema, I guess it's better to arrange a conf in a cinema because of asthenosphere, acoustic and state visibility for visitors. + +There is a small moment before every conference talk when the room becomes quiet, the slides are ready, and you suddenly remember why the topic matters. For me, that moment happened at Convex. My topic was “Turn any database into a conversational reporting engine.” I can admit it was a cool talk. But I was also there as a listener, a software architect, and someone trying to understand where enterprise AI is really going after the first wave of demos and experiments. CONVEX was interesting because it brought software development, architecture, and AI into the same conversation. These topics are often discussed separately, but in real companies they are tightly connected. AI features do not live in isolation. They live inside applications, databases, identity systems, permission models, workflows, dashboards, and business expectations. That was the real theme I felt throughout the event. + +## Speaking at CONVEX + +![My CONVEX 2026 speaker badge before the sessions started](images/IMG_20927.jpg) + +My talk focused on a question that is becoming more important for enterprise software teams: + +> What if users could ask their business data questions in natural language and receive safe, useful, validated answers? + +I started my slide with **Sobrino de Botin restaurant**. It's the oldest restaurant in the world according to the Guinness Book of World Records. Sobrino de Botín **has been open since 1725**. The taste never changed, the restaurant **is keeping the same classic taste with the same cooking techniques** but in the age of AI; we developers should **use new techniques for reporting**. We are not running a restaurant and this is how the development works. Adjust to the tech standards, new techniques and recent practices. + +![image-20260624200005106](images/the-oldest-restaurant-world.png) + +And in one part of my talk, I need to ask questions like “Show me the top customers by revenue this quarter.” So the LLM answers in my language. And I learnt some Spanish sentences before the conf. Even for this I used AI. So I translated 10 different English sentences to Spanish. Later I asked ChatGPT: "*Can you score my pronunciation for these sentences.*". ChatGPT gave the most ratings to 3 of my sentences' prouncations. And I talked those during my interview with my reporting AI tool. And that was fantastic eye-catching moment of my talk. + +![Some photos from my talk 1](images/my-pictures-1.jpg) + +*My session focused on building conversational reporting experiences without giving up control, validation, or security.* + +I asked the attendees how many of you have written SQL, created reporting screen, and %80 of people wrote SQL and created reporting UIs. And same amount of people also use .NET. + +![Some photos from my talk 2](images/my-pictures-1.jpg) + +> **AI can make data more accessible, but architecture must define the boundaries.** + +--- + +## What I Learned From the Other Sessions + +There was a track with completely English sessions. One of the reasons I enjoyed Convex was that the English sessions did not treat AI as magic. + +The strongest message I heard across different sessions was this: + +> **AI is becoming part of real systems and real systems have constraints.** + +And I can see, software development is rapidly evolving with AI agentic tools. + +> **We cannot say development is dead, but hand-made development is dead.** + +From now on we'll use our time less on typing and more on thinking about features, user experiences and robust infrastructure. + +**In the age of AI, writing code by hand is the software equivalent of sending a fax to prove commitment.** + +![hand-made-coding](images/hand-made-coding.png) + +For a while, many AI discussions were focused on what AI could generate: code, tests, text, SQL, documentation, designs. +At CONVEX, the more interesting question was: + +**What happens after AI generates something?** + +- Who validates it? +- Who owns the decision? +- Can we say I don't know to a question about how that works!? +- If something blows up or happens a data leakage, who is accountable for it? +- How does it fit into the architecture? +- How do we make it useful for the business instead of impressive for five minutes? + +### Architecture is also a people problem + +One session that stayed with me used the idea of the **Prisoner’s Dilemma** to describe the tension between product priorities and architectural work. The slide I captured showed a collaboration payoff matrix: when product management optimizes only for short-term business value, architecture can suffer; when architects focus only on architecture, market opportunity can be lost. The win-win scenario appears when both sides optimize for business value and architecture together. + +![A collaboration payoff matrix from an architecture session](images/IMG_20898.jpg) + +*The architecture sessions connected technical decisions with incentives, collaboration, and long-term system health.* + +Another slide suggested practical ways forward: learn the business, understand the competition, avoid “big bang” changes, work incrementally, create options, make trade-off decisions with the business and **become a business value creator** rather than someone who only responds to requests. + +I liked that message. Architecture is much more valuable when it helps the business create options, not when it only explains why something is risky. + +--- + +### Power, knowledge and decision-making + +Another interesting thread was about power in organizations. One talk referenced **Power-With**, I found it useful because it shifts the conversation away from control and toward collaboration. The slides connected power with access to knowledge, authority, charisma and the way decisions move through an organization. + +![A session slide discussing Power-With and organizational dynamics](images/IMG_20914.jpg) + +*Some of the most interesting moments connected architecture with people, incentives, and organizational reality.* + +There are 2 powers: + +1. **Power-Over**: Conquer other people's mind, control, force and order for a work output. +2. **Power-With**: Co-operate with others, use everyone's power into a big power, move together for a work output. + +This may sound less technical than a database, a framework, or a deployment pipeline. But in practice, many technical decisions fail or succeed because of organizational dynamics. A clean architecture can still fail if teams are not aligned. + +> A promising AI feature can still fail if no one trusts the output. + +### So Let's Think What's Charisma at Work + +- **What's charisma actually?** Let me tell you my opinion; charisma is experience, wisdom, grace, listening more and speaking less, way of looking to life, trustability (reliability), being a role model and an inspiration to others. +- **Why charisma is important?** It makes your words to be listened by other people **naturally** (without any need of dictation). + +One slide quoted the idea that knowledge workers “think for a living.” Another referenced Peter Naur’s **Programming as Theory Building**, where program text and documentation are not always enough to carry the most important design ideas. That felt very relevant in the age of AI-generated code. If code becomes easier to produce, shared understanding becomes even more valuable. + +As a summary; AI can often understand the architecture from the code. What it usually can't know reliably is **why** + +- the architecture ended up that way; the design decisions +- trade-offs +- historical context +- assumptions that exist mostly in the team's shared understanding rather than in the code itself. + +--- + +### What AI Agents can do and cannot do?! + +One of the most thought-provoking slides at the conf explored the current boundaries of AI agents. Instead of asking whether AI will replace humans, it asked a more interesting question: **What can AI agents actually do today, what can't they do and which limitations might disappear over time?** + +The first column listed the things AI agents already do well. They can execute tasks reliably without getting tired, maintain context across long-running work, report progress, detect problems, follow established processes, generate alternatives, document their work, and scale by running thousands of instances simultaneously. In short, AI excels at **execution**. + +The second column focused on capabilities that are fundamentally human today. AI can perform the role of a manager, mentor, or teammate, but it cannot truly *be* one. It cannot be held accountable for its decisions, earn trust through years of shared experience, genuinely care about an outcome, feel the weight of failure, or belong to a team. It can disagree or refuse a request, but not from genuine conviction or personal values. These qualities come from human relationships, responsibility, and lived experience, not from generating the next token. + +The third column added an important nuance. It wasn't titled "Impossible," but rather "Cannot, but maybe will one day." Some capabilities are already beginning to emerge. Multi-agent systems can delegate work to other agents. Better memory and continuity may allow AI to build trust over time. Multimodal models are becoming better at reading context, and reinforcement learning is an early form of learning from mistakes. The point wasn't that these problems are solved, but that some of today's limitations may become tomorrow's capabilities. + +The overall message was refreshingly balanced. AI agents should not be viewed as human employees, nor should they be underestimated. They are exceptional at executing work at scale, but organizations are built on more than execution. Trust, accountability, judgment, conviction, and belonging remain deeply human qualities, for now. + + + +![A slide comparing what AI agents can and cannot do](images/IMG_20935.jpg) + +*The AI agent discussion was interesting because it did not only focus on automation; it also highlighted accountability, trust, judgment, and team dynamics.* + +That is a healthy way to talk about AI. Not “*AI will replace everything*,” and not “*AI is useless.*” + +> **The real question is where AI can help a team and where humans still need to own the decision.** + +### Better decisions need better records + +I also followed sessions about architecture principles and decision records. One slide explained principles as priorities, beliefs, guardrails and a way to connect requirements to architectural decisions. Another used a simple architectural decision example: **Data Store per Service**, where each service owns its data and other services access it through APIs or events instead of direct database queries. + +![A slide about architecture principles and decisions](images/IMG_20952.jpg) + +*Architecture principles were presented as guardrails that connect requirements, trade-offs, and decisions.* + +Let me first define what's ADR:.. An **ADR (Architecture Decision Record)** is a short document that explains **an important technical decision, why it was made, and what the consequences are**. See the [Microsoft Document about ADR](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record). + +> **Code tells you *what* the system does. An ADR tells you *why* it was designed that way.** + +This connected nicely with another slide about ADRs. A minimal ADR, based on Michael Nygard’s format, includes a name, status, context, decision, and consequences. A more comprehensive ADR can also include related requirements, assumptions, constraints, options, reasoning and trade-offs. + +![A slide explaining the minimal ADR structure](images/IMG_20960.jpg) + +*The ADR discussions were a reminder that good architecture is not only about making decisions, but also about preserving the reasoning behind them.* + +For .NET teams, these ideas are practical. AI can sit on top of strong foundations around backend services, identity, data access, cloud integration, and enterprise applications, but it should not bypass them. + +If anything, AI makes good engineering discipline more important. + +## The Conference Experience + +The venue, Kinépolis Ciudad de la Imagen in Madrid, gave the conference a different feeling from a typical hotel-based event. The rooms, stage, and screens made the sessions feel cinematic. Outside the session rooms, the networking areas were active throughout the day. People were not only exchanging LinkedIn profiles; they were continuing the technical debates from the talks. + +![Participants networking at CONVEX Summit 2026](images/convex-ambiance.jpg) + +*The networking areas were busy between sessions, creating space for conversations beyond the formal agenda.* + +I met people from my country as well from Bosch and Aselsan companies...For me, the most valuable conversations happened after the talk. I made new friends and learn what other people do. + +## My Key Takeaways + +1. **AI features need data boundaries.** The more natural the interface becomes, the more important permissions, context, and allowed actions become. +2. **Natural language is becoming a product interface.** Users increasingly want answers, not get lost in the UI and not navigation paths. +3. **Architecture is becoming more important, not less.** AI can accelerate delivery, but it cannot remove product constraints, security requirements, or organizational complexity. + + > When calculator first invented they didn't think problem solving finished with this invention, people use more time to solve problems rather then calculating.... +4. **Decisions need memory.** Principles, ADRs, trade-offs and exceptions help teams preserve reasoning. +5. **Conferences still matter.** A hallway discussion after a session can sometimes teach you more than a full article or video. It's **a way of motivation**, a way of socializing for developers. You see what other do, you discuss with them, you know your customers and you know where you're at development. + + + +## My Cultural Visits + +I visited Toledo and Madrid's most important tourist attractions and museums. Now I know way much better then I knew before about Spanish culture and lifestyle. But this is the most impressive moment for me. As you may know I'm Turkish. My grand grandfathers were Ottomans coming from Mongolia to Anatolia. In 1571 the Ottomans were in a war with Spain, Genoa, Malta and Italy. The battle was in the sea near Greece. It's called Sea Battle of Lepanto. In the below pictures, you can see the Ottoman's highest level sea commander's personal items. Wwe call him **Kaptan-ı Derya** -the captain of seas-. He died in this war. For those who wants to see it; it's in Royal Palace of Madrid and the items are in Royal Armoury department. + +If you're interested in this war, you can also read this part: + +### The Battle of Lepanto ⚔ + +The Ottoman army was invading Cyprus. Angered by this, European countries asked Spain, one of the strongest kingdoms of the period for help. To retake the island, a Holy Christian fleet was assembled under Spanish leadership. On 7 October 1571, the forces arrived at the Gulf of Patras in Greece for what would become known as the Battle of Lepanto. On one side was the Ottoman army, commanded by Ali Pasha (the Grand Admiral). On the opposing side were the major European powers: Spain, Venice, the Papacy, Genoa, the Knights of Malta, and Italy. It would become the last major naval battle fought with oared warships. The Ottomans lost the battle and Sokollu Mehmed Pasha (he's normally Serbian Turk and he's the most powerful manager after Sultan) said the following famous saying: “*You have cut off our beard, but we have cut off your arm. A beard grows back.*” More than 200 Ottoman ships were lost. Tens of thousands of soldiers were killed or captured. In the below photograph, you will see war trophies taken from Ali Pasha. In Spain, this battle would be called “*La Defensa de la Cristiandad*” means “*The Defense of Christianity*” and would be used for propaganda for years. These trophies were used as symbols. The first time I saw the exhibit in a museum, I stood in front of it for 15–20 minutes, simply looking at it. + +![royal-palace-0](images/royal-palace-0.jpg) + +![royal-palace-1](images/royal-palace-1.png) + +![royal-palace-2](images/royal-palace-2.png) + +### What's the thing with Cervantes and Ottomans? + +There may be one more little-known detail about the Battle of Lepanto. Miguel de Cervantes, the author of the famous novel Don Quixote, also took part in this battle. During the conflict, Cervantes served aboard the Spanish ship Marquesa. Despite suffering from a fever, he insisted on joining the battle. The Ottoman army wounded Cervantes in the chest and left arm. As a result, he lost much of the use of his left hand. For this reason, he became known as “*El manco de Lepanto*,” meaning “*the one-handed hero of Lepanto.*” + +![don-kisot](images/don-kisot.png) + +### Bullfighting 🦬 + +I met a real matador in Toledo, and after talking to him, my perspective on everything changed dramatically! + +From the outside, it looks like nothing more than a “brutal spectacle,” but apparently there is a surprisingly deep philosophy behind it. These were the most interesting things I took away from what the matador told me: + +- **Bulls don’t react to the color red:** They are actually color-blind. What triggers them is the movement of the cape, not its color. Red is purely for visual aesthetics. +- **The selected bull is a special, wild breed:** The animal has almost never seen a human before entering the arena. It sees the matador as an enemy and wants to destroy him. +- **The greatest honor is to survive:** If a bull shows exceptional nobility and courage, the audience waves white handkerchiefs to ask for its pardon. That bull never enters the arena again and spends the rest of its life like a king on a farm. +- **A dance with death:** Matadors do not see this as a sport, but as a way of confronting death. When making the most critical strike, the matador must also put his own life at risk, he cannot simply stab the bull from behind. He has to face the bull head-on, bravely. In that sense, there is a strange bond of respect between them. The bull is powerful, but the matador is intelligent. He cannot defeat it through strength, only through skill, timing, and agility. +- **It is a controversial subject**, but hearing it firsthand in its own context changed my perspective considerably. At a time when animal rights are more important than ever, this tradition still continues. And I have now learned that bullfighting has a much deeper philosophy behind it than I had realized. + +![bull-fight](images/bull-fight.jpg) + +## Closing + +I left Convex 2026 and Spain with new ideas, useful feedback, and a stronger belief that the next phase of enterprise AI will be less about impressive demos and more about trusted systems. + +For me, the most interesting AI features are not the ones that look magical. They are the ones that quietly solve a real problem, respect the architecture around them, and help users make better decisions. + +Thank you to the Convex organizers, the speakers, and everyone who joined my session or continued the conversation afterward. + +Madrid was a great place to talk about AI, .NET, architecture, and the future of enterprise software. I hope to see many of you again at the next event. + +--- diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20898.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20898.jpg new file mode 100644 index 0000000000..eb95029543 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20898.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20914.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20914.jpg new file mode 100644 index 0000000000..3603ee8037 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20914.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20927.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20927.jpg new file mode 100644 index 0000000000..039bcdf1e0 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20927.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20935.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20935.jpg new file mode 100644 index 0000000000..235118bfc7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20935.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20952.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20952.jpg new file mode 100644 index 0000000000..f34333e988 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20952.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20960.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20960.jpg new file mode 100644 index 0000000000..40d15268c9 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/IMG_20960.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/bull-fight.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/bull-fight.jpg new file mode 100644 index 0000000000..e96a721afd Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/bull-fight.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/convex-ambiance.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/convex-ambiance.jpg new file mode 100644 index 0000000000..854c25ef69 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/convex-ambiance.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/cover.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/cover.jpg new file mode 100644 index 0000000000..27917025b8 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/cover.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/don-kisot.png b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/don-kisot.png new file mode 100644 index 0000000000..803685e4fc Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/don-kisot.png differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/hand-made-coding.png b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/hand-made-coding.png new file mode 100644 index 0000000000..d71ea044cb Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/hand-made-coding.png differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/my-pictures-1.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/my-pictures-1.jpg new file mode 100644 index 0000000000..d3f9b43334 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/my-pictures-1.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/my-pictures-2.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/my-pictures-2.jpg new file mode 100644 index 0000000000..a7741b804c Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/my-pictures-2.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-0.jpg b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-0.jpg new file mode 100644 index 0000000000..bd12a45c6f Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-0.jpg differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-1.png b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-1.png new file mode 100644 index 0000000000..e559a5c5c4 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-1.png differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-2.png b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-2.png new file mode 100644 index 0000000000..4c291f0b84 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/royal-palace-2.png differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/the-oldest-restaurant-world.png b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/the-oldest-restaurant-world.png new file mode 100644 index 0000000000..66dd237590 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/images/the-oldest-restaurant-world.png differ diff --git a/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/volosoft-presentation.pptx b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/volosoft-presentation.pptx new file mode 100644 index 0000000000..8b25522e54 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-Convex-Summit-2026-Recap/volosoft-presentation.pptx differ diff --git a/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/Post.md b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/Post.md new file mode 100644 index 0000000000..a36eab93e8 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/Post.md @@ -0,0 +1,349 @@ +A lot of the current AI discussion in software development swings between two extremes: either AI will write everything, or it is just autocomplete with better marketing. + +Neither view is especially useful. + +What the evidence shows is more practical: AI coding tools can improve developer throughput on certain tasks, especially repetitive work, scaffolding, and first drafts. But they do not remove the need for developers. In many teams, they actually create a new category of work around review, verification, security, and long-term maintainability. + +That is the real story. AI is not replacing developers. It is changing what developers do, what teams optimize for, and where engineering judgment matters most. + +## The productivity gains are real, but they are not magic + +There is enough data now to move beyond hot takes. + +Across multiple studies and industry reports, AI coding assistants show measurable productivity gains, but those gains are usually modest rather than transformational: + +- A BlueOptima analysis across 30,000 developers in 18 enterprises reported an average productivity uplift of 5.4%, with the most active users seeing gains closer to 20%. +- An open source study found roughly a 6.5% project-level productivity increase after Copilot adoption. +- GitHub survey data from more than 2,000 developers showed strong perceived benefits: improved flow, less mental drain on repetitive tasks, and greater job satisfaction. +- A longitudinal study from a large public-sector engineering organization found that developers using Copilot were already highly active, and while they reported productivity improvements, commit-based metrics did not show a statistically significant post-adoption jump. + +That last point matters. + +Perceived productivity and actual output are not always the same thing. Developers may feel faster because they spend less time on boilerplate, search, or syntax recall. That feeling is valuable. Less friction often means better focus. But it does not automatically translate into dramatically more shipped business value. + +In other words, AI helps, but it does not suspend the usual constraints of software delivery: + +- unclear requirements still slow teams down +- poor architecture still creates drag +- bad testing practices still leak defects +- messy codebases are still messy codebases + +If your delivery bottleneck is typing, AI looks revolutionary. If your bottleneck is product ambiguity, compliance, integration complexity, or production risk, AI helps less than the marketing suggests. + +## What AI coding tools are actually good at + +The strongest use case for AI in development is not autonomous software engineering. It is acceleration of narrow, well-bounded tasks. + +AI coding assistants are usually good at: + +- generating boilerplate +- filling in repetitive CRUD patterns +- writing simple tests and test skeletons +- suggesting refactors +- producing documentation drafts +- translating between languages or frameworks +- helping developers recall APIs and syntax +- creating a first pass for routine utility code + +This is why many developers genuinely like these tools. They reduce low-value friction. + +A practical example: + +A developer building an ABP-based application might use AI to: + +- scaffold DTO mappings +- draft validation rules +- generate basic unit test cases +- create repository query examples +- summarize a service class before refactoring + +Those are useful accelerators. But the same tool is much less reliable when asked to decide: + +- whether a module boundary is correct +- how to model a permission system +- what tradeoff to make between consistency and performance +- how multi-tenancy affects data access rules +- which abstraction will still be maintainable a year later + +That is the dividing line. AI handles local code generation better than system-level reasoning. + + + +![Generated illustration](inline-1.png) + +## Where developers are still irreplaceable + +The most valuable parts of software development were never just typing code. + +Developers are still responsible for the parts AI consistently struggles with: + +### Understanding the problem behind the ticket + +Business requirements are often incomplete, contradictory, or politically constrained. A human developer can ask the uncomfortable question, spot hidden assumptions, and translate vague intent into a workable implementation. + +AI can generate an answer. It cannot reliably challenge the question. + +### Making architecture tradeoffs + +Real systems involve tradeoffs, not ideal answers. + +Should this feature live in an existing module or a new service? Is eventual consistency acceptable here? Are we optimizing for onboarding speed, runtime performance, auditability, or cost control? + +These decisions depend on context that usually lives outside the prompt window. + +### Working safely in large, imperfect codebases + +Most production systems are not greenfield demos. They include legacy code, weird integrations, undocumented conventions, and historical constraints. + +This is where experienced developers earn their keep. They know that the technically correct change is not always the operationally safe change. + +### Taking responsibility for outcomes + +An AI assistant does not get paged at 2 a.m. It does not own the incident review. It does not explain a data leak to legal, security, or customers. + +Software engineering is not just generation. It is accountability. + +## The hidden cost: verification debt + +One of the most important ideas in the current AI coding debate is verification debt. + +AI can generate code quickly, but that speed often shifts effort downstream. Instead of spending time writing code, teams spend time validating whether the generated code is correct, secure, idiomatic, and maintainable. + +That creates a new form of debt: + +- code is produced faster than it is reviewed properly +- weak suggestions slip into the codebase because they look plausible +- reviewers must inspect more generated code with lower trust +- maintenance costs rise later because low-context code ages badly + +Recent survey data points in the same direction: + +- 72% of developers reported using AI tools daily +- AI contributes a substantial share of committed code in some teams +- 96% of developers do not fully trust AI-generated code +- less than half consistently review AI-generated code before committing +- 38% say reviewing AI code can take longer than reviewing human-written code + +That combination should worry engineering leaders. + +If teams accept more machine-generated code while also trusting it less, the result is not full automation. The result is a fragile review pipeline. + +This is why senior engineers are not becoming obsolete. Their work is shifting toward validation, standards, and system integrity. + + + +![Generated illustration](inline-2.png) + +## Security is the clearest reason AI won’t replace developers + +If you want one hard reality check, it is security. + +AI-generated code often looks polished. That makes insecure output more dangerous, not less dangerous. + +Research and industry testing have found recurring problems such as: + +- flawed input validation +- weak authentication or authorization logic +- unsafe serialization patterns +- insecure defaults +- cross-site scripting exposure +- log injection issues +- dependency and configuration mistakes + +A Veracode study covering 100 LLMs across 80 coding tasks found that about 45% of AI-generated code samples contained security flaws. Reported failure rates were especially high in some languages and security-sensitive tasks. + +That aligns with what many teams see in practice: AI can produce code that appears complete while quietly missing the exact defensive details that matter in production. + +There is a second security problem too: the tools themselves. + +Recent research into AI-enabled IDE workflows has highlighted risks such as: + +- prompt injection through project content +- data exfiltration from workspace context +- misuse of tool permissions +- remote code execution paths via compromised assistant workflows + +So the risk surface is now two-layered: + +1. the generated code may be unsafe +2. the coding assistant environment may itself introduce supply-chain and data exposure risks + +That is not a path to replacing developers. It is a path to needing more disciplined developers. + + + +![Generated illustration](inline-3.png) + +## Why junior and senior developers benefit differently + +AI does not help every developer in the same way. + +Less experienced developers often benefit the most from: + +- faster onboarding +- easier exploration of unfamiliar APIs +- reduced time spent on repetitive syntax work +- quick examples to unblock momentum + +That is a good thing. Used well, AI can shorten the distance between "I know the concept" and "I can build the first version." + +But there is a catch. + +If juniors over-rely on generated solutions they do not understand, they can ship code without building judgment. That creates a team with higher output but thinner engineering depth. + +Senior developers usually get less value from raw generation and more value from targeted acceleration. Their role shifts toward: + +- architectural direction +- code review and design review +- defining guardrails +- mentoring developers on when not to trust the tool +- shaping prompts and workflows around quality + +That is not replacement. It is role redistribution. + +## The best teams treat AI like a power tool, not a developer + +The most productive framing is simple: AI is a power tool. + +A power tool can make a skilled worker much faster. It can also let an unskilled worker make bigger mistakes faster. + +Teams getting real value from AI coding assistants usually do a few things consistently. + +### They define where AI is allowed to help + +For example: + +- okay for scaffolding and test drafts +- okay for documentation summaries +- okay for refactoring suggestions in low-risk modules +- not okay for auth flows without explicit review +- not okay for security-sensitive changes without human design approval +- not okay for direct commits to critical paths + +### They keep human review non-negotiable + +AI-generated code should be reviewed like code from a new team member who is fast, confident, and occasionally wrong in subtle ways. + +That means checking: + +- correctness +- security +- consistency with project conventions +- operational impact +- maintainability six months from now + +### They invest in guardrails + +Useful guardrails include: + +- secure coding standards +- mandatory tests for generated code +- SAST and dependency scanning +- branch protection and review policies +- secret scanning +- documented AI usage rules +- prompt hygiene, especially around sensitive data + +### They optimize for maintainability, not just speed + +The wrong metric is lines generated. + +Better metrics include: + +- cycle time without increased incident rate +- review burden +- escaped defects +- time to understand generated code later +- security findings per change + + + +![Generated illustration](inline-4.png) + +## When AI helps most — and when it helps least + +A balanced view is more useful than either fear or hype. + +### When to use AI-assisted coding + +AI is a strong fit when: + +- the task is repetitive or pattern-based +- the scope is narrow and easy to verify +- the code is low-risk and well-tested +- you need a first draft, not a final answer +- developers understand the output well enough to challenge it +- the team has solid review and security practices + +Examples: + +- generating DTOs, mappings, and validation stubs +- producing test cases for straightforward services +- drafting migration scripts that will be reviewed carefully +- summarizing unfamiliar code before manual refactoring + +### When not to rely on AI-assisted coding + +AI is a poor fit when: + +- business rules are complex or ambiguous +- security is central to the change +- architecture decisions are still in flux +- the code touches compliance-heavy or highly regulated paths +- the surrounding codebase has lots of undocumented behavior +- the team is unlikely to review the output carefully + +Examples: + +- permission and tenancy boundaries +- payment or identity workflows +- critical infrastructure automation +- cross-service consistency logic +- sensitive data handling and audit trails + +## What this means for the future of software teams + +AI is changing software development, but not in the simplistic way people often describe. + +The likely outcome is not fewer developers because code writes itself. The more plausible outcome is a different distribution of engineering work: + +- more generated code +- more review and verification work +- more emphasis on architecture and systems thinking +- more value placed on security awareness +- more leverage for developers who can guide tools effectively + +There are also organizational effects. + +If AI tools can remove some low-level friction, teams may ship faster. Some studies and industry analyses even project large macroeconomic gains from AI-augmented software work. But inside engineering organizations, those gains depend on whether speed is paired with discipline. + +Without discipline, AI increases noise. + +With discipline, AI increases leverage. + +That is the distinction leaders should care about. + +## The developer job is not disappearing — it is getting more judgment-heavy + +The strongest developers in the AI era will not be the ones who generate the most code. They will be the ones who can: + +- define the problem clearly +- evaluate tradeoffs +- spot incorrect assumptions +- review machine output efficiently +- protect quality under delivery pressure +- turn generated fragments into coherent systems + +That is a more senior version of software engineering, not a smaller one. + +Typing code was never the whole profession. It was just the most visible part. AI is making that easier, which means the less visible parts now matter even more. + +And those parts are deeply human: judgment, context, responsibility, and taste. + +## TL;DR + +- AI coding tools improve productivity on repetitive, bounded tasks, but the gains are usually incremental, not total automation. +- Developers are still needed for architecture, business logic, tradeoffs, security, and accountability. +- AI-generated code often adds verification debt, increasing review and maintenance work later. +- Security remains a major limitation, both in generated code and in AI-assisted development workflows. +- The winning teams use AI as a power tool with strong guardrails, not as a replacement for engineering judgment. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/cover.png b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/cover.png new file mode 100644 index 0000000000..9e5cfb860b Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-1.png b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-1.png new file mode 100644 index 0000000000..d2c734c3b7 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-2.png b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-2.png new file mode 100644 index 0000000000..724d15d84e Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-3.png b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-3.png new file mode 100644 index 0000000000..ba64f15192 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-4.png b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-4.png new file mode 100644 index 0000000000..ddbbdb74fd Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-ai-isnt-replacing-developers-its-changing-what-good/inline-4.png differ diff --git a/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/Post.md b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/Post.md new file mode 100644 index 0000000000..6c9a4e4a76 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/Post.md @@ -0,0 +1,631 @@ +Caching is one of those topics that looks simple until an application starts scaling. The first version works fine with direct database reads. Then traffic grows, page loads become inconsistent, and suddenly the team is debating Redis, stale data, invalidation, and why one node sees fresh data while another still serves old results. + +ABP Framework gives you a solid caching foundation, but the important part is choosing the right caching strategy for the job. Not everything should be cached the same way. A read-only lookup list, a tenant-specific settings object, and an entity that changes every minute do not have the same caching needs. + +This article walks through the practical caching strategies in ABP Framework, what each one is good at, how to configure them, and the mistakes that usually show up in production. + +## Understand ABP's caching model first + +ABP builds its caching support on top of `Microsoft.Extensions.Caching.Distributed.IDistributedCache`. That matters because ABP does not invent a completely separate caching universe. Instead, it adds practical features developers actually need in real systems: + +- typed cache abstractions +- automatic serialization and deserialization +- tenant-aware cache keys +- configurable key prefixes +- batch operations +- optional Unit of Work awareness +- safer error handling defaults + +Out of the box, the default distributed cache implementation is `MemoryDistributedCache`. Despite the name, this is still wired through the distributed cache abstraction, but the storage is in-memory for the current app instance. + +That is fine for: + +- local development +- demos +- single-node monoliths +- low-risk cached reads + +It is not enough for: + +- load-balanced deployments +- Kubernetes or App Service scale-out +- background workers sharing cached data with web apps +- any scenario where multiple instances must see the same cache state + +In those cases, you should move to a real distributed provider such as Redis. + + + +![Generated illustration](inline-1.png) + +## Strategy 1: Use typed distributed cache for application data + +For most ABP applications, the default and most useful strategy is the generic typed distributed cache. + +ABP provides: + +- `IDistributedCache` +- `IDistributedCache` + +These abstractions remove a lot of repetitive work. You do not have to manually serialize objects, invent every cache key shape yourself, or worry about tenant ID inclusion for common cases. + +### Why typed distributed cache is usually the best starting point + +It works well when you want to cache: + +- lookup lists +- settings snapshots +- permission-related read models +- dashboard widgets +- expensive API responses +- aggregated DTOs used by the UI + +This strategy is usually better than caching raw entities because cached application-facing models tend to be: + +- smaller +n- more stable +- easier to version +- less coupled to domain changes + +### Example: cache a product summary DTO + +```csharp +using Microsoft.Extensions.Caching.Distributed; +using Volo.Abp.Caching; + +[CacheName("ProductSummary")] +public class ProductSummaryCacheItem +{ + public Guid Id { get; set; } + public string Name { get; set; } + public decimal Price { get; set; } + public bool IsAvailable { get; set; } +} + +public class ProductAppService : ApplicationService +{ + private readonly IDistributedCache _cache; + private readonly IRepository _productRepository; + + public ProductAppService( + IDistributedCache cache, + IRepository productRepository) + { + _cache = cache; + _productRepository = productRepository; + } + + public async Task GetSummaryAsync(Guid id) + { + return await _cache.GetOrAddAsync( + id, + async () => + { + var product = await _productRepository.GetAsync(id); + + return new ProductSummaryCacheItem + { + Id = product.Id, + Name = product.Name, + Price = product.Price, + IsAvailable = product.StockCount > 0 + }; + }, + () => new DistributedCacheEntryOptions + { + SlidingExpiration = TimeSpan.FromMinutes(10), + AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(1) + } + ); + } +} +``` + +A few good things are happening here: + +- the cache item is small and explicit +- the key is strongly typed +- expiration is defined close to the use case +- both sliding and absolute expiration are used + +That last point is important. Sliding expiration alone can keep hot items alive indefinitely. Absolute expiration alone can evict popular items too aggressively. In many business cases, combining them gives you a better balance. + +### When to use + +Use typed distributed cache when: + +- you want a simple, explicit cache around a read operation +- the cached model is a DTO or a lightweight read model +- invalidation can be handled in application logic +- you need tenant-aware behavior without extra plumbing + +### When NOT to use + +Avoid it when: + +- the underlying data changes extremely often and stale reads are unacceptable +- the object is very large and serialization cost outweighs the benefit +- cache invalidation is too complex to reason about safely +- the query is already cheap and highly selective + +## Strategy 2: Use entity cache for read-heavy entity access + +ABP also provides an entity cache abstraction for read-only entity-level caching. This is useful when you repeatedly fetch entities or entity-based DTOs by ID and want cache invalidation to happen automatically on update or delete. + +This is where entity cache can save real effort. Instead of manually wiring remove calls in every update path, you lean on the framework's invalidation behavior. + +### What entity cache is good at + +Entity cache is a good fit for: + +- catalogs +- countries, regions, tax definitions +- organization units that are read often but changed infrequently +- profile-like records fetched by ID repeatedly + +It is a bad fit for highly volatile entities where every read risks becoming stale within seconds. + +### Example use case + +Suppose your application repeatedly loads a `Category` record by ID from both HTTP requests and background jobs. That category changes maybe once a week. Entity cache is a better fit than manually managing many distributed cache entries across the codebase. + +The main advantage is operational simplicity: + +- read-through usage is straightforward +- updates and deletes trigger invalidation automatically +- you get consistency improvements without scattering cache removal logic everywhere + +### A practical warning about entity versioning + +ABP supports entity versioning through `IHasEntityVersion`. If an entity implements it, ABP increments the `EntityVersion` on updates and uses that in invalidation-related behavior. + +That is useful, but there is one common trap: direct SQL updates outside the normal application flow bypass entity versioning and the domain pipeline. + +If your team runs scripts like this: + +```sql +update Products set Name = 'New Name' where Id = '...' +``` + +then your cache may not be invalidated as expected. + +If you use entity cache, make sure updates go through the application and domain stack whenever possible. If operational SQL scripts are unavoidable, explicitly account for cache invalidation. + +### When to use + +Use entity cache when: + +- reads are frequent and mostly by entity key +- entities change infrequently +- automatic invalidation on update/delete is valuable +- you want less manual cache removal code + +### When NOT to use + +Avoid it when: + +- the read model should differ significantly from the entity shape +- data is updated too frequently +- your team often bypasses the application layer with direct SQL updates +- the cached object graph is large or expensive to serialize + + + +![Generated illustration](inline-2.png) + +## Strategy 3: Prefer Redis for real distributed deployments + +A lot of caching problems are not about API design. They are deployment problems. + +If you run multiple application instances and still use the default in-memory distributed cache implementation, each node will maintain its own private cache state. That means: + +- node A may have fresh data +- node B may have stale data +- invalidation on one node does not magically update the others +- behavior becomes inconsistent under load balancing + +For production scale-out, Redis is usually the practical answer. + +ABP provides Redis integration through `Volo.Abp.Caching.StackExchangeRedis`. + +### Basic setup idea + +Install the Redis caching package and configure distributed caching as your backing provider. ABP then continues to use its caching abstractions, while Redis stores the actual cache entries. + +A typical module configuration looks like this: + +```csharp +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp.Caching; +using Volo.Abp.Modularity; + +[DependsOn(typeof(AbpCachingStackExchangeRedisModule))] +public class MyProjectModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + var configuration = context.Services.GetConfiguration(); + + context.Services.AddStackExchangeRedisCache(options => + { + options.Configuration = configuration["Redis:Configuration"]; + }); + + Configure(options => + { + options.KeyPrefix = "MyApp"; + options.GlobalCacheEntryOptions.SlidingExpiration = TimeSpan.FromMinutes(20); + options.HideErrors = true; + }); + } +} +``` + +### Why the key prefix matters + +If the same Redis server is shared by multiple applications or environments, a global key prefix is not optional in practice. Without it, key collisions become surprisingly easy. + +Good examples: + +- `MyApp-Prod` +- `SalesService` +- `TenantPortal` + +Bad example: + +- leaving it empty and hoping naming conventions elsewhere are enough + +## Strategy 4: Use batch cache operations for high-volume reads + +If you need to fetch many cache entries at once, ABP supports batch operations such as: + +- `GetManyAsync` +- `SetManyAsync` +- `RemoveManyAsync` + +This matters most in list and aggregation scenarios. + +For example, imagine a product page that needs cached summaries for 50 product IDs. Doing 50 individual round-trips is not ideal. If the provider supports batch operations well, this can reduce latency significantly. + +### Example: batch loading summaries + +```csharp +public async Task> GetManySummariesAsync(Guid[] ids) +{ + var cachedItems = await _cache.GetManyAsync(ids); + + var missingIds = ids + .Where(id => !cachedItems.ContainsKey(id) || cachedItems[id] == null) + .ToArray(); + + if (missingIds.Any()) + { + var products = await _productRepository.GetListAsync(x => missingIds.Contains(x.Id)); + + var newItems = products.ToDictionary( + x => x.Id, + x => new ProductSummaryCacheItem + { + Id = x.Id, + Name = x.Name, + Price = x.Price, + IsAvailable = x.StockCount > 0 + }); + + await _cache.SetManyAsync( + newItems, + new DistributedCacheEntryOptions + { + SlidingExpiration = TimeSpan.FromMinutes(10) + }); + + foreach (var item in newItems) + { + cachedItems[item.Key] = item.Value; + } + } + + return ids + .Where(id => cachedItems.ContainsKey(id) && cachedItems[id] != null) + .Select(id => cachedItems[id]) + .ToList(); +} +``` + +Provider support matters here. With Redis and ABP's Redis package, batch operations are especially useful. If the underlying provider does not support them efficiently, ABP can fall back to single operations. + +That means batch APIs are still worth using from an application-code perspective, but you should validate the real performance characteristics in your deployed environment. + +## Strategy 5: Make cache writes Unit of Work aware when consistency matters + +One subtle but valuable ABP feature is the `considerUow` flag on typed distributed cache operations. + +This is easy to overlook, but it can prevent a nasty class of bugs. + +Imagine this sequence: + +1. You update an entity. +2. You write a corresponding cache value immediately. +3. The database transaction later fails and rolls back. +4. The cache now contains data representing a change that never actually committed. + +That is classic stale-or-phantom cache state. + +When `considerUow` is enabled, ABP can defer cache writes until the Unit of Work completes successfully. + +### Example + +```csharp +await _cache.SetAsync( + id, + cacheItem, + options: new DistributedCacheEntryOptions + { + AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30) + }, + considerUow: true +); +``` + +Use this when cache state depends on transactional data changes in the same operation. + +### When to use + +Use `considerUow` when: + +- you update data and cache in the same business operation +- transaction rollback is possible +- cache correctness matters more than immediate write timing + +### When NOT to use + +You may skip it when: + +- you are caching purely read-side data after a committed fetch +- the operation is outside transactional boundaries +- eventual cache population is acceptable + + + +![Generated illustration](inline-3.png) + +## Strategy 6: Treat multi-tenancy as a cache design concern, not a detail + +ABP automatically includes the current tenant ID in cache keys for typed distributed cache scenarios unless multi-tenancy is explicitly ignored. + +This is one of those features that quietly prevents serious data leaks. + +Without tenant-aware cache keys, this can happen: + +- tenant A requests a settings object +- it gets cached under a generic key +- tenant B requests the same logical object +- tenant B receives tenant A's cached data + +That is not just a bug. In many systems, it is a security incident. + +### Practical guidance + +For multi-tenant systems: + +- keep tenant-aware caching enabled by default +- only ignore multi-tenancy for truly global shared data +- review custom key-building logic carefully +- test cache behavior with at least two tenants in integration tests + +If a cache item is intentionally global, make that decision explicit and document it. + +## Strategy 7: Be deliberate about expiration policy + +A lot of bad caching behavior comes from expiration values chosen almost randomly. + +ABP lets you define expiration using `DistributedCacheEntryOptions`, including: + +- `AbsoluteExpiration` +- `AbsoluteExpirationRelativeToNow` +- `SlidingExpiration` + +ABP also supports global defaults through `AbpDistributedCacheOptions`. If you do not specify item-level options, a default sliding expiration is commonly configured as 20 minutes. + +### A simple rule of thumb + +- Use sliding expiration for frequently accessed, low-volatility items. +- Use absolute expiration when freshness has a hard upper bound. +- Use both when you want hot items to stay warm, but not forever. + +### Example global configuration + +```csharp +Configure(options => +{ + options.GlobalCacheEntryOptions.SlidingExpiration = TimeSpan.FromMinutes(20); + options.HideErrors = true; + options.KeyPrefix = "MyApp"; +}); +``` + +### Common expiration patterns + +**Reference data** + +- sliding: 30 to 60 minutes +- absolute: 6 to 24 hours + +**User-specific dashboard data** + +- sliding: 5 to 15 minutes +- absolute: 15 to 60 minutes + +**Highly dynamic operational metrics** + +- short absolute expirations, or no cache at all + +These are not universal numbers, but they are more realistic than setting every cache entry to 24 hours and calling it done. + +## Strategy 8: Keep cache items small and serialization-friendly + +Distributed caching always includes serialization and deserialization overhead. ABP handles this for you, with JSON serialization by default, but the cost still exists. + +That means cache item design matters. + +### Prefer this + +- lean DTO-style cache items +- primitive properties +- only fields needed by the consuming path +- stable shapes that do not change constantly + +### Avoid this + +- huge object graphs +- navigation-heavy entities +- deeply nested collections when only a few fields are used +- caching everything just because it was already available in memory + +A cache entry should usually be optimized for read efficiency, not for domain completeness. + +If a page needs only `Name`, `Price`, and `Status`, do not cache the entire entity graph with audit fields, children, and metadata. + +## Strategy 9: Decide how hard cache failures should fail + +ABP defaults to a practical stance: cache errors are hidden and logged so your application can continue functioning. + +This default is often correct. + +If Redis has a transient issue, it is usually better for the request to fall back to the database than to fail completely. Caching should improve performance, not become a single point of failure. + +You can control this behavior globally with `AbpDistributedCacheOptions.HideErrors` and per operation with the `hideErrors` parameter. + +### Good default thinking + +Keep `HideErrors = true` when: + +- cache is a performance optimization +- falling back to source data is acceptable +- temporary cache outages should not break user flows + +Consider stricter behavior when: + +- cache is part of a critical coordination pattern +- silent fallback would overload downstream systems +- you are diagnosing a production issue and want failures surfaced more aggressively + +In most business applications, hidden-and-logged cache failures are the safer default. + +## What about automatic method-level caching? + +You may have seen community implementations that add automatic method-level caching through interception and a `[Cache]` attribute. + +That pattern can be attractive because it reduces boilerplate: + +- decorate a method +- define expiration +- cache the return value transparently +- optionally connect invalidation to entity changes + +It is a useful pattern, but it is important to say clearly: this is not part of ABP core. + +So treat it as an architectural choice, not a built-in feature. + +### Why teams like it + +- less repetitive cache code +- centralized cache policy +- easier adoption for query-heavy services + +### Why teams get into trouble with it + +- invalidation becomes less explicit +- stale data bugs are harder to trace +- cache scope decisions can become too magical +- developers may not realize when a method result is tenant-specific or user-specific + +If you adopt method-level caching, document it aggressively and be strict about invalidation rules. It can be productive, but only when the team fully understands the behavior. + +## Common mistakes in ABP caching + +Here are the mistakes that cause the most pain. + +### Using in-memory distributed cache in a multi-instance production setup + +This is probably the most common one. It works in testing, then becomes inconsistent under scale-out. + +Fix: use Redis or another true distributed cache provider. + +### Caching entities instead of read models by default + +This increases serialization cost and couples cache shape to domain shape. + +Fix: cache DTOs or purpose-built cache items unless entity cache is clearly the better fit. + +### Forgetting invalidation paths + +Manual caches live or die by invalidation quality. + +Fix: centralize writes, remove cache entries on updates, and use entity cache where automatic invalidation helps. + +### Relying only on sliding expiration + +Hot keys may stay forever. + +Fix: combine sliding and absolute expiration for many scenarios. + +### Ignoring tenant boundaries + +This can leak data across tenants. + +Fix: rely on ABP's tenant-aware key behavior and be very careful with custom key generation. + +### Writing to cache before transaction success + +This creates cache values for changes that later roll back. + +Fix: use `considerUow` for transactional cache writes. + +### Treating cache outages as impossible + +Eventually, your cache provider will have a bad day. + +Fix: decide upfront whether fallback or fail-fast behavior is right for each path. + +## A practical decision guide + +If you just want a sensible default approach for most ABP projects, this is a good starting point: + +1. Use typed distributed cache for expensive read models and DTOs. +2. Use Redis for anything beyond a single instance. +3. Use entity cache for read-heavy entities fetched by ID when automatic invalidation is valuable. +4. Combine sliding and absolute expiration for most business data. +5. Keep cache items small. +6. Use tenant-aware keys by default. +7. Use `considerUow` for cache writes tied to transactions. + +That covers a large percentage of real-world ABP caching needs without overengineering the system. + +## When to use / When NOT to use caching in ABP + +### Use caching when + +- the same data is read frequently +- computing or querying the result is expensive +- modest staleness is acceptable +- the cache key can be defined clearly +- invalidation rules are understandable + +### Do NOT use caching when + +- the underlying data changes constantly +- every read must reflect the latest committed value immediately +- the query is already cheap +- object serialization cost is high relative to the saved work +- the team cannot confidently maintain invalidation rules + +Caching is a performance tool, not a default architecture layer for every service method. + +## TL;DR + +- In ABP, typed distributed cache is the best default for caching DTOs and read models. +- `MemoryDistributedCache` is fine for single-instance apps, but scaled deployments should use Redis. +- Entity cache is useful for read-heavy entity access with automatic invalidation on update and delete. +- Use tenant-aware keys, sensible expiration policies, and `considerUow` to avoid subtle consistency bugs. +- Keep cache items small, explicit, and easy to invalidate. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/cover.png b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/cover.png new file mode 100644 index 0000000000..c95b525828 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-1.png b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-1.png new file mode 100644 index 0000000000..f64ec05422 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-2.png b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-2.png new file mode 100644 index 0000000000..5e7881c7d3 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-3.png b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-3.png new file mode 100644 index 0000000000..0c340d8700 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-caching-strategies-in-abp-framework/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/Post.md b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/Post.md new file mode 100644 index 0000000000..b8384ca165 --- /dev/null +++ b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/Post.md @@ -0,0 +1,693 @@ +Domain events look simple on paper: something happened, react to it. In a real ABP microservices solution, the hard part is not raising the event. The hard part is deciding which event belongs inside the service, which one should cross service boundaries, and how to publish it without losing data or coupling your modules into a distributed monolith. + +ABP gives you the primitives to do this well: local events, distributed events, aggregate-root support, and built-in outbox/inbox infrastructure. Used correctly, they let you keep your domain model clean while still coordinating work across microservices. + +This article walks through a practical way to implement domain events in ABP microservices, including the boundary between domain and integration events, the transactional flow, outbox/inbox configuration, and the pitfalls that usually show up after the first production incident. + +## Start with the right event boundary + +The most important design choice is this: + +- **Domain events** are internal to a bounded context. +- **Integration events** are for other microservices. + +These are not interchangeable, even if the payload looks similar. + +### Domain events + +A domain event represents something meaningful that happened inside your domain model. + +Examples: + +- `OrderPlacedDomainEvent` +- `PaymentCapturedDomainEvent` +- `ProductStockDecreasedDomainEvent` + +These events are typically handled **in-process**. In ABP, that usually means the **local event bus** or ABP's domain event dispatching from aggregates tracked by the ORM. + +Use domain events when you want to: + +- trigger side effects inside the same microservice +- keep aggregate logic focused +- avoid bloated application services +- coordinate rules across domain services without hard references + +### Integration events + +An integration event is a contract for communication between microservices. + +Examples: + +- `OrderPlacedEto` +- `StockCountChangedEto` +- `CustomerDeletedEto` + +In ABP, these go through the **distributed event bus**. With a real provider like RabbitMQ, Kafka, or Azure Service Bus, they leave the current process and get consumed elsewhere. + +Use integration events when you want to: + +- notify another microservice +- update a local projection in another service +- drive eventual consistency across bounded contexts + +### The rule that keeps systems healthy + +A good practical rule is: + +1. Raise a **domain event** from the aggregate or domain layer. +2. Handle it inside the same service. +3. From that handler, publish a **distributed event** if another microservice needs to know. + +That separation prevents leaking internal domain details into your external contracts. + + + +![Generated illustration](inline-1.png) + +## What ABP gives you out of the box + +ABP already supports the eventing model most microservices need. + +### Local event bus + +The local event bus is in-process. It is appropriate for: + +- domain events +- module-to-module communication inside the same app +- internal side effects that should not leave the service boundary + +### Distributed event bus + +The distributed event bus is for cross-process communication. + +A few practical notes matter here: + +- Without a real provider configured, it behaves effectively in-process. +- With RabbitMQ, Kafka, or another provider, it becomes actual inter-service messaging. +- It works best with **ETOs** instead of domain entities. + +### Aggregate roots and generated events + +ABP aggregate roots can generate events directly. In practice, if your entity inherits from `AggregateRoot`, you can use methods like: + +- `AddDomainEvent(...)` +- `AddDistributedEvent(...)` + +ABP collects these events and dispatches them during persistence, typically around `SaveChanges` in EF Core-based applications. + +That means your aggregate can say, "this happened," without knowing who will react. + +## A practical implementation flow + +Let's use a simple example: an Ordering microservice places an order, and an Inventory microservice needs to update its local stock view. + +### Step 1: Raise a domain event in the aggregate + +The aggregate should express business meaning, not infrastructure concerns. + +```csharp +public class Order : AggregateRoot +{ + public OrderStatus Status { get; private set; } + public Guid CustomerId { get; private set; } + + public void Place() + { + if (Status != OrderStatus.Draft) + { + throw new BusinessException("Order is not in draft state."); + } + + Status = OrderStatus.Placed; + + AddDomainEvent(new OrderPlacedDomainEvent(Id, CustomerId)); + } +} + +public record OrderPlacedDomainEvent(Guid OrderId, Guid CustomerId); +``` + +This is internal and business-oriented. It says nothing about RabbitMQ, contracts, queues, or other services. + +### Step 2: Handle the domain event inside the same microservice + +Now handle that event in-process. + +Typical responsibilities here: + +- update other local models +- start internal workflows +- publish an integration event for external consumers + +```csharp +public class OrderPlacedDomainEventHandler : + ILocalEventHandler, + ITransientDependency +{ + private readonly IDistributedEventBus _distributedEventBus; + + public OrderPlacedDomainEventHandler(IDistributedEventBus distributedEventBus) + { + _distributedEventBus = distributedEventBus; + } + + public async Task HandleEventAsync(OrderPlacedDomainEvent eventData) + { + await _distributedEventBus.PublishAsync( + new OrderPlacedEto + { + OrderId = eventData.OrderId, + CustomerId = eventData.CustomerId + } + ); + } +} +``` + +This is where the boundary is enforced: + +- domain event in +- integration event out + +### Step 3: Define a lean ETO + +Your Event Transfer Object should be serializable and intentionally small. + +```csharp +public class OrderPlacedEto +{ + public Guid OrderId { get; set; } + public Guid CustomerId { get; set; } +} +``` + +A few ABP-friendly rules for ETOs: + +- keep only the properties consumers actually need +- avoid navigation properties +- avoid circular references +- avoid polymorphic object graphs unless you really control serialization end to end +- prefer public setters or structures that deserialize cleanly + +Do not publish your aggregate itself. That creates versioning and serialization problems fast. + +### Step 4: Consume the distributed event in another microservice + +In the Inventory microservice, handle the integration event through the distributed event bus. + +```csharp +public class OrderPlacedHandler : + IDistributedEventHandler, + ITransientDependency +{ + private readonly IInventorySyncService _inventorySyncService; + + public OrderPlacedHandler(IInventorySyncService inventorySyncService) + { + _inventorySyncService = inventorySyncService; + } + + [UnitOfWork] + public virtual async Task HandleEventAsync(OrderPlacedEto eventData) + { + await _inventorySyncService.HandleOrderPlacedAsync( + eventData.OrderId, + eventData.CustomerId + ); + } +} +``` + +The `UnitOfWork` attribute is important when the handler writes to the local database. + +## Domain events vs distributed events in ABP + +A lot of design mistakes come from treating these as the same thing. They are not. + +### Domain events + +Characteristics: + +- in-process +- internal to one bounded context +- part of domain modeling +- can trigger multiple internal handlers +- often dispatched during the same persistence flow + +Typical example: + +- an `Order` was placed, so calculate loyalty points internally + +### Distributed events + +Characteristics: + +- cross-process +- integration contract between services +- serialized and brokered +- eventually consistent by nature +- must tolerate retries, duplication, and delayed delivery + +Typical example: + +- Ordering tells Inventory that an order was placed + +### The key difference in failure behavior + +If a local domain event handler fails, that failure is usually part of the current application's execution path. + +If a distributed event consumer fails in another microservice, the original transaction is already committed. You are now in the world of retries, poison messages, compensation, and idempotency. + +That is why integration events need a different level of discipline. + + + +![Generated illustration](inline-2.png) + +## Using AddDistributedEvent directly on aggregates + +ABP also allows aggregates and domain services to add distributed events directly. + +```csharp +public class Product : AggregateRoot +{ + public int StockCount { get; private set; } + + public void ChangeStock(int newCount) + { + StockCount = newCount; + + AddDistributedEvent(new StockCountChangedEto + { + ProductId = Id, + NewCount = newCount + }); + } +} + +public class StockCountChangedEto +{ + public Guid ProductId { get; set; } + public int NewCount { get; set; } +} +``` + +This is convenient, and ABP supports it well. + +Still, I would use it selectively. + +### When it works well + +- the event contract is stable +- the aggregate genuinely owns the integration signal +- the payload is simple +- the team is disciplined about not leaking internal state + +### When to be careful + +- the integration event may change independently from domain behavior +- multiple external contracts may be derived from one domain event +- you want the domain layer isolated from integration messaging concerns + +In larger systems, the domain-event-then-integration-event pattern usually ages better. + + + +![Generated illustration](inline-3.png) + +## The outbox pattern: the part that saves you in production + +Without outbox, the classic failure is simple: + +1. Save business data to the database. +2. Try publishing to the broker. +3. App crashes between the two. +4. Your data is committed, but the event is gone. + +Now one microservice thinks the operation happened, and the others never hear about it. + +Outbox exists to remove that gap. + +### How outbox works in ABP + +With outbox enabled: + +1. Your business data is saved. +2. The outgoing distributed event is also stored in the same database transaction. +3. A background worker reads pending outbox records. +4. It publishes them to the message broker. +5. Published records are marked processed and later cleaned up. + +That gives you transactional safety between your local state change and the fact that an event must be published. + +### EF Core outbox configuration + +Your DbContext needs to participate in event outbox support. + +```csharp +public class OrderingDbContext : AbpDbContext, IHasEventOutbox +{ + public DbSet OutgoingEvents { get; set; } + + protected override void OnModelCreating(ModelBuilder builder) + { + base.OnModelCreating(builder); + + builder.ConfigureEventOutbox(); + } +} +``` + +Then configure the outbox: + +```csharp +Configure(options => +{ + options.Outboxes.Configure(config => + { + config.UseDbContext(); + config.Selector = type => true; + }); +}); +``` + +The selector lets you choose which events go through that outbox. This becomes useful when a solution has multiple modules or database contexts. + +### Why selectors matter + +In modular ABP solutions, not every event should use every outbox. + +Selectors help you: + +- route specific event types through a specific context +- separate concerns between modules +- avoid a single shared event persistence strategy for everything + +That flexibility matters more as the solution grows. + +## The inbox pattern: the consumer-side safety net + +Outbox protects publishing. Inbox protects consumption. + +Without inbox, a consumer can receive an event and fail mid-processing, leaving you unsure whether the local change happened, whether to retry, or whether the event was already partially applied. + +### How inbox works in ABP + +With inbox enabled: + +1. The incoming event is persisted first. +2. ABP processes it in a transactional scope. +3. Processed records are tracked. +4. Duplicate deliveries can be detected and ignored safely. + +This gives you practical idempotency support and much better operational behavior. + +### EF Core inbox configuration + +Your consumer DbContext participates similarly. + +```csharp +public class InventoryDbContext : AbpDbContext, IHasEventInbox +{ + public DbSet IncomingEvents { get; set; } + + protected override void OnModelCreating(ModelBuilder builder) + { + base.OnModelCreating(builder); + + builder.ConfigureEventInbox(); + } +} +``` + +Then wire it up: + +```csharp +Configure(options => +{ + options.Inboxes.Configure(config => + { + config.UseDbContext(); + config.EventSelector = type => true; + config.HandlerSelector = type => true; + }); +}); +``` + +### Important operational trade-off + +Inbox and outbox improve reliability, but they add: + +- extra tables/collections +- polling and background processing +- a little more latency +- more database activity + +That trade-off is usually worth it for microservices. It is often unnecessary for a simple monolith. + +## Pre-defined entity distributed events + +ABP can automatically publish distributed entity lifecycle events. + +Common built-in types include: + +- `EntityCreatedEto` +- `EntityUpdatedEto` +- `EntityDeletedEto` + +These are useful when another service needs basic CRUD-oriented synchronization rather than a rich business workflow event. + +### Enabling auto entity events + +```csharp +Configure(options => +{ + options.AutoEventSelectors.Add(); + options.EtoMappings.Add(); +}); +``` + +And the mapped ETO: + +```csharp +public class ProductEto +{ + public Guid Id { get; set; } + public string Name { get; set; } + public int StockCount { get; set; } +} +``` + +### When this is a good fit + +- reference data synchronization +- local read model updates in another service +- straightforward create/update/delete propagation + +### When not to use it + +- when business meaning matters more than CRUD state +- when consumers should react to a specific business action, not a generic update +- when publishing all entity changes leaks too much internal behavior + +A `ProductUpdated` technical event is not the same as a meaningful `StockCountChanged` business event. + +## Entity synchronizer for local copies of remote data + +One common microservice pattern is keeping a local copy of remote entities for querying or validation. + +For example: + +- Catalog owns `Product` +- Ordering keeps a local product snapshot for order creation rules + +ABP's entity synchronizer support helps consume create/update/delete events and persist local copies. This is useful for eventual consistency scenarios where each service needs its own storage and query model. + +This pattern works well when: + +- read performance matters +- cross-service synchronous calls would be too chatty +- temporary staleness is acceptable + +It works poorly when: + +- the downstream service requires strict immediate consistency +- the data changes constantly and synchronization cost gets high +- teams assume replicated data is always current + +## Event naming and contract design + +ABP uses the event type's full class name by default unless you specify an event name explicitly. + +That default is convenient, but contracts deserve some care. + +### Good contract design principles + +- keep ETOs small +- include identifiers and values the consumer truly needs +- avoid domain behavior and private invariants in the payload +- design for versioning from day one +- prefer additive changes over breaking changes + +### A bad ETO usually looks like this + +- dozens of properties copied from the aggregate +- nested child collections that consumers barely use +- serialization-unfriendly types +- assumptions that all consumers share the same domain model + +### A better ETO usually looks like this + +- stable identifiers +- a small number of primitive fields +- explicit timestamps or version fields if useful +- business meaning that survives service evolution + +## Real-world pattern: publish from a domain handler, not the application service + +Many examples online publish distributed events directly from app services after repository calls. That works, but it tends to make orchestration logic pile up in the application layer. + +A cleaner ABP approach is often: + +- aggregate raises domain event +- local handler reacts +- local handler publishes distributed event + +Why this usually scales better: + +- the aggregate stays expressive +- the app service stays thin +- internal reactions remain composable +- multiple handlers can subscribe without changing the original use case + +It also makes testing easier because the business event becomes the seam. + +## Failure modes you should design for + +If you are using distributed events, assume these will happen eventually: + +- duplicate message delivery +- delayed delivery +- consumer failure after partial processing +- contract evolution across independently deployed services +- producer publishes faster than consumers can handle + +### Practical defenses + +- enable outbox on producers +- enable inbox on consumers +- make handlers idempotent +- keep events small and versionable +- avoid side effects that cannot be retried safely +- use compensating actions for multi-service workflows + +A distributed event is not a database transaction stretched across services. Treat it as asynchronous coordination. + +## When to use / When NOT to use + +### Use domain events in ABP when + +- you want to decouple internal side effects +- multiple parts of the same microservice should react to a business action +- your aggregate should express business intent without knowing infrastructure details +- you want cleaner application services + +### Do not use domain events when + +- a plain method call inside the same class is clearer +- the logic is not really event-driven and has only one obvious synchronous step +- the event abstraction makes the code harder to understand than the original flow + +### Use distributed events when + +- another microservice needs to react asynchronously +- eventual consistency is acceptable +- you want to avoid synchronous runtime coupling between services +- local replicas or read models must stay updated + +### Do not use distributed events when + +- the consumer requires immediate consistency before the current request can finish +- the workflow cannot tolerate asynchronous delays +- you have not planned for retries, idempotency, and failure handling +- you are using microservices in name only and everything still depends on lockstep behavior + +## A reference implementation shape + +In a typical ABP microservice, the structure often looks like this: + +### In the domain layer + +- aggregates call `AddDomainEvent(...)` +- optionally aggregates call `AddDistributedEvent(...)` for very stable external contracts +- domain logic stays free from broker-specific code + +### In the application or domain event handling layer + +- implement `ILocalEventHandler` +- translate domain events into integration ETOs +- publish using `IDistributedEventBus` + +### In infrastructure + +- configure RabbitMQ or another provider +- configure outbox/inbox on the relevant DbContexts +- tune event box options for polling, batching, cleanup + +### In consuming microservices + +- implement `IDistributedEventHandler` +- wrap data updates in a unit of work +- make processing idempotent + +That division keeps the model understandable and avoids most of the coupling problems teams introduce accidentally. + +## Common mistakes in ABP event-driven microservices + +### 1. Publishing entities instead of contracts + +This leaks internals and breaks consumers when your domain evolves. + +### 2. Treating domain events as public integration events + +Internal events and external contracts change at different speeds. Keep them separate. + +### 3. Skipping outbox in production + +It works until the day you hit the save-then-crash gap. + +### 4. Forgetting idempotency on consumers + +Brokers and retries do not guarantee single delivery in the way many teams assume. + +### 5. Emitting generic CRUD events for business workflows + +A business process usually deserves a business event, not just `EntityUpdated`. + +### 6. Putting too much data in ETOs + +Large event contracts create versioning pain, serialization issues, and unnecessary coupling. + +## Final recommendations + +If you are implementing domain events in ABP microservices, optimize for clear boundaries first and infrastructure reliability second. + +The pattern that works well in most real systems is: + +- raise domain events inside aggregates +- handle them locally +- publish explicit integration events for other services +- protect publishing with outbox +- protect consumption with inbox + +ABP already gives you the building blocks. The main challenge is not framework support. It is resisting the temptation to blur domain events, application events, and integration contracts into one catch-all mechanism. + +If you keep those boundaries sharp, your services remain easier to evolve, test, and operate. + +## TL;DR + +- In ABP, use domain events for in-process reactions inside one microservice and distributed events for cross-service communication. +- Prefer raising domain events from aggregates, then translating them into lean ETOs in local handlers. +- Enable outbox on producers and inbox on consumers to avoid lost events and improve idempotency. +- Use built-in entity events for synchronization scenarios, but prefer business events when workflow meaning matters. +- Keep integration contracts small, serializable, stable, and separate from your domain model. \ No newline at end of file diff --git a/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/cover.png b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/cover.png new file mode 100644 index 0000000000..d7aa34a813 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/cover.png differ diff --git a/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-1.png b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-1.png new file mode 100644 index 0000000000..dff7d67d5c Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-1.png differ diff --git a/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-2.png b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-2.png new file mode 100644 index 0000000000..5574439be2 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-2.png differ diff --git a/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-3.png b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-3.png new file mode 100644 index 0000000000..0d35b894ae Binary files /dev/null and b/docs/en/Community-Articles/2026-06-25-implementing-domain-events-in-abp-microservices/inline-3.png differ diff --git a/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/POST.md b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/POST.md new file mode 100644 index 0000000000..4a97b9d7cb --- /dev/null +++ b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/POST.md @@ -0,0 +1,419 @@ +# Working with Dapr Workflows in the ABP Framework + +Most real business processes don't finish in a single request. + +An order gets placed, inventory gets checked, a payment gets charged, and the customer gets notified. Each step can fail, time out, or need a retry. And the whole thing has to survive a process restart without losing its place or charging someone twice. + +We usually solve this with a pile of queues, a state table, and a lot of defensive code to track where each process is. It works, but the business logic ends up scattered across handlers and database rows, and nobody can read the flow top to bottom anymore. + +[I covered **Elsa** in two earlier articles](https://abp.io/community/search?tag=elsa) as one way to handle workflows in ABP. **Dapr Workflow** takes a different path: instead of an in-app engine, the workflow engine runs in the [**Dapr sidecar**](https://docs.dapr.io/concepts/dapr-services/sidecar/), and you write the process as ordinary C# code that Dapr makes durable. If the host crashes halfway through, the workflow picks up right where it left off. + +In this article, we'll build a small Dapr Workflow inside a fresh ABP project and run it end to end. By the time you reach the bottom, you should be able to copy the code, run it, and watch a workflow march through its steps. + +> **Note:** Versions matter here, because both ABP and Dapr move fast. This article is written in June 2026 against **ABP 10.4** (.NET 10), **Dapr 1.18**, and the **`Dapr.Workflow` 1.18.x** package. The `Dapr.Workflow` package was rewritten in Dapr 1.17, so older tutorials you find online may use a different API. + +## What Dapr Workflow Actually Is? + +You define a [**workflow**](https://docs.dapr.io/developing-applications/building-blocks/workflow/) that orchestrates a process, and [**activities**](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/#workflows-and-activities) that do the actual work (call a database, hit an API, send an email). + +> **This is orchestration rather than choreography:** one place drives the process, instead of services reacting to each other's events. The definitions live in your app, but the engine that executes them runs in the Dapr sidecar next to it. + +![Dapr workflow execution architecture diagram](./mermaid1.png) + +The key idea is **durable execution**. Dapr records every step to a state store, so the workflow can be replayed from history at any time. A crash, a deployment, or a scale-out event doesn't lose progress, and a workflow can run for seconds or for months. + +> ⚠️ One rule follows from this: **workflow code must be deterministic**. No `DateTime.Now`, no random values, no direct I/O. Anything non-deterministic goes into an activity. Even logging is affected, so inside a workflow you use `context.CreateReplaySafeLogger()` instead of a normal logger, otherwise every replay repeats your log lines. + +Under the hood, this all runs on [**Dapr actors**](https://docs.dapr.io/developing-applications/building-blocks/actors/actors-overview/), which is why the state store has to support actors. The good news is that the default local setup already handles this, as you'll see in a moment. + +--- + +## A Quick Note on ABP and Dapr + +ABP already ships a set of Dapr integration packages: `Volo.Abp.Dapr` (the core package), `Volo.Abp.EventBus.Dapr` and `Volo.Abp.AspNetCore.Mvc.Dapr.EventBus` (distributed event bus over Dapr pub/sub), `Volo.Abp.Http.Client.Dapr` (service invocation), and `Volo.Abp.DistributedLocking.Dapr` (distributed locking). You can read all about them in the [ABP Dapr integration documentation](https://abp.io/docs/latest/framework/dapr). + +These cover pub/sub, service-to-service calls, and locking. **Workflows are not part of ABP's Dapr integration**, and that's fine. Dapr Workflow has its own first-class .NET SDK (`Dapr.Workflow`), and you plug it straight into your ABP app like any other .NET library. So in this article we use the Dapr SDK directly, inside an ABP startup template. + +> **Note:** If you'd like to see deeper Dapr integration in ABP, or you'd like us to build a dedicated piece around Dapr Workflow, feel free to open a new issue on the [ABP GitHub repository](https://github.com/abpframework/abp/issues). Telling us what you need is the best way to help us prioritize it. + +--- + +## What We'll Build + +To keep this concrete, we'll build a small **order processing** workflow, the classic example for this kind of thing. + +The workflow takes an order, checks inventory, charges the customer, then notifies them. If the item is out of stock, it stops early and returns a rejected result. Nothing fancy on the business side, but it's enough to show the parts that matter: how a workflow chains activities, how state survives across steps, and how you start and track an instance. + +Here's the flow we're aiming for: + +- An order comes in with a product, a quantity, and a price +- **Check inventory**: if there isn't enough stock, reject the order and stop +- **Process payment**: charge the customer +- **Notify the customer**: let them know the order went through +- Return a final result + +Each of those steps will be an **activity**, and the workflow is the code that orchestrates them. Let's set up the project and build it. + +## Prerequisites + +Before we start, make sure you have these installed: + +- **.NET 10 SDK** +- **ABP CLI** (the current Studio CLI). Install it with `dotnet tool install -g Volo.Abp.Studio.Cli` (or update with `dotnet tool update -g Volo.Abp.Studio.Cli`) +- **Docker**, running on your machine +- [**Dapr CLI**, initialized once with `dapr init`](https://docs.dapr.io/getting-started/) + +That last step matters. When you run `dapr init` in self-hosted mode, Dapr pulls a few containers (including Redis) and writes a default `statestore.yaml` component. That default state store already has `actorStateStore: "true"` set, which is exactly what Dapr Workflow needs. So once `dapr init` finishes, you can run workflows locally with zero extra configuration. + +![dapr-init-run-result](./dapr-init-run-result.png) + +> **Pro Tip:** If you ever swap the default Redis store for your own component, double-check that it sets `actorStateStore: "true"`. Without it, workflows silently fail to start, and it's the line people forget most often. + +## Create the Project + +In this article I'll create a new layered solution with **EF Core** as the database provider, using the ABP CLI. + +> If you already have an ABP project, you don't need a new one. You can apply the following steps to your existing solution and skip this section. + +Create a new solution named `DaprWorkflowDemo` (or whatever you want): + +```bash +abp new DaprWorkflowDemo +``` + +Once the download finishes, your project boilerplate is ready. Open the solution in your IDE and run the `DaprWorkflowDemo.Web` project once to confirm the app starts and the UI works. + +> Since, we have created the solution via ABP Studio CLI, it automatically runs the initial-tasks, which init database, seed initial data and run `abp install-libs` command, so, no need run the **DbMigrator* project. + +> Default admin username is **admin** and the password is **1q2w3E***. You can use these credentials to login... + +We'll do all the workflow work inside the `DaprWorkflowDemo.Web` project, since that's the running host where the workflow engine connects to the sidecar. + +## Install the Dapr.Workflow Package + +Open a terminal in the `DaprWorkflowDemo.Web` project folder and add the package: + +```bash +dotnet add package Dapr.Workflow +``` + +-> **This single package gives you everything:** the base `Workflow` and `WorkflowActivity` types, the `AddDaprWorkflow` registration helper, and the `DaprWorkflowClient` you use to start and query workflows from code. + +## Define the Workflow and Its Activities + +Now let's write the order processing flow we sketched out earlier. + +First, create a `Workflows` folder in the `DaprWorkflowDemo.Web` project. We'll keep everything there for simplicity. + +Every input and output in a workflow gets serialized to the state store, so the types you pass around should be simple, JSON-friendly records (**_ensure they are serializable!_**). Let's define them: + +```csharp +namespace DaprWorkflowDemo.Web.Workflows; + +public record OrderPayload(string OrderId, string ProductName, int Quantity, decimal TotalPrice); + +public record InventoryResult(bool InStock); + +public record OrderResult(string OrderId, string Status); +``` + +Now the workflow itself. A workflow derives from `Workflow` and reads top to bottom like a normal method, even though every step is durably persisted: + +```csharp +using Dapr.Workflow; +using Microsoft.Extensions.Logging; +using System.Threading.Tasks; + +namespace DaprWorkflowDemo.Web.Workflows; + +public class OrderProcessingWorkflow : Workflow +{ + public override async Task RunAsync(WorkflowContext context, OrderPayload order) + { + var logger = context.CreateReplaySafeLogger(); + logger.LogInformation("Starting order {OrderId}: {Quantity} x {ProductName}", + order.OrderId, order.Quantity, order.ProductName); + + // 1. Check inventory + var inventory = await context.CallActivityAsync( + nameof(CheckInventoryActivity), order); + + if (!inventory.InStock) + { + logger.LogWarning("Order {OrderId} rejected: out of stock", order.OrderId); + return new OrderResult(order.OrderId, "Rejected: out of stock"); + } + + // 2. Process the payment + await context.CallActivityAsync(nameof(ProcessPaymentActivity), order); + + // 3. Notify the customer + await context.CallActivityAsync(nameof(NotifyCustomerActivity), order); + + logger.LogInformation("Order {OrderId} completed", order.OrderId); + return new OrderResult(order.OrderId, "Completed"); + } +} +``` + +A couple of things worth pointing out here. + +- `CallActivityAsync` does not invoke the activity directly. It schedules the work with the workflow engine, which records the result once the activity completes. If the process dies right after the payment step, Dapr replays the workflow, feeds it the already-recorded results for the completed steps, and resumes at the notification step. The customer never gets charged twice. This is the **task chaining** pattern. +- Notice the replay-safe logger too. Because the engine replays the workflow to rebuild its state, a normal logger would print the same lines over and over. `context.CreateReplaySafeLogger()` logs only on the first real pass. +- Now the activities. An activity is where the real work happens, and the only place you're allowed to be non-deterministic. It derives from `WorkflowActivity` and supports constructor injection, so you can pull in your ABP services, repositories, or any registered dependency: + +```csharp +using Dapr.Workflow; +using Microsoft.Extensions.Logging; +using System.Threading.Tasks; + +namespace DaprWorkflowDemo.Web.Workflows; + +public class CheckInventoryActivity : WorkflowActivity +{ + private readonly ILogger _logger; + + public CheckInventoryActivity(ILogger logger) + { + _logger = logger; + } + + public override Task RunAsync(WorkflowActivityContext context, OrderPayload order) + { + _logger.LogInformation("Checking inventory for {ProductName}", order.ProductName); + + // Pretend we queried a stock service or a repository here. + var inStock = order.Quantity <= 100; + + return Task.FromResult(new InventoryResult(inStock)); + } +} + +public class ProcessPaymentActivity : WorkflowActivity +{ + private readonly ILogger _logger; + + public ProcessPaymentActivity(ILogger logger) + { + _logger = logger; + } + + public override Task RunAsync(WorkflowActivityContext context, OrderPayload order) + { + _logger.LogInformation("Charging {TotalPrice:C} for order {OrderId}", + order.TotalPrice, order.OrderId); + + // Call your real payment provider here. + return Task.FromResult(null); + } +} + +public class NotifyCustomerActivity : WorkflowActivity +{ + private readonly ILogger _logger; + + public NotifyCustomerActivity(ILogger logger) + { + _logger = logger; + } + + public override Task RunAsync(WorkflowActivityContext context, OrderPayload order) + { + _logger.LogInformation("Notifying customer about order {OrderId}", order.OrderId); + + // Send an email, push a notification, publish an event, etc. + return Task.FromResult(null); + } +} +``` + +Each activity is isolated, so Dapr can retry a failed one without re-running the whole workflow. The two activities that don't return anything useful use `object?` as their output type and return `null`. That's why the workflow calls them with the non-generic `CallActivityAsync`, which ignores the result. + +Here's the shape of the process we just wrote: + +![Order processing workflow flowchart](./mermaid2.png) + +## Register the Workflow + +Workflows and activities need to be registered so the engine knows about them. Open your `DaprWorkflowDemoWebModule` class and register them in `ConfigureServices`. Most of the existing code is abbreviated for simplicity: + +```csharp +using DaprWorkflowDemo.Web.Workflows; +using Dapr.Workflow; + +public override void ConfigureServices(ServiceConfigurationContext context) +{ + var hostingEnvironment = context.Services.GetHostingEnvironment(); + var configuration = context.Services.GetConfiguration(); + + // ... existing ABP configuration ... + + //Configure Dapr Workflows... + context.Services.AddDaprWorkflow(options => + { + options.RegisterWorkflow(); + + options.RegisterActivity(); + options.RegisterActivity(); + options.RegisterActivity(); + }); +} +``` + +> `AddDaprWorkflow` does two things for us. It registers a background worker that connects to the sidecar's workflow engine and hosts your workflow definitions, and it registers a `DaprWorkflowClient` in the dependency injection container so you can start and query workflows from your own code later. + +That's all the wiring. There's no component YAML to write, because Dapr ships a built-in workflow component named `dapr` that runs on top of the actor state store we already have. + +## Run It With the Dapr Sidecar + +Here's the part that's different from a normal `dotnet run`. The workflow engine lives in the Dapr sidecar, so the app has to run **alongside** a sidecar. The Dapr CLI handles that for us. + +> In this section, I assume that you already run `dapr init` command before, as explained above. If you haven't run it yet, please first run it and then follow the instructions/commands below. + +First, make sure your database is migrated (run `DaprWorkflowDemo.DbMigrator` if you haven't). Then, from the `DaprWorkflowDemo.Web` project folder, start the app with Dapr: + +```bash +dapr run --app-id dapr-workflow-demo --dapr-http-port 3500 -- dotnet run +``` + +A few notes on this command: + +- `--app-id` is the identity of your app within Dapr. We'll use it nowhere else in this example, but Dapr needs it. +- `--dapr-http-port 3500` pins the sidecar's HTTP port so we know where to send requests. You can leave it out and let Dapr pick one, but pinning it keeps the next step simple. +- Everything after `--` is the command Dapr runs for your app. `dapr run` injects the sidecar's connection details (like the gRPC port) as environment variables, and the `Dapr.Workflow` worker reads them automatically to connect to the engine. + +Notice we don't pass `--app-port` here. That flag is only needed when Dapr has to call **into** your app (for pub/sub or service invocation). For workflows, your app connects **out** to the sidecar over gRPC, so we don't need it for this scenario. + +Once it's running, you'll see both the ABP app logs and the Dapr sidecar logs in the same terminal. + +## Does It Actually Work? + +The quickest way to test is to talk to the sidecar's **Workflow management HTTP API** directly. This hits Dapr, not your app, which makes it a clean smoke test with no extra endpoint code. + +Start a workflow instance. The component name is `dapr` (the built-in one), the workflow name is the class name, and we pass our own instance ID so it's easy to query: + +```bash +curl -i -X POST "http://localhost:3500/v1.0/workflows/dapr/OrderProcessingWorkflow/start?instanceID=order-001" \ + -H "Content-Type: application/json" \ + -d '{"OrderId":"order-001","ProductName":"Mechanical Keyboard","Quantity":2,"TotalPrice":59.90}' +``` + +The request body is the workflow input, and Dapr passes it straight through to your `OrderPayload`. You should get a `202 Accepted` back with the instance ID: + +```json +{ "instanceID": "order-001" } +``` + +Now query the status of that instance: + +```bash +curl "http://localhost:3500/v1.0/workflows/dapr/order-001" +``` + +After the workflow finishes, you'll see a `COMPLETED` status along with the serialized output: + +```json +{ + "instanceID": "order-001", + "workflowName": "OrderProcessingWorkflow", + "createdAt": "2026-06-29T15:30:15.038490Z", + "lastUpdatedAt": "2026-06-29T15:30:15.360885500Z", + "runtimeStatus": "COMPLETED", + "properties": { + "dapr.workflow.input": "{\"ProductName\":\"Mechanical Keyboard\",\"Quantity\":2,\"OrderId\":\"order-001\",\"TotalPrice\":59.9}", + "dapr.workflow.output": "{\"orderId\":\"order-001\",\"status\":\"Completed\"}" + } +} +``` + +If you check the terminal, you'll also see the log lines from the workflow and each activity in order: + +![dapr-workflow-response](./dapr-workflow-response.png) + +The same management API also lets you `terminate`, `pause`, `resume`, and `purge` instances, and `raiseEvent` to send external events into a waiting workflow. For example: + +```bash +# Permanently delete a finished workflow's state +curl -X POST "http://localhost:3500/v1.0/workflows/dapr/order-001/purge" +``` + +The `DaprWorkflowClient` exposes the same operations in code (terminating, suspending and resuming, purging, and raising external events on an instance), which is the way to go for anything beyond a quick manual test. + +## Triggering Workflows From Your ABP Code + +Hitting the sidecar API by hand is great for a quick check, but in a real app you'll start workflows from your own code, and this is the recommended path. That's what the `DaprWorkflowClient` is for, and `AddDaprWorkflow` already registered it for you. + +You can inject it anywhere, for example into a controller or an application service. Here's a minimal controller in the `DaprWorkflowDemo.Web` project that starts an order and reads its status: + +```csharp +using System.Threading.Tasks; +using DaprWorkflowDemo.Web.Workflows; +using Dapr.Workflow; +using Microsoft.AspNetCore.Mvc; + +namespace DaprWorkflowDemo.Web.Controllers; + +[ApiController] +[Route("api/orders")] +public class OrderController : ControllerBase +{ + private readonly DaprWorkflowClient _workflowClient; + + public OrderController(DaprWorkflowClient workflowClient) + { + _workflowClient = workflowClient; + } + + [HttpPost] + public async Task StartAsync(OrderPayload order) + { + var instanceId = await _workflowClient.ScheduleNewWorkflowAsync( + name: nameof(OrderProcessingWorkflow), + instanceId: order.OrderId, + input: order); + + return Accepted($"/api/orders/{instanceId}", new { instanceId }); + } + + [HttpGet("{instanceId}")] + public async Task GetStatusAsync(string instanceId) + { + var state = await _workflowClient.GetWorkflowStateAsync(instanceId); + + if (state is null || !state.Exists) + { + return NotFound(); + } + + return Ok(new + { + RuntimeStatus = state.RuntimeStatus.ToString(), + Output = state.ReadOutputAs() + }); + } +} +``` + +`ScheduleNewWorkflowAsync` returns immediately and the workflow runs in the background, so this fits the asynchronous request pattern nicely: return `202 Accepted` and let the client poll the status endpoint. + +> One ABP-specific thing to keep in mind: ABP enforces antiforgery validation for unsafe HTTP methods on cookie-authenticated requests. Server-to-server or `curl` calls without an auth cookie usually pass straight through, but if you call the `POST` endpoint from a logged-in browser session and get a `400` antiforgery error, you can relax the auto validation for this controller through `AbpAntiForgeryOptions`, the same way the Elsa articles did for the Elsa endpoints. + +## Going Further + +We built a simple linear flow, but **Dapr Workflow** supports the patterns you'll actually need in production, all in plain C#: + +- **Fan-out / fan-in**: schedule many activities in parallel and aggregate the results (it's just `Select` plus `Task.WhenAll`). +- **External events**: pause a workflow until a human approves something or another system calls back. This is great for approval flows. +- **Timers**: durably wait for minutes, days, or months without holding a thread. +- **Child workflows**: break a big process into smaller workflows with their own history and status. +- **Retry policies**: give an activity an exponential backoff policy so transient failures recover on their own. + +## Conclusion + +**Dapr Workflow** gives you durable execution for long-running processes without bolting a heavy orchestration engine into your code. The process is plain C# that reads top to bottom, Dapr makes it fault-tolerant by replaying from the state store, and the orchestration stays deterministic while the side effects live in activities. + +The nice part for us is that none of this fights with ABP. You create a normal ABP solution, add the `Dapr.Workflow` package, register your workflows in a module, and run with `dapr run`. ABP's own Dapr packages still cover pub/sub, service invocation, and locking, so you can mix all of these in the same solution when you need them. + +All the code in this article is self-contained, so you can copy it into a fresh ABP project and follow along from top to bottom. + +Thanks for reading, see you in the next one! diff --git a/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/cover-image.png b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/cover-image.png new file mode 100644 index 0000000000..e880a97ab0 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/cover-image.png differ diff --git a/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/dapr-init-run-result.png b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/dapr-init-run-result.png new file mode 100644 index 0000000000..38ab1848e5 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/dapr-init-run-result.png differ diff --git a/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/dapr-workflow-response.png b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/dapr-workflow-response.png new file mode 100644 index 0000000000..a26143b053 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/dapr-workflow-response.png differ diff --git a/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/mermaid1.png b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/mermaid1.png new file mode 100644 index 0000000000..c73af2bf63 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/mermaid1.png differ diff --git a/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/mermaid2.png b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/mermaid2.png new file mode 100644 index 0000000000..5f108a4842 Binary files /dev/null and b/docs/en/Community-Articles/2026-06-28-working-with-dapr-workflows/mermaid2.png differ diff --git a/docs/en/Community-Articles/2026-06-29-customizing-the-abp-framework/POST.md b/docs/en/Community-Articles/2026-06-29-customizing-the-abp-framework/POST.md new file mode 100644 index 0000000000..a343173dbf --- /dev/null +++ b/docs/en/Community-Articles/2026-06-29-customizing-the-abp-framework/POST.md @@ -0,0 +1,216 @@ +# Customizing the ABP Framework: A Developer's Guide to LeptonX Theme Overrides in Angular and the Transition to React UI + +Enterprise ASP.NET Boilerplate (ABP) projects rarely stay with default theme behavior for long. At some point, teams need stricter brand alignment, user experience (UX) consistency across modules, or product-specific shell behavior that goes beyond palette and typography tweaks. + +This article explains a practical way to customize the LeptonX theme in Angular projects through two primary layers : + +1. **Style Overriding:** Utilizing design tokens, global CSS custom properties (variables), and component-level styling. +2. **Element Overriding:** Replacing or extending UI fragments and layout pieces using ABP's built-in services. + +Finally, we connect this customization mindset to ABP’s new React direction, where application development teams own more of the user interface (UI) implementation directly from day one. + +## Why Overriding Matters in Real ABP Solutions + +In enterprise software engineering, frontend customization is not a cosmetic task. Instead, it directly supports core technical and architectural goals : + +- **Brand System Compliance:** Enforcing strict color palettes, layouts, and typography across tenant-facing portals and internal back-office administration pages. +- **Accessibility (a11y) Improvements:** Optimizing focus states, color contrast ratios, screen reader compatibility, and keyboard navigation to meet WCAG standards. +- **Product Differentiation:** Structuring distinct top-level layouts, sidebar behavior, and navigation elements to separate multiple products within the same suite. +- **Operational Usability:** Reorganizing application spaces to match domain-specific workflows and simplify intensive data-entry tasks. + +To avoid building fragile CSS overrides that break during framework updates, development teams must follow a strict, highly structured hierarchy of customization : + +| Level | Customization Type | Technical Mechanism | Strategic Role | +| :---: | :--- | :--- | :--- | +| **1** | **Token-Level Variables** | CSS Custom Properties | 🛡️ *First Line of Defense* | +| **2** | **Component-Style Patch** | Class-Based Overrides | 🎨 *Moderate Visual Tweaks* | +| **3** | **Element Replacement** | ReplaceableComponents | 🏗️ *Deep Structural Overrides* | + +Adhering to this hierarchy reduces "style debt" and ensures that theme upgrades remain manageable throughout the application lifecycle. + +### Layer 1: Style Overriding in LeptonX (Angular) + +Style overriding is the safest and most maintainable way to alter your application's presentation layer. The LeptonX engine relies heavily on CSS custom properties (variables) defined at the `:root` level. + +### Customizing Brand Colors and Typography Tokens + +To modify the default colors and branding assets, developers can define custom properties within the global `src/styles.scss` file : + +```scss +:root { + /* Set the primary brand color used on active elements, buttons, and focuses */ + --lpx-brand: #1e3a8a; + + /* Set the physical paths for the application logos */ + --lpx-logo: url('/assets/images/logo.png'); + --lpx-logo-icon: url('/assets/images/logo-icon.png'); /* Displayed when sidebar is collapsed */ +} +``` + +For applications utilizing multi-theme layouts (such as LeptonX Pro's Light, Dark, or Dim modes), variables can be scoped under individual theme classes to dynamically swap brand colors or assets : + +```scss +/* Scoping theme-specific logos to prevent visibility issues on dark backgrounds */ +:root.lpx-theme-dark, :root.lpx-theme-dim { + --lpx-logo: url('/assets/images/logo-light.png'); + --lpx-logo-icon: url('/assets/images/logo-icon-light.png'); +} +``` + +#### Solving the "Visual Branding Blink" on Initial Page Load + +A common issue in production occurs when the default LeptonX logo is briefly displayed on screen before the client browser parses the custom stylesheet. This latency creates a noticeable "blink" or flicker. + +To eliminate this rendering gap, bypass the CSS variable load phase by replacing the physical logo assets inside the web host project's public directory. Write your custom branding files directly to `/images/logo/leptonx/logo-light.png` inside the server's public folder. Because the fallback variable defaults directly to this location, the client browser displays the custom logo asset immediately without waiting to parse the custom CSS rules. + +Additionally, note that styles registered solely in the application's global `styles.scss` may fail to apply to the **Account Layout** (such as the standard login page) because it compiles within an isolated module lifecycle. To ensure your styling overrides apply globally, register the assets and styles in the Virtual File System (VFS) of the.NET backend host, making them universally accessible across all client routing contexts. + +### Layer 2: Element Overriding in LeptonX (Angular) + +When CSS modifications cannot support your required user experience (such as adding search interfaces, custom profile controls, or custom action layouts), teams must override the underlying UI elements. + +ABP provides the `ReplaceableComponentsService` to dynamically replace pre-built layout pieces with custom, project-owned Angular components without breaking core module logic. + +### Troubleshooting the Mobile User Profile Freeze + +In compiled editions of the LeptonX Lite layout library (specifically versions 3.1.x through 4.3.1), developers have identified a rendering bug affecting mobile layouts. When a user logs in via a mobile device and taps the profile dropdown menu, the page freezes. Instead of displaying the profile options, the sidebar area recursively renders a duplicate copy of the active route page. This layout loop completely breaks navigation until the page is refreshed. + +The root cause is a layout bug inside the compiled LeptonX library template (`mn-user-profile.component.html`), where the template markup is wrapped inside an `` tag instead of a structurally neutral `` tag. + +To resolve this issue, you can implement a custom component replacement : + +1. Generate a custom mobile profile component using the Angular CLI + + ```bash + ng g component components/my-mobile-profile + ``` + +2. Implement the component template, ensuring the wrapper elements utilize `` instead of ``. +3. Inject the `ReplaceableComponentsService` into your root `app.component.ts` to swap the underlying component keys during application bootstrap : + + ```tsx + import { Component, OnInit } from '@angular/core'; + import { ReplaceableComponentsService } from '@abp/ng.core'; + import { eThemeLeptonXComponents } from '@volosoft/ngx-lepton-x'; + import { MyMobileUserProfileComponent } from './components/my-mobile-profile.component'; + + @Component({ + selector: 'app-root', + template: '' + }) + export class AppComponent implements OnInit{ + private replaceableComponents = inject(ReplaceableComponentsService); + + ngOnInit() { + this.replaceableComponents.add({ + component: MyMobileUserProfileComponent, + key: eThemeLeptonXComponents.MobileUserProfile + }); + } + } + ``` + + +### Template Context: From LeptonX Demo Setup to Real ABP Application Templates + +When transitioning customized designs from local prototypes to production environments, development teams must choose between two operating modes : + +| **Operational Mode** | **Core Architecture** | **Rationale & Trade-offs** | +| --- | --- | --- | +| **Standard Template Mode** | Consumes LeptonX packages as standard dependencies (`@abp/ng.theme.lepton-x`) from npm registries. All overrides are applied at the application layer. | **Highly Recommended.** Keeps local project codebases clean, simplifies dependency updates, and avoids style debt. | +| **Source-Inspection Mode** | Utilizes the ABP CLI `get-source` command to download the raw theme code and configure temporary local path aliases. | **Diagnostic Only.** Best used for deep debugging, prototyping layout behaviors, or tracing framework-level bugs. | + +### Resolving Strict MIME Type CSS Loading Exceptions + +During local development or initial production deployments of LeptonX Lite Angular applications, browsers may refuse to apply the theme's styles. This issue manifests as a console exception: + +`Refused to apply style from 'http://localhost:4200/bootstrap-dim.css' because its MIME type ('text/html') is not a supported stylesheet MIME type, and strict MIME checking is enabled.` + +This error occurs when the browser requests static layout stylesheets from paths that do not exist, causing the back-end host to return a default 404 HTML fallback page. To resolve this, run the installation command in your client-side workspace : + +```bash +abp install-libs +``` + +This command forces the ABP CLI to parse package dependencies, copy the compiled stylesheets directly into the physical output directories, and make them available to the web server. + +### Deep Implementation: Integrating Theme Source Code and the Upgrade Trade-Off + +For complex enterprise scenarios requiring structural changes that cannot be achieved via standard token configurations or component replacements, developers have the option to bypass compiled packages entirely and integrate the theme’s raw source code. + +### How to Retrieve the Source Code + +ABP Commercial customers have full access to the complete source code of the LeptonX Pro theme. This can be downloaded directly through the ABP Suite user interface or by executing the following command in the ABP CLI within your project directory : + +``` +abp get-source Volo.Abp.LeptonXTheme +``` + +This command downloads the raw C# and Angular source files directly into your local solution structure. Once downloaded, you can modify the underlying HTML templates, restructure Angular modules, and alter core layout scripts to meet your product requirements. + +#### The Upgrade Warning: Maintenance Overhead and Style Debt + +While direct access to the source code provides complete design freedom, it comes with a major warning regarding long-term maintenance : + +- **Bypassing the Update Stream:** Once you replace official package references (such as `@volosoft/abp.ng.theme.lepton-x` or NuGet packages) with local project references, your application is disconnected from the automatic update pipeline. +- **Manual Merge Burden:** When Volosoft releases framework updates, security patches, or compatibility fixes (such as aligning with newer Angular or.NET compiler baselines), these updates will not automatically apply to your customized code. Your team must manually compare, diff, and merge upstream changes, which can introduce regressions and increase technical debt. +- **VFS and APIs as the First Line of Defense:** Before choosing a full source code integration, try using the Virtual File System (VFS) on the backend or standard component replacement APIs in the frontend to override only the specific elements you need to change. This allows you to customize the UI while keeping the rest of your theme packages fully upgradeable. + +### Connecting the Mindset to ABP’s New React Era + +The introduction of the React UI option in ABP 10.4 represents a major architectural shift. While the Angular implementation relies on structured layout packages and runtime component overrides, the React architecture prioritizes **direct developer ownership** of the presentation layer. + +```mermaid +graph TD + %% Styling + classDef react fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#0d47a1; + classDef dotnet fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px,color:#4a148c; + classDef proxy fill:#fff3e0,stroke:#fb8c00,stroke-width:2px,color:#e65100; + classDef tool fill:#f5f5f5,stroke:#757575,color:#333; + + %% React App Box + subgraph ReactApp ["React App Repository"] + C1["Custom Business Components
(Local Source Code)"]:::react + C2["TanStack Router & Query
(Type-Safe Client Routes)"]:::react + + T1["Vite Dev Server & Bundling
(Fast HMR, Vitest)"]:::tool + T2["Tailwind CSS / shadcn/ui
(Accessible UI Components)"]:::tool + + C1 --> C2 + T1 --> T2 + end + + %% Backend Box + subgraph NetCore ["ASP.NET Core Web API Host"] + P1["Dynamic API Client Proxies
(Auto-Generated Endpoints)"]:::proxy + A1["ABP Admin Console
(Delivered via NuGet)"]:::dotnet + + P1 <==> A1 + end + + %% Inter-Repository Flow + ReactApp -- "Generates Dynamic Proxies" --> P1 + + %% Layout Tweaks + style ReactApp fill:#fafafa,stroke:#1e88e5,stroke-width:1px,stroke-dasharray: 5 5; + style NetCore fill:#fafafa,stroke:#8e24aa,stroke-width:1px,stroke-dasharray: 5 5; +``` + +### What Stays Consistent vs. What Changes + +Understanding how patterns transfer between frameworks is key for teams migrating to the React UI: + +- **What Stays Consistent:** Core DDD infrastructure, backend integration, dynamic API proxy generation, multi-tenancy models, and permission-aware routing configurations. +- **What Changes:** Direct ownership of page layouts, faster iteration of UI composition, and modern utility-first styling tools. + +### A New Frontend Philosophy + +In the Angular model, developers import pre-built layouts from compiled packages and selectively override elements using classes or replacing components. While structured, this approach can sometimes feel like "fighting" the framework. + +The React UI model, by contrast, gives developers direct control over the UI components from day one. Standard administrative pages (such as Identity, Tenants, and Settings) are managed separately by the **ABP Admin Console** on the back-end host, while all application layouts and views remain locally in your React project. + +Built with modern tools like **Vite**, **Tailwind CSS**, and **shadcn/ui**, developers can customize and extend components directly in their local source files without needing complex overriding wrappers. + +Additionally, because the layout and page templates reside in local source directories rather than compiled packages, this architecture is highly optimized for AI-driven development. Automated coding agents (such as the ABP Studio AI Agent) can easily inspect and modify local layouts, run API proxy generation, and deploy updates quickly. + +Whether your enterprise solution leverages the structured, component-driven architecture of ABP's Angular UI or is stepping into the modern, developer-owned era of the Vite-powered React UI , establishing an intentional, upgrade-safe customization strategy is crucial. By resolving design changes through token-level custom properties first, documenting structural element overrides, and preparing public-facing technical resources to be highly citable by conversational search agents , development teams can insulate their codebases from technical debt. Ultimately, the transition from rigid theme packages to direct frontend ownership not only streamlines day-to-day software delivery but also ensures that your application framework remains flexible, performant, and visible in an AI-driven ecosystem. \ No newline at end of file diff --git a/docs/en/framework/infrastructure/object-to-object-mapping.md b/docs/en/framework/infrastructure/object-to-object-mapping.md index 5dcf526266..d8484a277e 100644 --- a/docs/en/framework/infrastructure/object-to-object-mapping.md +++ b/docs/en/framework/infrastructure/object-to-object-mapping.md @@ -254,8 +254,8 @@ public partial class UserToUserDtoMapper : TwoWayMapperBase public override partial UserDto Map(User source); public override partial void Map(User source, UserDto destination); - public override partial User ReverseMap(UserDto destination); - public override partial void ReverseMap(UserDto destination, User source); + public override partial User ReverseMap(UserDto source); + public override partial void ReverseMap(UserDto source, User destination); } ```` @@ -280,15 +280,15 @@ public partial class UserToUserDtoMapper : TwoWayMapperBase //TODO: Perform actions after the mapping } - public override partial User ReverseMap(UserDto destination); - public override partial void ReverseMap(UserDto destination, User source); + public override partial User ReverseMap(UserDto source); + public override partial void ReverseMap(UserDto source, User destination); - public override partial void BeforeReverseMap(UserDto destination) + public override partial void BeforeReverseMap(UserDto source) { //TODO: Perform actions before the reverse mapping } - public override partial void AfterReverseMap(UserDto destination, User source) + public override partial void AfterReverseMap(UserDto source, User destination) { //TODO: Perform actions after the reverse mapping } diff --git a/docs/en/package-version-changes.md b/docs/en/package-version-changes.md index 8049ffa986..431d012e59 100644 --- a/docs/en/package-version-changes.md +++ b/docs/en/package-version-changes.md @@ -7,6 +7,72 @@ # Package Version Changes +## 10.6.0-rc.1 + +| Package | Old Version | New Version | PR | +|---------|-------------|-------------|-----| +| Microsoft.AspNetCore.Authentication.JwtBearer | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Authentication.OpenIdConnect | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Authorization | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Components | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Components.Authorization | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Components.Web | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Components.WebAssembly | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Components.WebAssembly.Authentication | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Components.WebAssembly.DevServer | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Components.WebAssembly.Server | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.DataProtection.StackExchangeRedis | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Mvc.NewtonsoftJson | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.Mvc.Testing | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.TestHost | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.AspNetCore.WebUtilities | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Bcl.AsyncInterfaces | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Data.SqlClient | 6.1.1 | 7.0.2 | #25706 | +| Microsoft.Data.Sqlite | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore.Design | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore.InMemory | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore.Proxies | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore.Relational | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore.SqlServer | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore.Sqlite | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.EntityFrameworkCore.Tools | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Caching.Hybrid | 9.9.0 | 10.7.0 | #25706 | +| Microsoft.Extensions.Caching.Memory | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Caching.StackExchangeRedis | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Configuration.Binder | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Configuration.CommandLine | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Configuration.EnvironmentVariables | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Configuration.UserSecrets | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.DependencyInjection | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.DependencyInjection.Abstractions | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.FileProviders.Composite | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.FileProviders.Embedded | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.FileProviders.Physical | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.FileSystemGlobbing | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Hosting | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Hosting.Abstractions | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Http | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Identity.Core | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Localization | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Logging | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Logging.Abstractions | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Logging.Console | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Options | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.Extensions.Options.ConfigurationExtensions | 10.0.7 | 10.0.9 | #25706 | +| Microsoft.IdentityModel.JsonWebTokens | 8.16.0 | 8.19.1 | #25706 | +| Microsoft.IdentityModel.Protocols.OpenIdConnect | 8.16.0 | 8.19.1 | #25706 | +| Microsoft.IdentityModel.Tokens | 8.16.0 | 8.19.1 | #25706 | +| System.Collections.Immutable | 10.0.7 | 10.0.9 | #25706 | +| System.IdentityModel.Tokens.Jwt | 8.16.0 | 8.19.1 | #25706 | +| System.Management | 10.0.7 | 10.0.9 | #25706 | +| System.Security.Cryptography.Xml | 10.0.7 | 10.0.9 | #25706 | +| System.Security.Permissions | 10.0.7 | 10.0.9 | #25706 | +| System.Text.Encoding.CodePages | 10.0.7 | 10.0.9 | #25706 | +| System.Text.Encodings.Web | 10.0.7 | 10.0.9 | #25706 | +| System.Text.Json | 10.0.7 | 10.0.9 | #25706 | + ## 10.5.0-rc.4 | Package | Old Version | New Version | PR | diff --git a/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md b/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md index f19449d04f..ddae40e1d0 100644 --- a/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md +++ b/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md @@ -95,8 +95,8 @@ public partial class OrganizationUnitRoleToOrganizationUnitRoleDtoMapper : TwoWa public override partial OrganizationUnitRoleDto Map(OrganizationUnitRole source); public override partial void Map(OrganizationUnitRole source, OrganizationUnitRoleDto destination); - public override partial OrganizationUnitRole ReverseMap(OrganizationUnitRoleDto destination); - public override partial void ReverseMap(OrganizationUnitRoleDto destination, OrganizationUnitRole source); + public override partial OrganizationUnitRole ReverseMap(OrganizationUnitRoleDto source); + public override partial void ReverseMap(OrganizationUnitRoleDto source, OrganizationUnitRole destination); } [Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)] @@ -306,8 +306,8 @@ public partial class OrganizationUnitRoleToOrganizationUnitRoleDtoMapper : TwoWa public override partial OrganizationUnitRoleDto Map(OrganizationUnitRole source); public override partial void Map(OrganizationUnitRole source, OrganizationUnitRoleDto destination); - public override partial OrganizationUnitRole ReverseMap(OrganizationUnitRoleDto destination); - public override partial void ReverseMap(OrganizationUnitRoleDto destination, OrganizationUnitRole source); + public override partial OrganizationUnitRole ReverseMap(OrganizationUnitRoleDto source); + public override partial void ReverseMap(OrganizationUnitRoleDto source, OrganizationUnitRole destination); } [Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)] diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AbpAspNetCoreMvcModule.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AbpAspNetCoreMvcModule.cs index 9da7e7454f..0f80fe219d 100644 --- a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AbpAspNetCoreMvcModule.cs +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AbpAspNetCoreMvcModule.cs @@ -1,3 +1,4 @@ +using Microsoft.AspNetCore.Antiforgery; using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Mvc.ApplicationParts; using Microsoft.AspNetCore.Mvc.Filters; @@ -216,6 +217,27 @@ public class AbpAspNetCoreMvcModule : AbpModule }); ConfigureRouteBasedCulture(context); + DecorateAntiforgery(context); + } + + protected virtual void DecorateAntiforgery(ServiceConfigurationContext context) + { + // Wrap the registered IAntiforgery (DefaultAntiforgery from AddAntiforgery by default) with + // AbpAntiforgery so every antiforgery entry point goes through the claim normalization. + // Only an implementation-type registration is wrapped; a custom factory/instance registration of + // IAntiforgery is left as-is. + var descriptor = context.Services.LastOrDefault(d => d.ServiceType == typeof(IAntiforgery)); + if (descriptor?.ImplementationType == null) + { + return; + } + + context.Services.Replace(ServiceDescriptor.Describe( + typeof(IAntiforgery), + sp => new AbpAntiforgery( + (IAntiforgery)ActivatorUtilities.CreateInstance(sp, descriptor.ImplementationType), + sp.GetRequiredService>()), + descriptor.Lifetime)); } protected virtual void ConfigureRouteBasedCulture(ServiceConfigurationContext context) diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryClaimsPrincipalNormalizer.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryClaimsPrincipalNormalizer.cs new file mode 100644 index 0000000000..9275737245 --- /dev/null +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryClaimsPrincipalNormalizer.cs @@ -0,0 +1,66 @@ +using System; +using System.Linq; +using System.Security.Claims; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Security.Claims; + +namespace Volo.Abp.AspNetCore.Mvc.AntiForgery; + +public class AbpAntiForgeryClaimsPrincipalNormalizer : IAbpAntiForgeryClaimsPrincipalNormalizer, ITransientDependency +{ + public const string UserIdClaimIssuer = "AbpAntiForgery"; + + protected virtual string NormalizedIssuer => UserIdClaimIssuer; + + public virtual ClaimsPrincipal Normalize(ClaimsPrincipal principal) + { + var normalized = new ClaimsPrincipal(); + + foreach (var identity in principal.Identities) + { + normalized.AddIdentity(NormalizeIdentity(identity)); + } + + return normalized; + } + + protected virtual ClaimsIdentity NormalizeIdentity(ClaimsIdentity identity) + { + return new ClaimsIdentity( + identity.Claims.Select(NormalizeClaim), + identity.AuthenticationType, + identity.NameClaimType, + identity.RoleClaimType) + { + Actor = identity.Actor, + BootstrapContext = identity.BootstrapContext, + Label = identity.Label + }; + } + + protected virtual Claim NormalizeClaim(Claim claim) + { + var newClaim = new Claim( + claim.Type, + claim.Value, + claim.ValueType, + IsUserIdentifierClaim(claim.Type) ? NormalizedIssuer : claim.Issuer, + claim.OriginalIssuer); + + foreach (var property in claim.Properties) + { + newClaim.Properties[property.Key] = property.Value; + } + + return newClaim; + } + + // The claim types DefaultClaimUidExtractor inspects, in priority order, to build the antiforgery user id. + protected virtual bool IsUserIdentifierClaim(string claimType) + { + return string.Equals(claimType, AbpClaimTypes.UserId, StringComparison.Ordinal) || + string.Equals(claimType, "sub", StringComparison.Ordinal) || + string.Equals(claimType, ClaimTypes.NameIdentifier, StringComparison.Ordinal) || + string.Equals(claimType, ClaimTypes.Upn, StringComparison.Ordinal); + } +} diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryOptions.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryOptions.cs index 0c2cf8884c..f57a38d57a 100644 --- a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryOptions.cs +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryOptions.cs @@ -24,6 +24,13 @@ public class AbpAntiForgeryOptions /// public bool AutoValidate { get; set; } = true; + /// + /// Normalizes the user id claim issuer before generating/validating the antiforgery token, so the + /// same user produces the same token identifier under both cookie and bearer authentication. + /// Default value: true. + /// + public bool NormalizeUserIdClaimIssuer { get; set; } = true; + /// /// A predicate to filter types to auto-validate. /// Return true to select the type to validate. diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiforgery.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiforgery.cs new file mode 100644 index 0000000000..22c4900379 --- /dev/null +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiforgery.cs @@ -0,0 +1,101 @@ +using System; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Antiforgery; +using Microsoft.AspNetCore.Http; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Options; + +namespace Volo.Abp.AspNetCore.Mvc.AntiForgery; + +// Wraps the framework IAntiforgery so the antiforgery token's per-user identifier is computed against a +// normalized principal on every entry point (generation and validation, controllers and Razor Pages, +// ABP and built-in filters, cookie and bearer). This keeps the same user consistent across schemes whose +// user id claim carries a different issuer (e.g. "LOCAL AUTHORITY" for the Identity cookie vs. the token +// authority for a validated JWT or an OIDC cookie). +public class AbpAntiforgery : IAntiforgery +{ + protected IAntiforgery Inner { get; } + + protected AbpAntiForgeryOptions Options { get; } + + public AbpAntiforgery( + IAntiforgery inner, + IOptions options) + { + Inner = inner; + Options = options.Value; + } + + public virtual AntiforgeryTokenSet GetAndStoreTokens(HttpContext httpContext) + { + return WithNormalizedUser(httpContext, () => Inner.GetAndStoreTokens(httpContext)); + } + + public virtual AntiforgeryTokenSet GetTokens(HttpContext httpContext) + { + return WithNormalizedUser(httpContext, () => Inner.GetTokens(httpContext)); + } + + public virtual Task IsRequestValidAsync(HttpContext httpContext) + { + return WithNormalizedUserAsync(httpContext, () => Inner.IsRequestValidAsync(httpContext)); + } + + public virtual Task ValidateRequestAsync(HttpContext httpContext) + { + return WithNormalizedUserAsync(httpContext, async () => + { + await Inner.ValidateRequestAsync(httpContext); + return true; + }); + } + + public virtual void SetCookieTokenAndHeader(HttpContext httpContext) + { + WithNormalizedUser(httpContext, () => + { + Inner.SetCookieTokenAndHeader(httpContext); + return true; + }); + } + + protected virtual T WithNormalizedUser(HttpContext httpContext, Func action) + { + if (!Options.NormalizeUserIdClaimIssuer) + { + return action(); + } + + var normalizer = httpContext.RequestServices.GetRequiredService(); + var originalPrincipal = httpContext.User; + httpContext.User = normalizer.Normalize(originalPrincipal); + try + { + return action(); + } + finally + { + httpContext.User = originalPrincipal; + } + } + + protected virtual async Task WithNormalizedUserAsync(HttpContext httpContext, Func> action) + { + if (!Options.NormalizeUserIdClaimIssuer) + { + return await action(); + } + + var normalizer = httpContext.RequestServices.GetRequiredService(); + var originalPrincipal = httpContext.User; + httpContext.User = normalizer.Normalize(originalPrincipal); + try + { + return await action(); + } + finally + { + httpContext.User = originalPrincipal; + } + } +} diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/IAbpAntiForgeryClaimsPrincipalNormalizer.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/IAbpAntiForgeryClaimsPrincipalNormalizer.cs new file mode 100644 index 0000000000..bd2a581b5f --- /dev/null +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AntiForgery/IAbpAntiForgeryClaimsPrincipalNormalizer.cs @@ -0,0 +1,10 @@ +using System.Security.Claims; + +namespace Volo.Abp.AspNetCore.Mvc.AntiForgery; + +public interface IAbpAntiForgeryClaimsPrincipalNormalizer +{ + // Returns a copy of the principal whose user identifier claims carry a stable issuer, so the + // antiforgery token's per-user identifier is the same across authentication schemes. + ClaimsPrincipal Normalize(ClaimsPrincipal principal); +} diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs index 464981cb3c..bd5e1e82a0 100644 --- a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs @@ -175,7 +175,8 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide GetSupportedVersions(controllerType, method, setting), allowAnonymous, authorizeModels, - implementFrom + implementFrom, + GetReturnValueContentTypes(apiDescription) ) ); @@ -199,6 +200,27 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide } } + private static List? GetReturnValueContentTypes(ApiDescription apiDescription) + { + var preferred = apiDescription.SupportedResponseTypes + .FirstOrDefault(x => x.StatusCode == 200 && x.ApiResponseFormats.Any()) + ?? apiDescription.SupportedResponseTypes + .FirstOrDefault(x => x.StatusCode is >= 200 and < 300 && x.ApiResponseFormats.Any()); + + if (preferred == null) + { + return null; + } + + var contentTypes = preferred.ApiResponseFormats + .Select(f => f.MediaType) + .Where(m => !string.IsNullOrWhiteSpace(m)) + .Distinct() + .ToList(); + + return contentTypes.Count > 0 ? contentTypes : null; + } + private static List GetSupportedVersions(Type controllerType, MethodInfo method, ConventionalControllerSetting? setting) { diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ModelBinding/AbpDateTimeModelBinder.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ModelBinding/AbpDateTimeModelBinder.cs index ac6e44ed6c..35c62a626f 100644 --- a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ModelBinding/AbpDateTimeModelBinder.cs +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ModelBinding/AbpDateTimeModelBinder.cs @@ -42,14 +42,14 @@ public class AbpDateTimeModelBinder : IModelBinder _clock.SupportsMultipleTimezone && !_currentTimezoneProvider.TimeZone.IsNullOrWhiteSpace()) { + var timeZone = _currentTimezoneProvider.TimeZone; try { - var timezoneInfo = _timezoneProvider.GetTimeZoneInfo(_currentTimezoneProvider.TimeZone); - dateTime = new DateTimeOffset(dateTime, timezoneInfo.GetUtcOffset(dateTime)).UtcDateTime; + dateTime = _timezoneProvider.ConvertUnspecifiedToUtc(dateTime, timeZone); } catch { - _logger.LogWarning("Could not convert DateTime with unspecified Kind using timezone '{TimeZone}'.", _currentTimezoneProvider.TimeZone); + _logger.LogWarning("Could not convert DateTime with unspecified Kind using timezone '{TimeZone}'.", timeZone); } } diff --git a/framework/src/Volo.Abp.Http.Client/Volo/Abp/Http/Client/ClientProxying/ClientProxyBase.cs b/framework/src/Volo.Abp.Http.Client/Volo/Abp/Http/Client/ClientProxying/ClientProxyBase.cs index 107008deea..0b7a21c71e 100644 --- a/framework/src/Volo.Abp.Http.Client/Volo/Abp/Http/Client/ClientProxying/ClientProxyBase.cs +++ b/framework/src/Volo.Abp.Http.Client/Volo/Abp/Http/Client/ClientProxying/ClientProxyBase.cs @@ -108,8 +108,7 @@ public class ClientProxyBase : ITransientDependency { var responseContent = await RequestAsync(requestContext); - if (typeof(T) == typeof(IRemoteStreamContent) || - typeof(T) == typeof(RemoteStreamContent)) + if (typeof(T) == typeof(IRemoteStreamContent) || typeof(T) == typeof(RemoteStreamContent)) { /* returning a class that holds a reference to response * content just to be sure that GC does not dispose of @@ -127,7 +126,8 @@ public class ClientProxyBase : ITransientDependency var stringContent = await responseContent.ReadAsStringAsync(); if (typeof(T) == typeof(string)) { - return (T)(object)stringContent; + var unwrapped = UnwrapStringResponse(stringContent, responseContent.Headers?.ContentType?.MediaType); + return (T)(object)unwrapped!; } if (stringContent.IsNullOrWhiteSpace()) @@ -139,6 +139,39 @@ public class ClientProxyBase : ITransientDependency } } + protected virtual string? UnwrapStringResponse(string body, string? contentType) + { + if (body.IsNullOrEmpty() || contentType.IsNullOrWhiteSpace()) + { + return body; + } + + if (!IsJsonMediaType(NormalizeMediaType(contentType!))) + { + return body; + } + + try + { + var parsed = JsonSerializer.Deserialize(body); + return parsed ?? string.Empty; + } + catch + { + return body; + } + } + + protected static string NormalizeMediaType(string mediaType) + { + if (mediaType.IsNullOrWhiteSpace()) + { + return string.Empty; + } + var semi = mediaType.IndexOf(';'); + return (semi < 0 ? mediaType : mediaType.Substring(0, semi)).Trim().ToLowerInvariant(); + } + protected virtual async Task RequestAsync(ClientProxyRequestContext requestContext) { var clientConfig = ClientOptions.Value.HttpClientProxies.GetOrDefault(requestContext.ServiceType) ?? throw new AbpException($"Could not get HttpClientProxyConfig for {requestContext.ServiceType.FullName}."); @@ -326,14 +359,7 @@ public class ClientProxyBase : ITransientDependency HttpRequestMessage requestMessage, ApiVersionInfo apiVersion) { - //API Version - if (!apiVersion.Version.IsNullOrEmpty()) - { - //TODO: What about other media types? - requestMessage.Headers.Add("accept", $"{MimeTypes.Text.Plain}; v={apiVersion.Version}"); - requestMessage.Headers.Add("accept", $"{MimeTypes.Application.Json}; v={apiVersion.Version}"); - requestMessage.Headers.Add("api-version", apiVersion.Version); - } + AddAcceptHeaders(action, requestMessage, apiVersion); //Header parameters var headers = action.Parameters.Where(p => p.BindingSourceId == ParameterBindingSources.Header).ToArray(); @@ -378,6 +404,57 @@ public class ClientProxyBase : ITransientDependency } } + protected virtual void AddAcceptHeaders( + ActionApiDescriptionModel action, + HttpRequestMessage requestMessage, + ApiVersionInfo apiVersion) + { + var acceptForReturn = GetAcceptForActionReturn(action); + var versionSuffix = apiVersion.Version.IsNullOrEmpty() ? string.Empty : $"; v={apiVersion.Version}"; + + if (!acceptForReturn.IsNullOrEmpty()) + { + requestMessage.Headers.Add("accept", acceptForReturn + versionSuffix); + } + else + { + requestMessage.Headers.Add("accept", MimeTypes.Text.Plain + versionSuffix); + requestMessage.Headers.Add("accept", MimeTypes.Application.Json + versionSuffix); + } + + if (!apiVersion.Version.IsNullOrEmpty()) + { + requestMessage.Headers.Add("api-version", apiVersion.Version); + } + } + + protected virtual string? GetAcceptForActionReturn(ActionApiDescriptionModel action) + { + if (action.ReturnValue.IsRemoteStream || + action.ReturnValue.Type == typeof(IRemoteStreamContent).FullName || + action.ReturnValue.Type == typeof(RemoteStreamContent).FullName) + { + return MimeTypes.Application.OctetStream; + } + + var contentTypes = action.ReturnValue.ContentTypes; + if (contentTypes == null || contentTypes.Count == 0) + { + return null; + } + + var normalized = contentTypes.Select(NormalizeMediaType).ToList(); + + return normalized.FirstOrDefault(IsJsonMediaType) ?? normalized[0]; + } + + private static bool IsJsonMediaType(string normalizedMediaType) + { + return normalizedMediaType.Equals(MimeTypes.Application.Json, StringComparison.OrdinalIgnoreCase) || + normalizedMediaType.Equals("text/json", StringComparison.OrdinalIgnoreCase) || + normalizedMediaType.EndsWith("+json", StringComparison.OrdinalIgnoreCase); + } + protected virtual StringSegment RemoveQuotes(StringSegment input) { if (!StringSegment.IsNullOrEmpty(input) && input.Length >= 2 && input[0] == '"' && input[input.Length - 1] == '"') diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs index 7650e40f88..e01b39c94d 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs @@ -45,7 +45,7 @@ public class ActionApiDescriptionModel } - public static ActionApiDescriptionModel Create([NotNull] string uniqueName, [NotNull] MethodInfo method, [NotNull] string url, string? httpMethod, [NotNull] IList supportedVersions, bool? allowAnonymous = null, IList? authorizeDatas = null, string? implementFrom = null) + public static ActionApiDescriptionModel Create([NotNull] string uniqueName, [NotNull] MethodInfo method, [NotNull] string url, string? httpMethod, [NotNull] IList supportedVersions, bool? allowAnonymous = null, IList? authorizeDatas = null, string? implementFrom = null, IList? returnValueContentTypes = null) { Check.NotNull(uniqueName, nameof(uniqueName)); Check.NotNull(method, nameof(method)); @@ -58,7 +58,7 @@ public class ActionApiDescriptionModel Name = method.Name, Url = url, HttpMethod = httpMethod, - ReturnValue = ReturnValueApiDescriptionModel.Create(method.ReturnType), + ReturnValue = ReturnValueApiDescriptionModel.Create(method.ReturnType, returnValueContentTypes), Parameters = new List(), ParametersOnMethod = method .GetParameters() diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs index e77d2f7fea..25b2fb149a 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs @@ -1,4 +1,6 @@ using System; +using System.Collections.Generic; +using Volo.Abp.Content; using Volo.Abp.Reflection; using Volo.Abp.Threading; @@ -13,19 +15,30 @@ public class ReturnValueApiDescriptionModel public string? Summary { get; set; } + public IList? ContentTypes { get; set; } + + public bool IsRemoteStream { get; set; } + public ReturnValueApiDescriptionModel() { } - public static ReturnValueApiDescriptionModel Create(Type type) + public static ReturnValueApiDescriptionModel Create(Type type, IList? contentTypes = null) { var unwrappedType = AsyncHelper.UnwrapTask(type); return new ReturnValueApiDescriptionModel { Type = TypeHelper.GetFullNameHandlingNullableAndGenerics(unwrappedType), - TypeSimple = ApiTypeNameHelper.GetSimpleTypeName(unwrappedType) + TypeSimple = ApiTypeNameHelper.GetSimpleTypeName(unwrappedType), + ContentTypes = contentTypes, + IsRemoteStream = IsRemoteStreamType(unwrappedType) }; } + + private static bool IsRemoteStreamType(Type type) + { + return type == typeof(IRemoteStreamContent) || type == typeof(RemoteStreamContent); + } } diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/ProxyScripting/Generators/JQuery/JQueryProxyScriptGenerator.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/ProxyScripting/Generators/JQuery/JQueryProxyScriptGenerator.cs index 18af3e0661..8e15d85191 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/ProxyScripting/Generators/JQuery/JQueryProxyScriptGenerator.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/ProxyScripting/Generators/JQuery/JQueryProxyScriptGenerator.cs @@ -135,10 +135,9 @@ public class JQueryProxyScriptGenerator : IProxyScriptGenerator, ITransientDepen AddAjaxCallParameters(script, action); - var ajaxParamsIsFromForm = action.Parameters.Any(x => x.BindingSourceId == ParameterBindingSources.Form); - var dataType = action.ReturnValue.Type == ReturnValueApiDescriptionModel.Create(typeof(string)).Type - ? "{ dataType: 'text' }, " - : string.Empty; + var hasFormFile = action.Parameters.Any(x => x.BindingSourceId == ParameterBindingSources.FormFile); + var ajaxParamsIsFromForm = !hasFormFile && action.Parameters.Any(x => x.BindingSourceId == ParameterBindingSources.Form); + var dataType = GetJQueryDataTypeAndAcceptOverride(action); script.AppendLine(ajaxParamsIsFromForm ? " }, $.extend(true, {}, " + dataType + "{ contentType: 'application/x-www-form-urlencoded; charset=UTF-8' }, ajaxParams)));" : " }, " + dataType + "ajaxParams));"); @@ -146,6 +145,54 @@ public class JQueryProxyScriptGenerator : IProxyScriptGenerator, ITransientDepen script.AppendLine(" };"); } + private static string GetJQueryDataTypeAndAcceptOverride(ActionApiDescriptionModel action) + { + if (action.ReturnValue.IsRemoteStream) + { + return string.Empty; + } + + var contentTypes = action.ReturnValue.ContentTypes; + var isStringReturn = action.ReturnValue.Type == ReturnValueApiDescriptionModel.Create(typeof(string)).Type; + + if (contentTypes is { Count: > 0 }) + { + var normalized = contentTypes.Select(NormalizeMediaType).ToList(); + + var firstJsonShaped = normalized.FirstOrDefault(IsJsonMediaType); + if (firstJsonShaped != null) + { + return "{ dataType: 'json', headers: { Accept: '" + firstJsonShaped + "' } }, "; + } + + if (normalized.All(ct => ct.StartsWith("text/", StringComparison.OrdinalIgnoreCase))) + { + return "{ dataType: 'text', headers: { Accept: '" + normalized[0] + "' } }, "; + } + + return "{ headers: { Accept: '" + normalized[0] + "' } }, "; + } + + return isStringReturn ? "{ dataType: 'text' }, " : string.Empty; + } + + private static bool IsJsonMediaType(string normalizedMediaType) + { + return normalizedMediaType.Equals("application/json", StringComparison.OrdinalIgnoreCase) || + normalizedMediaType.Equals("text/json", StringComparison.OrdinalIgnoreCase) || + normalizedMediaType.EndsWith("+json", StringComparison.OrdinalIgnoreCase); + } + + private static string NormalizeMediaType(string mediaType) + { + if (string.IsNullOrWhiteSpace(mediaType)) + { + return string.Empty; + } + var semi = mediaType.IndexOf(';'); + return (semi < 0 ? mediaType : mediaType.Substring(0, semi)).Trim().ToLowerInvariant(); + } + private static string FindBestApiVersion(ActionApiDescriptionModel action) { //var configuredVersion = GetConfiguredApiVersion(); //TODO: Implement @@ -184,6 +231,20 @@ public class JQueryProxyScriptGenerator : IProxyScriptGenerator, ITransientDepen script.Append(" headers: " + headers); } + var firstFileParam = action.Parameters.FirstOrDefault(p => p.BindingSourceId == ParameterBindingSources.FormFile); + if (firstFileParam != null) + { + var fileVar = ProxyScriptingJsFuncHelper.NormalizeJsVariableName(firstFileParam.NameOnMethod.ToCamelCase()); + script.AppendLine(","); + script.Append(" data: " + fileVar + ","); + script.AppendLine(); + script.Append(" processData: false,"); + script.AppendLine(); + script.Append(" contentType: false"); + script.AppendLine(); + return; + } + var body = ProxyScriptingHelper.GenerateBody(action); if (!body.IsNullOrEmpty()) { diff --git a/framework/src/Volo.Abp.Json.Newtonsoft/Volo/Abp/Json/Newtonsoft/AbpDateTimeConverter.cs b/framework/src/Volo.Abp.Json.Newtonsoft/Volo/Abp/Json/Newtonsoft/AbpDateTimeConverter.cs index 55c270d14e..3b278d5252 100644 --- a/framework/src/Volo.Abp.Json.Newtonsoft/Volo/Abp/Json/Newtonsoft/AbpDateTimeConverter.cs +++ b/framework/src/Volo.Abp.Json.Newtonsoft/Volo/Abp/Json/Newtonsoft/AbpDateTimeConverter.cs @@ -134,14 +134,14 @@ public class AbpDateTimeConverter : DateTimeConverterBase, ITransientDependency return _skipDateTimeNormalization ? dateTime : _clock.Normalize(dateTime); } + var timeZone = _currentTimezoneProvider.TimeZone; try { - var timezoneInfo = _timezoneProvider.GetTimeZoneInfo(_currentTimezoneProvider.TimeZone); - dateTime = new DateTimeOffset(dateTime, timezoneInfo.GetUtcOffset(dateTime)).UtcDateTime; + dateTime = _timezoneProvider.ConvertUnspecifiedToUtc(dateTime, timeZone); } catch { - Logger.LogWarning("Could not convert DateTime with unspecified Kind using timezone '{TimeZone}'.", _currentTimezoneProvider.TimeZone); + Logger.LogWarning("Could not convert DateTime with unspecified Kind using timezone '{TimeZone}'.", timeZone); } return _skipDateTimeNormalization diff --git a/framework/src/Volo.Abp.Json.SystemTextJson/Volo/Abp/Json/SystemTextJson/JsonConverters/AbpDateTimeConverterBase.cs b/framework/src/Volo.Abp.Json.SystemTextJson/Volo/Abp/Json/SystemTextJson/JsonConverters/AbpDateTimeConverterBase.cs index ee39a66678..02aaec00b2 100644 --- a/framework/src/Volo.Abp.Json.SystemTextJson/Volo/Abp/Json/SystemTextJson/JsonConverters/AbpDateTimeConverterBase.cs +++ b/framework/src/Volo.Abp.Json.SystemTextJson/Volo/Abp/Json/SystemTextJson/JsonConverters/AbpDateTimeConverterBase.cs @@ -101,14 +101,14 @@ public abstract class AbpDateTimeConverterBase : JsonConverter return IsSkipDateTimeNormalization ? dateTime : Clock.Normalize(dateTime); } + var timeZone = CurrentTimezoneProvider.TimeZone; try { - var timezoneInfo = TimezoneProvider.GetTimeZoneInfo(CurrentTimezoneProvider.TimeZone); - dateTime = new DateTimeOffset(dateTime, timezoneInfo.GetUtcOffset(dateTime)).UtcDateTime; + dateTime = TimezoneProvider.ConvertUnspecifiedToUtc(dateTime, timeZone); } catch { - Logger.LogWarning("Could not convert DateTime with unspecified Kind using timezone '{TimeZone}'.", CurrentTimezoneProvider.TimeZone); + Logger.LogWarning("Could not convert DateTime with unspecified Kind using timezone '{TimeZone}'.", timeZone); } return IsSkipDateTimeNormalization ? dateTime : Clock.Normalize(dateTime); diff --git a/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/IAbpMapperlyMapper.cs b/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/IAbpMapperlyMapper.cs index eac0f6644c..80efb49f4c 100644 --- a/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/IAbpMapperlyMapper.cs +++ b/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/IAbpMapperlyMapper.cs @@ -13,11 +13,11 @@ public interface IAbpMapperlyMapper public interface IAbpReverseMapperlyMapper : IAbpMapperlyMapper { - TSource ReverseMap(TDestination destination); + TSource ReverseMap(TDestination source); - void ReverseMap(TDestination destination, TSource source); + void ReverseMap(TDestination source, TSource destination); - void BeforeReverseMap(TDestination destination); + void BeforeReverseMap(TDestination source); - void AfterReverseMap(TDestination destination, TSource source); + void AfterReverseMap(TDestination source, TSource destination); } diff --git a/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/MapperBase.cs b/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/MapperBase.cs index 39d9dce995..f49b2f14c9 100644 --- a/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/MapperBase.cs +++ b/framework/src/Volo.Abp.Mapperly/Volo/Abp/Mapperly/MapperBase.cs @@ -18,15 +18,15 @@ public abstract class MapperBase : IAbpMapperlyMapper : MapperBase, IAbpReverseMapperlyMapper { - public abstract TSource ReverseMap(TDestination destination); + public abstract TSource ReverseMap(TDestination source); - public abstract void ReverseMap(TDestination destination, TSource source); + public abstract void ReverseMap(TDestination source, TSource destination); - public virtual void BeforeReverseMap(TDestination destination) + public virtual void BeforeReverseMap(TDestination source) { } - public virtual void AfterReverseMap(TDestination destination, TSource source) + public virtual void AfterReverseMap(TDestination source, TSource destination) { } } diff --git a/framework/src/Volo.Abp.Timing/Volo/Abp/Timing/TimezoneProviderExtensions.cs b/framework/src/Volo.Abp.Timing/Volo/Abp/Timing/TimezoneProviderExtensions.cs new file mode 100644 index 0000000000..29779a08be --- /dev/null +++ b/framework/src/Volo.Abp.Timing/Volo/Abp/Timing/TimezoneProviderExtensions.cs @@ -0,0 +1,37 @@ +using System; + +namespace Volo.Abp.Timing; + +public static class TimezoneProviderExtensions +{ + /// + /// Interprets as local time in + /// and converts it to its UTC equivalent. The caller is expected to pass a + /// value; the kind is not inspected, so a value is always + /// treated as wall-clock time in the given timezone regardless of its kind. + /// + /// + /// Returns unchanged when applying the timezone offset would move it + /// outside the supported range. This happens for values within the offset + /// distance of /, typically the + /// placeholder that does not represent a real instant. Computing the + /// UTC ticks directly avoids the that + /// new DateTimeOffset(dateTime, offset) would throw for such values. + /// + public static DateTime ConvertUnspecifiedToUtc( + this ITimezoneProvider timezoneProvider, + DateTime dateTime, + string windowsOrIanaTimeZoneId) + { + Check.NotNull(timezoneProvider, nameof(timezoneProvider)); + + var timezoneInfo = timezoneProvider.GetTimeZoneInfo(windowsOrIanaTimeZoneId); + var utcTicks = dateTime.Ticks - timezoneInfo.GetUtcOffset(dateTime).Ticks; + if (utcTicks < DateTime.MinValue.Ticks || utcTicks > DateTime.MaxValue.Ticks) + { + return dateTime; + } + + return new DateTime(utcTicks, DateTimeKind.Utc); + } +} diff --git a/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryClaimsPrincipalNormalizer_Tests.cs b/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryClaimsPrincipalNormalizer_Tests.cs new file mode 100644 index 0000000000..7a2393586c --- /dev/null +++ b/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiForgeryClaimsPrincipalNormalizer_Tests.cs @@ -0,0 +1,263 @@ +using System; +using System.Security.Claims; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Antiforgery; +using Microsoft.AspNetCore.Http; +using Microsoft.Extensions.DependencyInjection; +using Shouldly; +using Volo.Abp.Security.Claims; +using Xunit; + +namespace Volo.Abp.AspNetCore.Mvc.AntiForgery; + +public class AbpAntiForgeryClaimsPrincipalNormalizer_Tests +{ + private const string CookieIssuer = "LOCAL AUTHORITY"; + private const string BearerIssuer = "https://localhost:44361/"; + private const string UserId = "3a0e6f1c-1111-2222-3333-444455556666"; + private const string AntiForgeryHeaderName = "RequestVerificationToken"; + private const string AntiForgeryCookieName = "AF"; + + [Fact] + public void Normalize_should_set_a_constant_issuer_on_user_identifier_claims_only() + { + var usernameClaim = new Claim("preferred_username", "admin", ClaimValueTypes.String, CookieIssuer); + usernameClaim.Properties["test-property"] = "test-value"; + + var principal = new ClaimsPrincipal(new ClaimsIdentity( + new[] + { + new Claim("sub", UserId, ClaimValueTypes.String, CookieIssuer), + new Claim(ClaimTypes.NameIdentifier, UserId, ClaimValueTypes.String, CookieIssuer), + usernameClaim + }, + "Identity.Application")); + + var normalized = new AbpAntiForgeryClaimsPrincipalNormalizer().Normalize(principal); + + normalized.FindFirst("sub")!.Issuer.ShouldBe(AbpAntiForgeryClaimsPrincipalNormalizer.UserIdClaimIssuer); + normalized.FindFirst(ClaimTypes.NameIdentifier)!.Issuer.ShouldBe(AbpAntiForgeryClaimsPrincipalNormalizer.UserIdClaimIssuer); + + // value and OriginalIssuer are kept; only Issuer changes + normalized.FindFirst("sub")!.Value.ShouldBe(UserId); + normalized.FindFirst("sub")!.OriginalIssuer.ShouldBe(CookieIssuer); + + // non-identifier claims and their properties are untouched + var normalizedUsername = normalized.FindFirst("preferred_username")!; + normalizedUsername.Issuer.ShouldBe(CookieIssuer); + normalizedUsername.Properties["test-property"].ShouldBe("test-value"); + + // the original principal is not mutated + principal.FindFirst("sub")!.Issuer.ShouldBe(CookieIssuer); + } + + [Fact] + public void Normalize_should_preserve_identity_metadata() + { + var actor = new ClaimsIdentity(new[] { new Claim(AbpClaimTypes.UserId, "actor-id") }, "Actor"); + var principal = new ClaimsPrincipal(new ClaimsIdentity( + new[] { new Claim("sub", UserId, ClaimValueTypes.String, BearerIssuer) }, + "Identity.Application") + { + Actor = actor, + BootstrapContext = "raw-token", + Label = "my-label" + }); + + var normalized = new AbpAntiForgeryClaimsPrincipalNormalizer().Normalize(principal); + var normalizedIdentity = (ClaimsIdentity)normalized.Identity!; + + // identity metadata that the antiforgery claim uid does not use is still preserved on the copy + normalizedIdentity.Actor.ShouldBeSameAs(actor); + normalizedIdentity.BootstrapContext.ShouldBe("raw-token"); + normalizedIdentity.Label.ShouldBe("my-label"); + // and the user id claim issuer was still normalized + normalized.FindFirst("sub")!.Issuer.ShouldBe(AbpAntiForgeryClaimsPrincipalNormalizer.UserIdClaimIssuer); + } + + [Fact] + public async Task Token_should_validate_for_the_same_cookie_principal_through_the_decorator() + { + // The common server-rendered case: a token generated and validated for the same cookie principal. + // Guards that wrapping IAntiforgery does not break the basic flow every page POST relies on. + var (antiforgery, serviceProvider) = CreateDecoratedAntiforgery(normalize: true); + + var cookiePrincipal = CreatePrincipal("Identity.Application", CookieIssuer); + var (cookieToken, requestToken) = GenerateToken(antiforgery, serviceProvider, cookiePrincipal); + + var isValid = await ValidateAsync(antiforgery, serviceProvider, cookiePrincipal, cookieToken, requestToken); + + isValid.ShouldBeTrue(); + } + + [Fact] + public async Task Token_issued_under_one_scheme_should_validate_under_another_when_normalization_is_enabled() + { + var (antiforgery, serviceProvider) = CreateDecoratedAntiforgery(normalize: true); + + var cookiePrincipal = CreatePrincipal("Identity.Application", CookieIssuer); + var (cookieToken, requestToken) = GenerateToken(antiforgery, serviceProvider, cookiePrincipal); + + var bearerPrincipal = CreatePrincipal("AuthenticationTypes.Federation", BearerIssuer); + var isValid = await ValidateAsync(antiforgery, serviceProvider, bearerPrincipal, cookieToken, requestToken); + + isValid.ShouldBeTrue(); + } + + [Fact] + public async Task Token_issued_under_one_scheme_should_fail_under_another_when_normalization_is_disabled() + { + var (antiforgery, serviceProvider) = CreateDecoratedAntiforgery(normalize: false); + + var cookiePrincipal = CreatePrincipal("Identity.Application", CookieIssuer); + var (cookieToken, requestToken) = GenerateToken(antiforgery, serviceProvider, cookiePrincipal); + + var bearerPrincipal = CreatePrincipal("AuthenticationTypes.Federation", BearerIssuer); + var isValid = await ValidateAsync(antiforgery, serviceProvider, bearerPrincipal, cookieToken, requestToken); + + isValid.ShouldBeFalse(); + } + + [Fact] + public async Task Token_should_validate_when_the_cookie_principal_user_id_issuer_is_not_local_authority() + { + // Tiered/OIDC templates back the cookie with an OIDC principal whose user id issuer is the token + // authority. Because the decorator normalizes both generation and validation (Razor Pages validate + // through the same decorated IAntiforgery), the per-user identifier still matches. + var (antiforgery, serviceProvider) = CreateDecoratedAntiforgery(normalize: true); + + var oidcCookiePrincipal = CreatePrincipal("Identity.Application", BearerIssuer); + var (cookieToken, requestToken) = GenerateToken(antiforgery, serviceProvider, oidcCookiePrincipal); + + var isValid = await ValidateAsync(antiforgery, serviceProvider, oidcCookiePrincipal, cookieToken, requestToken); + + isValid.ShouldBeTrue(); + } + + [Fact] + public async Task Token_should_validate_across_schemes_when_principal_has_both_sub_and_name_identifier() + { + // The extractor picks "sub" before NameIdentifier and a principal can carry both, so the + // normalization must cover the claim actually picked. + var (antiforgery, serviceProvider) = CreateDecoratedAntiforgery(normalize: true); + + var cookiePrincipal = CreatePrincipalWithSubAndNameIdentifier("Identity.Application", CookieIssuer); + var (cookieToken, requestToken) = GenerateToken(antiforgery, serviceProvider, cookiePrincipal); + + var bearerPrincipal = CreatePrincipalWithSubAndNameIdentifier("AuthenticationTypes.Federation", BearerIssuer); + var isValid = await ValidateAsync(antiforgery, serviceProvider, bearerPrincipal, cookieToken, requestToken); + + isValid.ShouldBeTrue(); + } + + [Fact] + public async Task Decorator_should_restore_the_original_principal_after_each_call() + { + var (antiforgery, serviceProvider) = CreateDecoratedAntiforgery(normalize: true); + + var originalPrincipal = CreatePrincipal("AuthenticationTypes.Federation", BearerIssuer); + var httpContext = new DefaultHttpContext { User = originalPrincipal, RequestServices = serviceProvider }; + + antiforgery.GetAndStoreTokens(httpContext); + + httpContext.User.ShouldBeSameAs(originalPrincipal); + httpContext.User.FindFirst(AbpClaimTypes.UserId)!.Issuer.ShouldBe(BearerIssuer); + + httpContext.Request.Headers["Cookie"] = $"{AntiForgeryCookieName}=invalid"; + await antiforgery.IsRequestValidAsync(httpContext); + + httpContext.User.ShouldBeSameAs(originalPrincipal); + httpContext.User.FindFirst(AbpClaimTypes.UserId)!.Issuer.ShouldBe(BearerIssuer); + } + + [Fact] + public async Task Decorator_should_not_normalize_when_disabled() + { + var (antiforgery, serviceProvider) = CreateDecoratedAntiforgery(normalize: false); + + var principal = CreatePrincipal("Identity.Application", CookieIssuer); + var httpContext = new DefaultHttpContext { User = principal, RequestServices = serviceProvider }; + + antiforgery.GetAndStoreTokens(httpContext); + httpContext.User.ShouldBeSameAs(principal); + + httpContext.Request.Headers["Cookie"] = $"{AntiForgeryCookieName}=invalid"; + await antiforgery.IsRequestValidAsync(httpContext); + httpContext.User.ShouldBeSameAs(principal); + } + + private static ClaimsPrincipal CreatePrincipal(string authenticationType, string userIdClaimIssuer) + { + return new ClaimsPrincipal(new ClaimsIdentity( + new[] + { + new Claim(AbpClaimTypes.UserId, UserId, ClaimValueTypes.String, userIdClaimIssuer), + new Claim("preferred_username", "admin", ClaimValueTypes.String, userIdClaimIssuer) + }, + authenticationType, + "preferred_username", + AbpClaimTypes.Role)); + } + + private static ClaimsPrincipal CreatePrincipalWithSubAndNameIdentifier(string authenticationType, string issuer) + { + return new ClaimsPrincipal(new ClaimsIdentity( + new[] + { + new Claim("sub", UserId, ClaimValueTypes.String, issuer), + new Claim(ClaimTypes.NameIdentifier, UserId, ClaimValueTypes.String, issuer), + new Claim("preferred_username", "admin", ClaimValueTypes.String, issuer) + }, + authenticationType, + "preferred_username", + AbpClaimTypes.Role)); + } + + private static (IAntiforgery antiforgery, IServiceProvider serviceProvider) CreateDecoratedAntiforgery(bool normalize) + { + var services = new ServiceCollection(); + services.AddLogging(); + services.AddDataProtection(); + services.AddAntiforgery(options => + { + options.Cookie.Name = AntiForgeryCookieName; + options.HeaderName = AntiForgeryHeaderName; + }); + services.AddTransient(); + + var serviceProvider = services.BuildServiceProvider(); + + var antiforgery = new AbpAntiforgery( + serviceProvider.GetRequiredService(), + Microsoft.Extensions.Options.Options.Create(new AbpAntiForgeryOptions { NormalizeUserIdClaimIssuer = normalize })); + + return (antiforgery, serviceProvider); + } + + private static (string cookieToken, string requestToken) GenerateToken( + IAntiforgery antiforgery, IServiceProvider serviceProvider, ClaimsPrincipal user) + { + var httpContext = new DefaultHttpContext { User = user, RequestServices = serviceProvider }; + var tokenSet = antiforgery.GetAndStoreTokens(httpContext); + return (ExtractCookieToken(httpContext), tokenSet.RequestToken!); + } + + private static async Task ValidateAsync( + IAntiforgery antiforgery, IServiceProvider serviceProvider, ClaimsPrincipal user, string cookieToken, string requestToken) + { + var httpContext = new DefaultHttpContext { User = user, RequestServices = serviceProvider }; + httpContext.Request.Headers["Cookie"] = $"{AntiForgeryCookieName}={cookieToken}"; + httpContext.Request.Headers[AntiForgeryHeaderName] = requestToken; + + return await antiforgery.IsRequestValidAsync(httpContext); + } + + private static string ExtractCookieToken(HttpContext httpContext) + { + var setCookie = httpContext.Response.Headers.SetCookie.ToString(); + var prefix = AntiForgeryCookieName + "="; + var start = setCookie.IndexOf(prefix, StringComparison.Ordinal) + prefix.Length; + var end = setCookie.IndexOf(';', start); + return end < 0 ? setCookie.Substring(start) : setCookie.Substring(start, end - start); + } +} diff --git a/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiforgery_Tests.cs b/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiforgery_Tests.cs new file mode 100644 index 0000000000..9ac20ed4d6 --- /dev/null +++ b/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/AntiForgery/AbpAntiforgery_Tests.cs @@ -0,0 +1,182 @@ +using System; +using System.Security.Claims; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Antiforgery; +using Microsoft.AspNetCore.Http; +using Microsoft.Extensions.DependencyInjection; +using Shouldly; +using Volo.Abp.Security.Claims; +using Xunit; + +namespace Volo.Abp.AspNetCore.Mvc.AntiForgery; + +public class AbpAntiforgery_Tests +{ + private const string BearerIssuer = "https://localhost:44361/"; + private const string UserId = "3a0e6f1c-1111-2222-3333-444455556666"; + + [Fact] + public Task GetAndStoreTokens_should_normalize_the_user_and_restore_it() => + Should_normalize_then_restore( + (antiforgery, httpContext) => { antiforgery.GetAndStoreTokens(httpContext); return Task.CompletedTask; }, + inner => inner.UserSeenByGetAndStoreTokens); + + [Fact] + public Task GetTokens_should_normalize_the_user_and_restore_it() => + Should_normalize_then_restore( + (antiforgery, httpContext) => { antiforgery.GetTokens(httpContext); return Task.CompletedTask; }, + inner => inner.UserSeenByGetTokens); + + [Fact] + public Task IsRequestValidAsync_should_normalize_the_user_and_restore_it() => + Should_normalize_then_restore( + (antiforgery, httpContext) => antiforgery.IsRequestValidAsync(httpContext), + inner => inner.UserSeenByIsRequestValid); + + [Fact] + public Task ValidateRequestAsync_should_normalize_the_user_and_restore_it() => + Should_normalize_then_restore( + (antiforgery, httpContext) => antiforgery.ValidateRequestAsync(httpContext), + inner => inner.UserSeenByValidateRequest); + + [Fact] + public Task SetCookieTokenAndHeader_should_normalize_the_user_and_restore_it() => + Should_normalize_then_restore( + (antiforgery, httpContext) => { antiforgery.SetCookieTokenAndHeader(httpContext); return Task.CompletedTask; }, + inner => inner.UserSeenBySetCookieTokenAndHeader); + + [Fact] + public void Should_delegate_the_result_to_the_inner_antiforgery() + { + var inner = new RecordingAntiforgery(); + var antiforgery = new AbpAntiforgery(inner, CreateOptions(normalize: true)); + var httpContext = CreateHttpContext(CreatePrincipal(BearerIssuer), withNormalizer: true); + + var tokenSet = antiforgery.GetAndStoreTokens(httpContext); + + tokenSet.RequestToken.ShouldBe(RecordingAntiforgery.RequestToken); + tokenSet.CookieToken.ShouldBe(RecordingAntiforgery.CookieToken); + } + + [Fact] + public void Should_not_normalize_when_disabled() + { + var inner = new RecordingAntiforgery(); + var antiforgery = new AbpAntiforgery(inner, CreateOptions(normalize: false)); + var original = CreatePrincipal(BearerIssuer); + var httpContext = CreateHttpContext(original, withNormalizer: true); + + antiforgery.GetAndStoreTokens(httpContext); + + // the inner saw the original (un-normalized) principal + inner.UserSeenByGetAndStoreTokens.ShouldBeSameAs(original); + inner.UserSeenByGetAndStoreTokens!.FindFirst(AbpClaimTypes.UserId)!.Issuer.ShouldBe(BearerIssuer); + httpContext.User.ShouldBeSameAs(original); + } + + [Fact] + public void Should_not_resolve_the_normalizer_service_when_disabled() + { + // the normalizer is intentionally not registered; the disabled fast-path must not touch RequestServices + var inner = new RecordingAntiforgery(); + var antiforgery = new AbpAntiforgery(inner, CreateOptions(normalize: false)); + var httpContext = CreateHttpContext(CreatePrincipal(BearerIssuer), withNormalizer: false); + + Should.NotThrow(() => antiforgery.GetAndStoreTokens(httpContext)); + } + + private static async Task Should_normalize_then_restore( + Func invoke, + Func userSeenByInner) + { + var inner = new RecordingAntiforgery(); + var antiforgery = new AbpAntiforgery(inner, CreateOptions(normalize: true)); + var original = CreatePrincipal(BearerIssuer); + var httpContext = CreateHttpContext(original, withNormalizer: true); + + await invoke(antiforgery, httpContext); + + // the inner ran against the normalized principal + userSeenByInner(inner)!.FindFirst(AbpClaimTypes.UserId)!.Issuer + .ShouldBe(AbpAntiForgeryClaimsPrincipalNormalizer.UserIdClaimIssuer); + // the original principal is restored after the call + httpContext.User.ShouldBeSameAs(original); + } + + private static Microsoft.Extensions.Options.IOptions CreateOptions(bool normalize) + { + return Microsoft.Extensions.Options.Options.Create( + new AbpAntiForgeryOptions { NormalizeUserIdClaimIssuer = normalize }); + } + + private static HttpContext CreateHttpContext(ClaimsPrincipal user, bool withNormalizer) + { + var services = new ServiceCollection(); + if (withNormalizer) + { + services.AddTransient(); + } + + return new DefaultHttpContext + { + User = user, + RequestServices = services.BuildServiceProvider() + }; + } + + private static ClaimsPrincipal CreatePrincipal(string userIdClaimIssuer) + { + return new ClaimsPrincipal(new ClaimsIdentity( + new[] + { + new Claim(AbpClaimTypes.UserId, UserId, ClaimValueTypes.String, userIdClaimIssuer) + }, + "AuthenticationTypes.Federation")); + } + + private sealed class RecordingAntiforgery : IAntiforgery + { + public const string RequestToken = "test-request-token"; + public const string CookieToken = "test-cookie-token"; + + public ClaimsPrincipal? UserSeenByGetAndStoreTokens { get; private set; } + public ClaimsPrincipal? UserSeenByGetTokens { get; private set; } + public ClaimsPrincipal? UserSeenByIsRequestValid { get; private set; } + public ClaimsPrincipal? UserSeenByValidateRequest { get; private set; } + public ClaimsPrincipal? UserSeenBySetCookieTokenAndHeader { get; private set; } + + public AntiforgeryTokenSet GetAndStoreTokens(HttpContext httpContext) + { + UserSeenByGetAndStoreTokens = httpContext.User; + return CreateTokenSet(); + } + + public AntiforgeryTokenSet GetTokens(HttpContext httpContext) + { + UserSeenByGetTokens = httpContext.User; + return CreateTokenSet(); + } + + public Task IsRequestValidAsync(HttpContext httpContext) + { + UserSeenByIsRequestValid = httpContext.User; + return Task.FromResult(true); + } + + public Task ValidateRequestAsync(HttpContext httpContext) + { + UserSeenByValidateRequest = httpContext.User; + return Task.CompletedTask; + } + + public void SetCookieTokenAndHeader(HttpContext httpContext) + { + UserSeenBySetCookieTokenAndHeader = httpContext.User; + } + + private static AntiforgeryTokenSet CreateTokenSet() + { + return new AntiforgeryTokenSet(RequestToken, CookieToken, "RequestVerificationToken", "RequestVerificationToken"); + } + } +} diff --git a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/Client/ClientProxying/ClientProxyBase_ContentTypes_Tests.cs b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/Client/ClientProxying/ClientProxyBase_ContentTypes_Tests.cs new file mode 100644 index 0000000000..c30fbb0d43 --- /dev/null +++ b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/Client/ClientProxying/ClientProxyBase_ContentTypes_Tests.cs @@ -0,0 +1,275 @@ +#nullable enable +using System.Collections.Generic; +using System.Linq; +using System.Net.Http; +using Shouldly; +using Volo.Abp.Content; +using Volo.Abp.Http.Modeling; +using Xunit; + +namespace Volo.Abp.Http.Client.ClientProxying; + +public class ClientProxyBase_GetAcceptForActionReturn_Tests +{ + [Fact] + public void IRemoteStreamContent_Should_Pick_OctetStream_Even_When_ContentTypes_Include_Json() + { + var action = BuildAction( + returnType: typeof(IRemoteStreamContent).FullName!, + contentTypes: new[] { "application/json", "text/plain", "text/json" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/octet-stream"); + } + + [Fact] + public void RemoteStreamContent_Concrete_Type_Should_Pick_OctetStream() + { + var action = BuildAction( + returnType: typeof(RemoteStreamContent).FullName!, + contentTypes: null); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/octet-stream"); + } + + [Fact] + public void Json_In_ContentTypes_Should_Pick_Json() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "text/plain", "application/json", "text/json" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/json"); + } + + [Fact] + public void Only_Text_ContentTypes_Should_Pick_TextPlain() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "text/plain", "text/csv" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("text/plain"); + } + + [Fact] + public void Empty_Or_Null_ContentTypes_Should_Return_Null() + { + InvokeGetAcceptForActionReturn(BuildAction("System.Int32", null)).ShouldBeNull(); + InvokeGetAcceptForActionReturn(BuildAction("System.Int32", new string[0])).ShouldBeNull(); + } + + [Fact] + public void Mixed_Text_And_Octet_Stream_Should_Echo_First_Content_Type() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "text/plain", "application/octet-stream" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("text/plain"); + } + + [Fact] + public void JsonV2_Variant_Should_Still_Pick_Json() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "application/json; charset=utf-8" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/json"); + } + + [Fact] + public void Single_TextHtml_Should_Echo_Back_TextHtml() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "text/html" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("text/html"); + } + + [Fact] + public void OctetStream_Only_With_ObjectReturn_Should_Echo_OctetStream() + { + var action = BuildAction( + returnType: "My.Project.UserDto", + contentTypes: new[] { "application/octet-stream" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/octet-stream"); + } + + [Fact] + public void ApplicationXml_Only_Should_Echo_Back_Xml_Instead_Of_Legacy_Pair() + { + var action = BuildAction( + returnType: "My.Project.SoapEnvelope", + contentTypes: new[] { "application/xml" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/xml"); + } + + [Fact] + public void Case_Insensitive_Json_Match() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "APPLICATION/JSON" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/json"); + } + + [Fact] + public void Json_With_Charset_Parameter_Should_Still_Pick_Json() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "application/json; charset=utf-8" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/json"); + } + + [Fact] + public void Text_With_Charset_Parameter_Should_Still_Pick_TextPlain() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "text/plain ; charset=utf-8 " }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("text/plain"); + } + + [Fact] + public void Text_Json_Should_Echo_Back_Text_Json() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "text/json" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("text/json"); + } + + [Fact] + public void Application_Problem_Json_Should_Echo_Back_The_Plus_Json_Variant() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "application/problem+json" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/problem+json"); + } + + [Fact] + public void Vendor_Plus_Json_Should_Echo_Back_The_Plus_Json_Variant() + { + var action = BuildAction( + returnType: "System.String", + contentTypes: new[] { "application/vnd.api+json" }); + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/vnd.api+json"); + } + + [Fact] + public void IsRemoteStream_Flag_True_Should_Pick_OctetStream_Regardless_Of_TypeName() + { + var action = BuildAction( + returnType: "My.Project.CustomStream", + contentTypes: new[] { "application/json" }); + action.ReturnValue.IsRemoteStream = true; + + InvokeGetAcceptForActionReturn(action).ShouldBe("application/octet-stream"); + } + + private static string? InvokeGetAcceptForActionReturn(ActionApiDescriptionModel action) + { + var proxy = new TestableClientProxy(); + return proxy.PublicGetAcceptForActionReturn(action); + } + + private static ActionApiDescriptionModel BuildAction(string returnType, IList? contentTypes) + { + return new ActionApiDescriptionModel + { + UniqueName = "Sample", + Name = "Sample", + HttpMethod = "GET", + Url = "api/test", + SupportedVersions = new List(), + ParametersOnMethod = new List(), + Parameters = new List(), + ReturnValue = new ReturnValueApiDescriptionModel + { + Type = returnType, + TypeSimple = returnType, + ContentTypes = contentTypes + }, + AuthorizeDatas = new List() + }; + } + + [Fact] + public void AddHeaders_With_ApiVersion_Should_Combine_OctetStream_Accept_With_Version_Suffix() + { + var action = BuildAction( + returnType: typeof(IRemoteStreamContent).FullName!, + contentTypes: new[] { "application/json", "text/plain" }); + + var headers = InvokeAddHeadersAndCollectAccept(action, version: "2.0"); + + headers.ShouldContain("application/octet-stream; v=2.0"); + headers.ShouldNotContain(h => h == "text/plain; v=2.0"); + headers.ShouldNotContain(h => h == "application/json; v=2.0"); + } + + [Fact] + public void AddHeaders_Without_ApiVersion_Should_Emit_OctetStream_For_Stream_Returns() + { + var action = BuildAction( + returnType: typeof(IRemoteStreamContent).FullName!, + contentTypes: new[] { "application/json" }); + + var headers = InvokeAddHeadersAndCollectAccept(action, version: null); + + headers.ShouldContain("application/octet-stream"); + } + + [Fact] + public void AddHeaders_Without_ContentType_Metadata_Should_Fall_Back_To_Text_And_Json_Pair() + { + var action = BuildAction(returnType: "System.Int32", contentTypes: null); + + var headers = InvokeAddHeadersAndCollectAccept(action, version: "1.0"); + + headers.ShouldContain("text/plain; v=1.0"); + headers.ShouldContain("application/json; v=1.0"); + } + + [Fact] + public void AddHeaders_Without_ApiVersion_And_Without_ContentType_Metadata_Should_Emit_Unversioned_Text_Json_Pair() + { + var action = BuildAction(returnType: "System.Int32", contentTypes: null); + + var headers = InvokeAddHeadersAndCollectAccept(action, version: null); + + headers.ShouldContain("text/plain"); + headers.ShouldContain("application/json"); + headers.ShouldNotContain(h => h.Contains("; v=")); + } + + private static IList InvokeAddHeadersAndCollectAccept(ActionApiDescriptionModel action, string? version) + { + var proxy = new TestableClientProxy(); + var message = new HttpRequestMessage(HttpMethod.Get, "http://localhost/x"); + var apiVersion = new ApiVersionInfo("HeaderModelBinding", version ?? string.Empty); + proxy.PublicAddAcceptHeaders(action, message, apiVersion); + return message.Headers.Accept.Select(a => a.ToString()).ToList(); + } + + private sealed class TestableClientProxy : ClientProxyBase + { + public string? PublicGetAcceptForActionReturn(ActionApiDescriptionModel action) + => GetAcceptForActionReturn(action); + + public void PublicAddAcceptHeaders(ActionApiDescriptionModel action, HttpRequestMessage requestMessage, ApiVersionInfo apiVersion) + => AddAcceptHeaders(action, requestMessage, apiVersion); + } +} diff --git a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/Client/ClientProxying/ClientProxyRequestPayloadBuilder_FormData_Tests.cs b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/Client/ClientProxying/ClientProxyRequestPayloadBuilder_FormData_Tests.cs new file mode 100644 index 0000000000..12b453f4f4 --- /dev/null +++ b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/Client/ClientProxying/ClientProxyRequestPayloadBuilder_FormData_Tests.cs @@ -0,0 +1,804 @@ +#nullable enable +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Net.Http; +using System.Text; +using System.Threading.Tasks; +using Microsoft.Extensions.DependencyInjection; +using Shouldly; +using Volo.Abp.Content; +using Volo.Abp.Http.Modeling; +using Volo.Abp.Http.ProxyScripting.Generators; +using Volo.Abp.Json; +using Volo.Abp.Timing; +using Xunit; +using MicrosoftOptions = Microsoft.Extensions.Options.Options; + +namespace Volo.Abp.Http.Client.ClientProxying; + +public class ClientProxyRequestPayloadBuilder_FormData_Tests +{ + private readonly ClientProxyRequestPayloadBuilder _builder; + private readonly IJsonSerializer _jsonSerializer = new StubJsonSerializer(); + private static readonly ApiVersionInfo NoApiVersion = new("Query", "1.0"); + + public ClientProxyRequestPayloadBuilder_FormData_Tests() + { + var services = new ServiceCollection(); + var scopeFactory = services.BuildServiceProvider().GetRequiredService(); + var options = MicrosoftOptions.Create(new AbpHttpClientProxyingOptions()); + _builder = new ClientProxyRequestPayloadBuilder(scopeFactory, options, new TestClock()); + } + + [Fact] + public async Task Direct_IRemoteStreamContent_Param_Should_Produce_Single_StreamContent_Part() + { + var action = BuildAction(parameters: new[] + { + FormFileParam(name: "file", nameOnMethod: "file"), + }); + var stream = MakeStream("hello-direct"); + var args = new Dictionary + { + ["file"] = new RemoteStreamContent(stream, "demo.txt", "text/plain"), + }; + + var content = await InvokeAsync(action, args); + + var multipart = content.ShouldBeOfType(); + var parts = multipart.ToList(); + parts.Count.ShouldBe(1); + parts[0].Headers.ContentType!.MediaType.ShouldBe("text/plain"); + (await parts[0].ReadAsStringAsync()).ShouldBe("hello-direct"); + } + + [Fact] + public async Task Dto_With_IRemoteStreamContent_Property_Should_Flatten_To_Name_Plus_File_Parts() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Name", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestUploadDto + { + Name = "Alice", + File = new RemoteStreamContent(MakeStream("hello-single"), "single.txt", "text/plain"), + }, + }; + + var content = await InvokeAsync(action, args); + + var multipart = content.ShouldBeOfType(); + var parts = multipart.ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Name", "Alice"); + await AssertStreamPart(parts[1], "File", "hello-single", "text/plain"); + } + + [Fact] + public async Task Dto_With_IEnumerable_IRemoteStreamContent_Should_Emit_One_Part_Per_Stream() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Label", nameOnMethod: "input"), + FormFileParam(name: "Files", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestUploadFilesDto + { + Label = "batch", + Files = new[] + { + new RemoteStreamContent(MakeStream("a-content"), "a.txt", "text/plain"), + new RemoteStreamContent(MakeStream("b-content"), "b.txt", "text/csv"), + }, + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(3); + await AssertStringPart(parts[0], "Label", "batch"); + await AssertStreamPart(parts[1], "Files", "a-content", "text/plain"); + await AssertStreamPart(parts[2], "Files", "b-content", "text/csv"); + } + + [Fact] + public async Task Nested_Dto_With_Child_File_Path_Should_Be_Reflected_Via_Dotted_Name() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Outer", nameOnMethod: "input"), + FormFileParam(name: "Child.File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestNestedUploadDto + { + Outer = "outerVal", + Child = new TestNestedChildDto + { + File = new RemoteStreamContent(MakeStream("hello-nested"), "nested.txt", "text/plain"), + }, + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Outer", "outerVal"); + await AssertStreamPart(parts[1], "Child.File", "hello-nested", "text/plain"); + } + + [Fact] + public async Task Form_Only_Action_Without_FormFile_Should_Still_Produce_Multipart_With_String_Parts() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Name", nameOnMethod: "input"), + FormParam(name: "Tag", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestUploadDto { Name = "Alice", Tag = "T1" }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Name", "Alice"); + await AssertStringPart(parts[1], "Tag", "T1"); + } + + [Fact] + public async Task Body_Binding_Wins_Over_Form_And_Returns_Json_StringContent() + { + var action = BuildAction(parameters: new[] + { + new ParameterApiDescriptionModel + { + Name = "input", + NameOnMethod = "input", + Type = typeof(TestUploadDto).FullName!, + TypeSimple = "dto", + BindingSourceId = ParameterBindingSources.Body, + }, + }); + var args = new Dictionary + { + ["input"] = new TestUploadDto { Name = "Alice" }, + }; + + var content = await InvokeAsync(action, args); + + var stringContent = content.ShouldBeOfType(); + stringContent.Headers.ContentType!.MediaType.ShouldBe("application/json"); + var body = await stringContent.ReadAsStringAsync(); + body.ShouldContain("\"Name\":\"Alice\""); + } + + [Fact] + public async Task No_Form_Or_Body_Params_Should_Return_Null_Content() + { + var action = BuildAction(parameters: new[] + { + new ParameterApiDescriptionModel + { + Name = "id", + NameOnMethod = "id", + Type = "System.Int32", + TypeSimple = "int", + BindingSourceId = ParameterBindingSources.Path, + }, + }); + var args = new Dictionary { ["id"] = 42 }; + + var content = await InvokeAsync(action, args); + + content.ShouldBeNull(); + } + + [Fact] + public async Task FormFile_With_Null_Value_Should_Be_Skipped_Not_Throw() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Name", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestUploadDto { Name = "Alice", File = null }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(1); + await AssertStringPart(parts[0], "Name", "Alice"); + } + + [Fact] + public async Task Three_Level_Nested_Dto_Should_Resolve_Outer_Inner_File_Via_Dotted_Path() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Outer", nameOnMethod: "input"), + FormFileParam(name: "Inner.Child.File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestThreeLevelDto + { + Outer = "outerVal", + Inner = new TestThreeLevelMiddleDto + { + Child = new TestNestedChildDto + { + File = new RemoteStreamContent(MakeStream("hello-3-levels"), "deep.txt", "text/plain"), + }, + }, + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Outer", "outerVal"); + await AssertStreamPart(parts[1], "Inner.Child.File", "hello-3-levels", "text/plain"); + } + + [Fact] + public async Task File_With_UTF8_FileName_Should_Survive_To_Content_Disposition_FileName_Star() + { + var action = BuildAction(parameters: new[] + { + FormFileParam(name: "file", nameOnMethod: "file"), + }); + var args = new Dictionary + { + ["file"] = new RemoteStreamContent(MakeStream("hello-utf8"), "中文-文件名.txt", "text/plain"), + }; + + var content = await InvokeAsync(action, args); + + var part = content.ShouldBeOfType().Single(); + var disposition = part.Headers.ContentDisposition; + disposition.ShouldNotBeNull(); + disposition!.FileNameStar.ShouldBe("中文-文件名.txt"); + (await part.ReadAsStringAsync()).ShouldBe("hello-utf8"); + } + + [Fact] + public async Task Dto_Treated_As_Body_When_Not_Registered_Should_Serialize_As_Json_With_File_Field_Embedded() + { + var action = BuildAction(parameters: new[] + { + new ParameterApiDescriptionModel + { + Name = "input", + NameOnMethod = "input", + Type = typeof(TestUploadDto).FullName!, + TypeSimple = "dto", + BindingSourceId = ParameterBindingSources.Body, + }, + }); + var args = new Dictionary + { + ["input"] = new TestUploadDto + { + Name = "Alice", + File = new RemoteStreamContent(MakeStream("ignored"), "x.txt", "text/plain"), + }, + }; + + var content = await InvokeAsync(action, args); + + var stringContent = content.ShouldBeOfType(); + stringContent.Headers.ContentType!.MediaType.ShouldBe("application/json"); + var body = await stringContent.ReadAsStringAsync(); + body.ShouldContain("\"Name\":\"Alice\""); + body.ShouldContain("\"File\""); + } + + [Fact] + public async Task Dto_With_Both_Stream_Property_And_Stream_Collection_Should_Emit_All_Parts() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Label", nameOnMethod: "input"), + FormFileParam(name: "Main", nameOnMethod: "input"), + FormFileParam(name: "Extras", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestMixedUploadDto + { + Label = "combo", + Main = new RemoteStreamContent(MakeStream("main-body"), "main.txt", "text/plain"), + Extras = new[] + { + new RemoteStreamContent(MakeStream("extra-a"), "ea.txt", "text/csv"), + new RemoteStreamContent(MakeStream("extra-b"), "eb.txt", "text/plain"), + }, + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(4); + await AssertStringPart(parts[0], "Label", "combo"); + await AssertStreamPart(parts[1], "Main", "main-body", "text/plain"); + await AssertStreamPart(parts[2], "Extras", "extra-a", "text/csv"); + await AssertStreamPart(parts[3], "Extras", "extra-b", "text/plain"); + } + + [Fact] + public async Task Two_Different_Upload_Actions_On_Same_Builder_Should_Not_Pollute_Each_Other() + { + var actionA = BuildAction(parameters: new[] + { + FormParam(name: "Name", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var actionB = BuildAction(parameters: new[] + { + FormParam(name: "Label", nameOnMethod: "input"), + FormFileParam(name: "Files", nameOnMethod: "input"), + }); + + var argsA = new Dictionary + { + ["input"] = new TestUploadDto { Name = "A", File = new RemoteStreamContent(MakeStream("aa"), "a.txt", "text/plain") }, + }; + var argsB = new Dictionary + { + ["input"] = new TestUploadFilesDto + { + Label = "B", + Files = new[] { new RemoteStreamContent(MakeStream("bb"), "b.txt", "text/csv") }, + }, + }; + + var contentA = (await InvokeAsync(actionA, argsA)).ShouldBeOfType().ToList(); + var contentB = (await InvokeAsync(actionB, argsB)).ShouldBeOfType().ToList(); + + await AssertStringPart(contentA[0], "Name", "A"); + await AssertStreamPart(contentA[1], "File", "aa", "text/plain"); + await AssertStringPart(contentB[0], "Label", "B"); + await AssertStreamPart(contentB[1], "Files", "bb", "text/csv"); + } + + [Fact] + public async Task Inherited_Dto_With_File_Property_On_Base_Class_Should_Resolve_Via_Reflection() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Name", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + FormParam(name: "ChildOnly", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestInheritedUploadDto + { + Name = "inherited", + File = new RemoteStreamContent(MakeStream("from-base"), "base.txt", "text/plain"), + ChildOnly = "extra", + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(3); + await AssertStringPart(parts[0], "Name", "inherited"); + await AssertStreamPart(parts[1], "File", "from-base", "text/plain"); + await AssertStringPart(parts[2], "ChildOnly", "extra"); + } + + [Fact] + public async Task Record_Dto_With_File_Property_Should_Resolve_Via_Reflection() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Name", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestRecordUploadDto( + Name: "Diana", + File: new RemoteStreamContent(MakeStream("from-record"), "r.txt", "text/plain")), + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Name", "Diana"); + await AssertStreamPart(parts[1], "File", "from-record", "text/plain"); + } + + [Fact] + public async Task Dto_With_DateTime_Enum_And_Nullable_Struct_Fields_Should_Round_Trip_As_String_Parts() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "When", nameOnMethod: "input"), + FormParam(name: "Status", nameOnMethod: "input"), + FormParam(name: "Quantity", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestPrimitiveUploadDto + { + When = new DateTime(2025, 6, 1, 12, 34, 56, DateTimeKind.Utc), + Status = TestStatus.Active, + Quantity = 7, + File = new RemoteStreamContent(MakeStream("primitives"), "p.txt", "text/plain"), + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(4); + (await parts[0].ReadAsStringAsync()).ShouldStartWith("2025-06-01T12:34:56"); + (await parts[1].ReadAsStringAsync()).ShouldBe("Active"); + (await parts[2].ReadAsStringAsync()).ShouldBe("7"); + await AssertStreamPart(parts[3], "File", "primitives", "text/plain"); + } + + [Fact] + public async Task Dto_With_Nullable_Struct_Field_Set_To_Null_Should_Skip_The_Part_Entirely() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Quantity", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestPrimitiveUploadDto + { + Quantity = null, + File = new RemoteStreamContent(MakeStream("null-qty"), "n.txt", "text/plain"), + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(1); + await AssertStreamPart(parts[0], "File", "null-qty", "text/plain"); + } + + [Fact] + public async Task Polymorphic_Dto_With_Derived_Type_Should_Reflect_Properties_From_Concrete_Runtime_Type() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Name", nameOnMethod: "input"), + FormParam(name: "ExtraField", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + TestUploadDtoBase polymorphic = new TestPolymorphicDerivedDto + { + Name = "poly", + ExtraField = "derived-only", + File = new RemoteStreamContent(MakeStream("from-derived"), "d.txt", "text/plain"), + }; + var args = new Dictionary { ["input"] = polymorphic }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(3); + await AssertStringPart(parts[0], "Name", "poly"); + await AssertStringPart(parts[1], "ExtraField", "derived-only"); + await AssertStreamPart(parts[2], "File", "from-derived", "text/plain"); + } + + [Fact] + public async Task Generic_Dto_Closed_Over_Concrete_Type_Should_Reflect_Open_Generic_Property() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Payload", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestGenericUploadDto + { + Payload = "closed-string", + File = new RemoteStreamContent(MakeStream("g.txt-body"), "g.txt", "text/plain"), + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Payload", "closed-string"); + await AssertStreamPart(parts[1], "File", "g.txt-body", "text/plain"); + } + + [Fact] + public async Task Generic_Dto_With_Integer_Payload_Should_Convert_Via_ConvertValueToString() + { + var action = BuildAction(parameters: new[] + { + FormParam(name: "Payload", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["input"] = new TestGenericUploadDto + { + Payload = 42, + File = new RemoteStreamContent(MakeStream("int-payload"), "i.txt", "text/plain"), + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Payload", "42"); + } + + [Fact] + public async Task Underlying_Caller_Stream_Is_Wrapped_Without_Buffering_So_Retry_Sees_Drained_Source() + { + // Pin pass-through behaviour: HttpClient retry that re-reads `sourceStream` + // observes an empty body (no internal buffering). Opting in to buffering + // later would double-allocate for large uploads. + var action = BuildAction(parameters: new[] + { + FormFileParam(name: "file", nameOnMethod: "file"), + }); + var sourceStream = MakeStream("retry-payload"); + var args = new Dictionary + { + ["file"] = new RemoteStreamContent(sourceStream, "r.txt", "text/plain"), + }; + + var content = await InvokeAsync(action, args); + + var part = content.ShouldBeOfType().Single(); + sourceStream.Position.ShouldBe(0); + + (await part.ReadAsStringAsync()).ShouldBe("retry-payload"); + + sourceStream.Position.ShouldBe(sourceStream.Length); + } + + [Fact] + public async Task Action_With_No_Parameters_Should_Return_Null_Content_Without_Throwing() + { + var action = BuildAction(parameters: Array.Empty()); + var args = new Dictionary(); + + var content = await InvokeAsync(action, args); + + content.ShouldBeNull(); + } + + [Fact] + public async Task Path_Plus_Form_Plus_FormFile_Should_Skip_Path_And_Emit_Multipart_Only() + { + var action = BuildAction(parameters: new[] + { + new ParameterApiDescriptionModel + { + Name = "id", + NameOnMethod = "id", + Type = "System.Int32", + TypeSimple = "int", + BindingSourceId = ParameterBindingSources.Path, + }, + FormParam(name: "Name", nameOnMethod: "input"), + FormFileParam(name: "File", nameOnMethod: "input"), + }); + var args = new Dictionary + { + ["id"] = 7, + ["input"] = new TestUploadDto + { + Name = "Bob", + File = new RemoteStreamContent(MakeStream("path-mixed"), "p.txt", "text/plain"), + }, + }; + + var content = await InvokeAsync(action, args); + + var parts = content.ShouldBeOfType().ToList(); + parts.Count.ShouldBe(2); + await AssertStringPart(parts[0], "Name", "Bob"); + await AssertStreamPart(parts[1], "File", "path-mixed", "text/plain"); + } + + private Task InvokeAsync(ActionApiDescriptionModel action, IReadOnlyDictionary args) + => _builder.BuildContentAsync(action, args, _jsonSerializer, NoApiVersion); + + private static ActionApiDescriptionModel BuildAction(ParameterApiDescriptionModel[] parameters) + => new() + { + UniqueName = "TestAction", + Name = "TestAction", + HttpMethod = "POST", + Url = "api/test", + SupportedVersions = new List(), + ParametersOnMethod = new List(), + Parameters = parameters.ToList(), + ReturnValue = new ReturnValueApiDescriptionModel + { + Type = "System.String", + TypeSimple = "string", + }, + AuthorizeDatas = new List(), + }; + + private static ParameterApiDescriptionModel FormParam(string name, string nameOnMethod) + => new() + { + Name = name, + NameOnMethod = nameOnMethod, + Type = "System.String", + TypeSimple = "string", + BindingSourceId = ParameterBindingSources.Form, + }; + + private static ParameterApiDescriptionModel FormFileParam(string name, string nameOnMethod) + => new() + { + Name = name, + NameOnMethod = nameOnMethod, + Type = typeof(IRemoteStreamContent).FullName!, + TypeSimple = "stream", + BindingSourceId = ParameterBindingSources.FormFile, + }; + + private static MemoryStream MakeStream(string text) + { + var ms = new MemoryStream(); + ms.Write(Encoding.UTF8.GetBytes(text)); + ms.Position = 0; + return ms; + } + + private static async Task AssertStringPart(HttpContent part, string expectedName, string expectedValue) + { + var disposition = part.Headers.ContentDisposition; + disposition.ShouldNotBeNull(); + disposition!.Name!.Trim('"').ShouldBe(expectedName); + (await part.ReadAsStringAsync()).ShouldBe(expectedValue); + } + + private static async Task AssertStreamPart(HttpContent part, string expectedName, string expectedBody, string expectedContentType) + { + var disposition = part.Headers.ContentDisposition; + disposition.ShouldNotBeNull(); + disposition!.Name!.Trim('"').ShouldBe(expectedName); + part.Headers.ContentType!.MediaType.ShouldBe(expectedContentType); + (await part.ReadAsStringAsync()).ShouldBe(expectedBody); + } + + private class TestUploadDto + { + public string? Name { get; set; } + public string? Tag { get; set; } + public IRemoteStreamContent? File { get; set; } + } + + private class TestUploadFilesDto + { + public string? Label { get; set; } + public IEnumerable? Files { get; set; } + } + + private class TestNestedUploadDto + { + public string? Outer { get; set; } + public TestNestedChildDto? Child { get; set; } + } + + private class TestNestedChildDto + { + public IRemoteStreamContent? File { get; set; } + } + + private class TestThreeLevelDto + { + public string? Outer { get; set; } + public TestThreeLevelMiddleDto? Inner { get; set; } + } + + private class TestThreeLevelMiddleDto + { + public TestNestedChildDto? Child { get; set; } + } + + private class TestMixedUploadDto + { + public string? Label { get; set; } + public IRemoteStreamContent? Main { get; set; } + public IEnumerable? Extras { get; set; } + } + + private class TestUploadDtoBase + { + public string? Name { get; set; } + public IRemoteStreamContent? File { get; set; } + } + + private class TestInheritedUploadDto : TestUploadDtoBase + { + public string? ChildOnly { get; set; } + } + + private record TestRecordUploadDto(string Name, IRemoteStreamContent File); + + private class TestPrimitiveUploadDto + { + public DateTime When { get; set; } + public TestStatus Status { get; set; } + public int? Quantity { get; set; } + public IRemoteStreamContent? File { get; set; } + } + + private enum TestStatus + { + Pending = 0, + Active = 1, + Done = 2, + } + + private class TestPolymorphicDerivedDto : TestUploadDtoBase + { + public string? ExtraField { get; set; } + } + + private class TestGenericUploadDto + { + public T? Payload { get; set; } + public IRemoteStreamContent? File { get; set; } + } + + private class StubJsonSerializer : IJsonSerializer + { + public string Serialize(object obj, bool camelCase = true, bool indented = false) + => System.Text.Json.JsonSerializer.Serialize(obj); + + public T Deserialize(string jsonString, bool camelCase = true) + => System.Text.Json.JsonSerializer.Deserialize(jsonString)!; + + public object Deserialize(Type type, string jsonString, bool camelCase = true) + => System.Text.Json.JsonSerializer.Deserialize(jsonString, type)!; + } + + private class TestClock : IClock + { + public DateTime Now => DateTime.UtcNow; + public DateTimeKind Kind => DateTimeKind.Utc; + public bool SupportsMultipleTimezone => false; + public DateTime Normalize(DateTime dateTime) => dateTime; + public DateTime ConvertToUserTime(DateTime utcDateTime) => utcDateTime; + public DateTimeOffset ConvertToUserTime(DateTimeOffset dateTimeOffset) => dateTimeOffset; + public DateTime ConvertToUtc(DateTime dateTime) => dateTime; + } +} diff --git a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/IRegularTestController.cs b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/IRegularTestController.cs index 21786155bf..fdf279e1ce 100644 --- a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/IRegularTestController.cs +++ b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/IRegularTestController.cs @@ -1,6 +1,7 @@ using System; using System.Threading; using System.Threading.Tasks; +using Volo.Abp.Content; namespace Volo.Abp.Http.DynamicProxying; @@ -8,6 +9,26 @@ public interface IRegularTestController { Task IncrementValueAsync(int value); + Task GetPlainStringAsync(); + + Task GetProducesJsonStringAsync(); + + Task GetProducesTextStringAsync(); + + Task GetNullStringAsync(); + + Task GetProducesJsonNullStringAsync(); + + Task GetEmptyStringAsync(); + + Task GetEscapedStringAsync(); + + Task DownloadIconAsync(); + + Task GetReferenceTypeObjectAsync(); + + Task GetByteArrayAsync(); + Task GetException1Async(); Task GetException2Async(); diff --git a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/PeopleAppServiceClientProxy_ReturnContentTypes_Tests.cs b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/PeopleAppServiceClientProxy_ReturnContentTypes_Tests.cs new file mode 100644 index 0000000000..b89692eb90 --- /dev/null +++ b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/PeopleAppServiceClientProxy_ReturnContentTypes_Tests.cs @@ -0,0 +1,84 @@ +using System.IO; +using System.Threading.Tasks; +using Microsoft.Extensions.DependencyInjection; +using Shouldly; +using Volo.Abp.Http.Client; +using Volo.Abp.TestApp.Application; +using Xunit; + +namespace Volo.Abp.Http.DynamicProxying; + +public class PeopleAppServiceClientProxy_ReturnContentTypes_Tests : AbpHttpClientTestBase +{ + private readonly IPeopleAppService _peopleAppService; + + public PeopleAppServiceClientProxy_ReturnContentTypes_Tests() + { + _peopleAppService = ServiceProvider.GetRequiredService(); + } + + [Fact] + public async Task EchoStatusAsync_Should_Return_Plain_String_Without_Quotes() + { + var status = await _peopleAppService.EchoStatusAsync(); + status.ShouldBe("Open"); + status.StartsWith("\"").ShouldBeFalse(); + status.EndsWith("\"").ShouldBeFalse(); + } + + [Fact] + public async Task EchoStatusWithProducesJsonAsync_Should_Return_Plain_String_Without_Quotes() + { + var status = await _peopleAppService.EchoStatusWithProducesJsonAsync(); + status.ShouldBe("Open"); + status.StartsWith("\"").ShouldBeFalse(); + status.EndsWith("\"").ShouldBeFalse(); + } + + [Fact] + public async Task GetBinaryImageAsync_Should_Return_Real_Binary_Not_Json_Metadata() + { + using var content = await _peopleAppService.GetBinaryImageAsync(); + using var ms = new MemoryStream(); + await content.GetStream().CopyToAsync(ms); + var bytes = ms.ToArray(); + + content.FileName.ShouldBe("tiny.png"); + content.ContentType.ShouldStartWith("image/png"); + bytes.Length.ShouldBeGreaterThan(8); + + bytes[0].ShouldBe((byte)0x89); + bytes[1].ShouldBe((byte)0x50); + bytes[2].ShouldBe((byte)0x4E); + bytes[3].ShouldBe((byte)0x47); + } + + [Fact] + public async Task ThrowFromStringAsync_Should_Surface_Server_Exception_To_Client() + { + await Should.ThrowAsync( + () => _peopleAppService.ThrowFromStringAsync() + ); + } + + [Fact] + public async Task DownloadAsync_Should_Still_Work() + { + using var content = await _peopleAppService.DownloadAsync(); + using var reader = new StreamReader(content.GetStream()); + var text = await reader.ReadToEndAsync(); + text.ShouldBe("DownloadAsync"); + content.FileName.ShouldBe("download.rtf"); + content.ContentType.ShouldStartWith("application/rtf"); + } + + [Fact] + public async Task UploadAsync_String_Return_Should_Stay_Unquoted() + { + using var ms = new MemoryStream(System.Text.Encoding.UTF8.GetBytes("hello")); + var result = await _peopleAppService.UploadAsync( + new Content.RemoteStreamContent(ms, "upload.txt", "text/plain")); + result.ShouldBe("hello:text/plain:upload.txt"); + result.StartsWith("\"").ShouldBeFalse(); + } +} diff --git a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/RegularTestController.cs b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/RegularTestController.cs index 46b355090b..1d0864991b 100644 --- a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/RegularTestController.cs +++ b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/RegularTestController.cs @@ -1,10 +1,13 @@ using System; using System.Collections.Generic; using System.Globalization; +using System.IO; +using System.Text; using System.Threading; using System.Threading.Tasks; using Microsoft.AspNetCore.Mvc; using Volo.Abp.AspNetCore.Mvc; +using Volo.Abp.Content; namespace Volo.Abp.Http.DynamicProxying; @@ -20,6 +23,82 @@ public class RegularTestController : AbpController, IRegularTestController return Task.FromResult(value + 1); } + [HttpGet] + [Route("plain-string")] + public Task GetPlainStringAsync() + { + return Task.FromResult("Open"); + } + + [HttpGet] + [Route("produces-json-string")] + [Produces("application/json")] + public Task GetProducesJsonStringAsync() + { + return Task.FromResult("Open"); + } + + [HttpGet] + [Route("produces-text-string")] + [Produces("text/plain")] + public Task GetProducesTextStringAsync() + { + return Task.FromResult("Open"); + } + + [HttpGet] + [Route("null-string")] + public Task GetNullStringAsync() + { + return Task.FromResult(null!); + } + + [HttpGet] + [Route("produces-json-null-string")] + [Produces("application/json")] + public Task GetProducesJsonNullStringAsync() + { + return Task.FromResult(null!); + } + + [HttpGet] + [Route("empty-string")] + public Task GetEmptyStringAsync() + { + return Task.FromResult(string.Empty); + } + + [HttpGet] + [Route("escaped-string")] + [Produces("application/json")] + public Task GetEscapedStringAsync() + { + return Task.FromResult("a\"b\\c\nd"); + } + + [HttpGet] + [Route("download-icon")] + public Task DownloadIconAsync() + { + var bytes = Encoding.UTF8.GetBytes("ICON-BYTES"); + return Task.FromResult( + new RemoteStreamContent(new MemoryStream(bytes), "icon.bin", "application/octet-stream")); + } + + [HttpGet] + [Route("reference-type-object")] + public Task GetReferenceTypeObjectAsync() + { + return Task.FromResult(new Car { Year = 1999, Model = "BMW" }); + } + + [HttpGet] + [Route("byte-array")] + public Task GetByteArrayAsync() + { + return Task.FromResult(new byte[] { 1, 2, 3, 4 }); + } + [HttpGet] [Route("get-exception1")] public Task GetException1Async() diff --git a/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/RegularTestControllerClientProxy_ReturnContentTypes_Tests.cs b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/RegularTestControllerClientProxy_ReturnContentTypes_Tests.cs new file mode 100644 index 0000000000..92c8b5b23c --- /dev/null +++ b/framework/test/Volo.Abp.Http.Client.Tests/Volo/Abp/Http/DynamicProxying/RegularTestControllerClientProxy_ReturnContentTypes_Tests.cs @@ -0,0 +1,103 @@ +using System.IO; +using System.Threading.Tasks; +using Microsoft.Extensions.DependencyInjection; +using Shouldly; +using Xunit; + +namespace Volo.Abp.Http.DynamicProxying; + +public class RegularTestControllerClientProxy_ReturnContentTypes_Tests : AbpHttpClientTestBase +{ + private readonly IRegularTestController _controller; + + public RegularTestControllerClientProxy_ReturnContentTypes_Tests() + { + _controller = ServiceProvider.GetRequiredService(); + } + + [Fact] + public async Task GetPlainStringAsync_Should_Return_Unwrapped_String() + { + var result = await _controller.GetPlainStringAsync(); + result.ShouldBe("Open"); + result.StartsWith("\"").ShouldBeFalse(); + } + + [Fact] + public async Task GetProducesJsonStringAsync_Should_Strip_Json_Quotes() + { + var result = await _controller.GetProducesJsonStringAsync(); + result.ShouldBe("Open"); + result.StartsWith("\"").ShouldBeFalse(); + result.EndsWith("\"").ShouldBeFalse(); + } + + [Fact] + public async Task GetProducesTextStringAsync_Should_Return_Raw_Text_Body() + { + var result = await _controller.GetProducesTextStringAsync(); + result.ShouldBe("Open"); + result.StartsWith("\"").ShouldBeFalse(); + } + + [Fact] + public async Task GetNullStringAsync_Should_Return_Default_Or_Empty() + { + var result = await _controller.GetNullStringAsync(); + (result == null || result == string.Empty).ShouldBeTrue(); + } + + [Fact] + public async Task GetEmptyStringAsync_Should_Return_Empty() + { + var result = await _controller.GetEmptyStringAsync(); + (result == null || result == string.Empty).ShouldBeTrue(); + } + + [Fact] + public async Task GetProducesJsonNullStringAsync_Should_Not_Return_Literal_Null() + { + var result = await _controller.GetProducesJsonNullStringAsync(); + result.ShouldNotBe("null"); + (result == null || result == string.Empty).ShouldBeTrue(); + } + + [Fact] + public async Task GetEscapedStringAsync_Should_Decode_Escaped_Characters() + { + var result = await _controller.GetEscapedStringAsync(); + result.ShouldBe("a\"b\\c\nd"); + } + + [Fact] + public async Task DownloadIconAsync_Should_Return_Binary_Bytes() + { + using var content = await _controller.DownloadIconAsync(); + using var ms = new MemoryStream(); + await content.GetStream().CopyToAsync(ms); + ms.ToArray().ShouldBe(System.Text.Encoding.UTF8.GetBytes("ICON-BYTES")); + content.FileName.ShouldBe("icon.bin"); + } + + [Fact] + public async Task GetReferenceTypeObjectAsync_Should_Not_Be_Wrapped_As_RemoteStreamContent() + { + var result = await _controller.GetReferenceTypeObjectAsync(); + result.ShouldNotBeNull(); + result.ShouldNotBeAssignableTo(); + } + + [Fact] + public async Task GetByteArrayAsync_Should_Round_Trip_Bytes() + { + var bytes = await _controller.GetByteArrayAsync(); + bytes.ShouldBe(new byte[] { 1, 2, 3, 4 }); + } + + [Fact] + public async Task Existing_IncrementValueAsync_Regression_Should_Still_Work() + { + var result = await _controller.IncrementValueAsync(41); + result.ShouldBe(42); + } +} diff --git a/framework/test/Volo.Abp.Http.Tests/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel_Tests.cs b/framework/test/Volo.Abp.Http.Tests/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel_Tests.cs new file mode 100644 index 0000000000..d3c3197937 --- /dev/null +++ b/framework/test/Volo.Abp.Http.Tests/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel_Tests.cs @@ -0,0 +1,279 @@ +using System.Collections.Generic; +using System.IO; +using System.Threading.Tasks; +using Shouldly; +using Volo.Abp.Content; +using Volo.Abp.Http.Modeling; +using Xunit; + +namespace Volo.Abp.Http.Modeling; + +public class ReturnValueApiDescriptionModel_Tests +{ + [Fact] + public void Create_Without_ContentTypes_Should_Leave_Property_Null() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(string)); + + model.ShouldNotBeNull(); + model.TypeSimple.ShouldBe("string"); + model.ContentTypes.ShouldBeNull(); + } + + [Fact] + public void Create_With_ContentTypes_Should_Populate_The_Property() + { + var model = ReturnValueApiDescriptionModel.Create( + typeof(string), + new[] { "application/json", "text/plain" }); + + model.ContentTypes.ShouldNotBeNull(); + model.ContentTypes!.ShouldBe(new[] { "application/json", "text/plain" }); + } +} + +public class ReturnValueApiDescriptionModel_IsRemoteStream_Tests +{ + [Fact] + public void Direct_IRemoteStreamContent_Should_Be_True() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(IRemoteStreamContent)); + model.IsRemoteStream.ShouldBeTrue(); + } + + [Fact] + public void Concrete_RemoteStreamContent_Should_Be_True() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(RemoteStreamContent)); + model.IsRemoteStream.ShouldBeTrue(); + } + + [Fact] + public void Custom_Subclass_Of_IRemoteStreamContent_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(MyCustomStreamContent)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Task_Of_IRemoteStreamContent_Should_Be_True_After_UnwrapTask() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(Task)); + model.IsRemoteStream.ShouldBeTrue(); + } + + [Fact] + public void Task_Of_Custom_Stream_Subclass_Should_Be_False_After_UnwrapTask() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(Task)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void IRemoteStreamContent_Array_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(IRemoteStreamContent[])); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Concrete_RemoteStreamContent_Array_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(RemoteStreamContent[])); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void List_Of_IRemoteStreamContent_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(List)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void IEnumerable_Of_IRemoteStreamContent_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(IEnumerable)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void IReadOnlyCollection_Of_IRemoteStreamContent_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(IReadOnlyCollection)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Plain_String_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(string)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Int_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(int)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Plain_Dto_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(PlainDto)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Dto_Containing_IRemoteStreamContent_Property_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(DtoWithStream)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Dto_Inheriting_From_Type_With_Stream_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(DtoInheritingStream)); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Byte_Array_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(byte[])); + model.IsRemoteStream.ShouldBeFalse(); + } + + [Fact] + public void Dictionary_Should_Be_False() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(Dictionary)); + model.IsRemoteStream.ShouldBeFalse(); + } + + private class MyCustomStreamContent : IRemoteStreamContent + { + public string? FileName => null; + public string? ContentType => null; + public long? ContentLength => null; + public Stream GetStream() => Stream.Null; + public void Dispose() { } + } + + private class PlainDto + { + public int Id { get; set; } + public string Name { get; set; } = string.Empty; + } + + private class DtoWithStream + { + public string FileName { get; set; } = string.Empty; + public IRemoteStreamContent? File { get; set; } + } + + private class DtoInheritingStream : PlainDto + { + public IRemoteStreamContent? Stream { get; set; } + } +} + +public class ReturnValueApiDescriptionModel_BackwardsCompat_Tests +{ + [Fact] + public void Deserializing_Json_Without_ContentTypes_Field_Should_Leave_It_Null() + { + var json = """ + { + "type": "System.String", + "typeSimple": "string" + } + """; + + var model = System.Text.Json.JsonSerializer.Deserialize( + json, + new System.Text.Json.JsonSerializerOptions + { + PropertyNameCaseInsensitive = true + }); + + model.ShouldNotBeNull(); + model!.Type.ShouldBe("System.String"); + model.TypeSimple.ShouldBe("string"); + model.ContentTypes.ShouldBeNull(); + } + + [Fact] + public void Deserializing_Json_With_ContentTypes_Field_Should_Populate_It() + { + var json = """ + { + "type": "System.String", + "typeSimple": "string", + "contentTypes": ["application/json", "text/plain"] + } + """; + + var model = System.Text.Json.JsonSerializer.Deserialize( + json, + new System.Text.Json.JsonSerializerOptions + { + PropertyNameCaseInsensitive = true + }); + + model!.ContentTypes.ShouldNotBeNull(); + model.ContentTypes!.ShouldBe(new[] { "application/json", "text/plain" }); + } + + [Fact] + public void Serializing_With_Null_ContentTypes_Should_Emit_Null_Or_Omit() + { + var model = ReturnValueApiDescriptionModel.Create(typeof(string)); + var json = System.Text.Json.JsonSerializer.Serialize(model); + + var deserialized = System.Text.Json.JsonSerializer.Deserialize( + json, + new System.Text.Json.JsonSerializerOptions { PropertyNameCaseInsensitive = true }); + deserialized!.ContentTypes.ShouldBeNull(); + } +} + +public class ActionApiDescriptionModel_Tests +{ + [Fact] + public void Create_Should_Propagate_ReturnValueContentTypes() + { + var method = typeof(ActionApiDescriptionModel_Tests).GetMethod(nameof(SampleMethod))!; + var model = ActionApiDescriptionModel.Create( + uniqueName: "SampleMethod", + method: method, + url: "api/test/sample", + httpMethod: "GET", + supportedVersions: new[] { "1.0" }, + allowAnonymous: true, + authorizeDatas: null, + implementFrom: null, + returnValueContentTypes: new[] { "application/octet-stream" }); + + model.ReturnValue.ContentTypes.ShouldNotBeNull(); + model.ReturnValue.ContentTypes!.ShouldBe(new[] { "application/octet-stream" }); + } + + [Fact] + public void Create_Without_ReturnValueContentTypes_Should_Leave_Null() + { + var method = typeof(ActionApiDescriptionModel_Tests).GetMethod(nameof(SampleMethod))!; + var model = ActionApiDescriptionModel.Create( + uniqueName: "SampleMethod", + method: method, + url: "api/test/sample", + httpMethod: "GET", + supportedVersions: new[] { "1.0" }); + + model.ReturnValue.ContentTypes.ShouldBeNull(); + } + + public string SampleMethod() => string.Empty; +} diff --git a/framework/test/Volo.Abp.Http.Tests/Volo/Abp/Http/ProxyScripting/Generators/JQuery/JQueryProxyScriptGenerator_ContentTypes_Tests.cs b/framework/test/Volo.Abp.Http.Tests/Volo/Abp/Http/ProxyScripting/Generators/JQuery/JQueryProxyScriptGenerator_ContentTypes_Tests.cs new file mode 100644 index 0000000000..a7c63f8270 --- /dev/null +++ b/framework/test/Volo.Abp.Http.Tests/Volo/Abp/Http/ProxyScripting/Generators/JQuery/JQueryProxyScriptGenerator_ContentTypes_Tests.cs @@ -0,0 +1,266 @@ +#nullable enable +using System.Collections.Generic; +using Microsoft.Extensions.Options; +using Shouldly; +using Volo.Abp.Http.Modeling; +using Volo.Abp.Http.ProxyScripting.Generators; +using Volo.Abp.Http.ProxyScripting.Generators.JQuery; +using Xunit; + +namespace Volo.Abp.Http.ProxyScripting.Generators.JQuery; + +public class JQueryProxyScriptGenerator_ContentTypes_Tests +{ + private readonly JQueryProxyScriptGenerator _generator = new( + Microsoft.Extensions.Options.Options.Create(new DynamicJavaScriptProxyOptions())); + + [Fact] + public void Should_Emit_Json_DataType_And_Accept_When_ContentTypes_Contain_Json() + { + var script = _generator.CreateScript(BuildAppModel( + returnType: "System.String", + contentTypes: new[] { "text/plain", "application/json", "text/json" })); + + script.ShouldContain("dataType: 'json'"); + script.ShouldContain("Accept: 'application/json'"); + script.ShouldNotContain("dataType: 'text'"); + } + + [Fact] + public void Should_Emit_Text_DataType_And_Accept_When_ContentTypes_Only_Text() + { + var script = _generator.CreateScript(BuildAppModel( + returnType: "System.String", + contentTypes: new[] { "text/plain", "text/csv" })); + + script.ShouldContain("dataType: 'text'"); + script.ShouldContain("Accept: 'text/plain'"); + } + + [Fact] + public void Should_Fallback_To_Legacy_Text_When_Return_Is_String_And_ContentTypes_Null() + { + var script = _generator.CreateScript(BuildAppModel( + returnType: "System.String", + contentTypes: null)); + + // Legacy behavior preserved: string return → dataType: 'text' (no Accept override) + script.ShouldContain("dataType: 'text'"); + script.ShouldNotContain("Accept:"); + } + + [Fact] + public void Should_Emit_No_DataType_For_Non_String_Return_Without_ContentTypes() + { + var script = _generator.CreateScript(BuildAppModel( + returnType: "System.Int32", + contentTypes: null)); + + script.ShouldNotContain("dataType: 'text'"); + script.ShouldNotContain("dataType: 'json'"); + } + + [Fact] + public void Should_Not_Emit_Json_DataType_When_Only_Binary_ContentTypes() + { + var script = _generator.CreateScript(BuildAppModel( + returnType: "System.Byte[]", + contentTypes: new[] { "application/octet-stream", "image/png" })); + + // jQuery dataType doesn't have a clean "blob" — fall through to no override + script.ShouldNotContain("dataType: 'json'"); + script.ShouldNotContain("dataType: 'text'"); + } + + [Fact] + public void Should_Prefer_Json_When_Json_Present_Even_With_Other_Types() + { + var script = _generator.CreateScript(BuildAppModel( + returnType: "My.Project.UserDto", + contentTypes: new[] { "application/xml", "application/json", "text/html" })); + + script.ShouldContain("dataType: 'json'"); + script.ShouldContain("Accept: 'application/json'"); + } + + [Fact] + public void Case_Insensitive_Json_Detection() + { + var script = _generator.CreateScript(BuildAppModel( + returnType: "System.String", + contentTypes: new[] { "APPLICATION/JSON" })); + + script.ShouldContain("dataType: 'json'"); + } + + [Fact] + public void IsRemoteStream_Should_Skip_DataType_Override_To_Avoid_JSON_Metadata_Regression() + { + // IRemoteStreamContent: ABP advertises application/json in formatter list, but + // forcing dataType:'json' here would make the server JSON-serialise the stream. + var model = BuildAppModel( + returnType: "Volo.Abp.Content.IRemoteStreamContent", + contentTypes: new[] { "text/plain", "application/json", "text/json" }, + isRemoteStream: true); + + var script = _generator.CreateScript(model); + + script.ShouldNotContain("dataType: 'json'"); + script.ShouldNotContain("Accept: 'application/json'"); + } + + [Fact] + public void Multipart_Upload_Should_Emit_FormData_Body_With_ProcessData_And_ContentType_False() + { + var script = _generator.CreateScript(BuildUploadModel( + uploadParameters: new[] + { + ("Name", "input", ParameterBindingSources.Form), + ("File", "input", ParameterBindingSources.FormFile), + })); + + script.ShouldContain("data: input"); + script.ShouldContain("processData: false"); + script.ShouldContain("contentType: false"); + script.ShouldNotContain("contentType: 'application/x-www-form-urlencoded"); + } + + [Fact] + public void Multipart_Upload_Should_Use_NameOnMethod_As_Data_Variable() + { + var script = _generator.CreateScript(BuildUploadModel( + uploadParameters: new[] + { + ("file", "file", ParameterBindingSources.FormFile), + })); + + script.ShouldContain("data: file"); + script.ShouldContain("processData: false"); + script.ShouldContain("contentType: false"); + } + + [Fact] + public void Plain_Form_Action_Without_FormFile_Should_Still_Emit_UrlEncoded_ContentType() + { + var script = _generator.CreateScript(BuildUploadModel( + uploadParameters: new[] + { + ("Name", "input", ParameterBindingSources.Form), + })); + + script.ShouldContain("contentType: 'application/x-www-form-urlencoded; charset=UTF-8'"); + script.ShouldNotContain("processData: false"); + script.ShouldNotContain("contentType: false"); + } + + [Fact] + public void Multipart_Upload_Should_Skip_FormPostData_And_Body_Generation() + { + var script = _generator.CreateScript(BuildUploadModel( + uploadParameters: new[] + { + ("Name", "input", ParameterBindingSources.Form), + ("File", "input", ParameterBindingSources.FormFile), + })); + + script.ShouldNotContain("'Name=' + "); + script.ShouldNotContain("JSON.stringify"); + } + + [Fact] + public void Multiple_Direct_FormFile_Params_Should_Forward_Only_First_Var_Known_Limitation() + { + var script = _generator.CreateScript(BuildUploadModel( + uploadParameters: new[] + { + ("file1", "file1", ParameterBindingSources.FormFile), + ("file2", "file2", ParameterBindingSources.FormFile), + })); + + script.ShouldContain("data: file1"); + script.ShouldNotContain("data: file2"); + script.ShouldNotContain("$.merge(file1, file2)"); + } + + private static ApplicationApiDescriptionModel BuildAppModel(string returnType, IList? contentTypes, bool isRemoteStream = false) + { + var model = ApplicationApiDescriptionModel.Create(); + var module = model.GetOrAddModule("app", "Default"); + var controller = module.GetOrAddController( + name: "TestController", + groupName: null, + isRemoteService: true, + isIntegrationService: false, + apiVersion: null, + type: typeof(object)); + + var action = new ActionApiDescriptionModel + { + UniqueName = "DoSomethingAsync", + Name = "DoSomethingAsync", + HttpMethod = "GET", + Url = "api/test/do-something", + SupportedVersions = new List(), + ParametersOnMethod = new List(), + Parameters = new List(), + ReturnValue = new ReturnValueApiDescriptionModel + { + Type = returnType, + TypeSimple = returnType, + ContentTypes = contentTypes, + IsRemoteStream = isRemoteStream, + }, + AuthorizeDatas = new List(), + }; + controller.AddAction("DoSomethingAsync", action); + + return model; + } + + private static ApplicationApiDescriptionModel BuildUploadModel( + (string Name, string NameOnMethod, string BindingSourceId)[] uploadParameters) + { + var model = ApplicationApiDescriptionModel.Create(); + var module = model.GetOrAddModule("app", "Default"); + var controller = module.GetOrAddController( + name: "TestController", + groupName: null, + isRemoteService: true, + isIntegrationService: false, + apiVersion: null, + type: typeof(object)); + + var parameters = new List(); + foreach (var (name, nameOnMethod, binding) in uploadParameters) + { + parameters.Add(new ParameterApiDescriptionModel + { + Name = name, + NameOnMethod = nameOnMethod, + Type = "System.String", + TypeSimple = "string", + BindingSourceId = binding, + }); + } + + var action = new ActionApiDescriptionModel + { + UniqueName = "UploadAsync", + Name = "UploadAsync", + HttpMethod = "POST", + Url = "api/test/upload", + SupportedVersions = new List(), + ParametersOnMethod = new List(), + Parameters = parameters, + ReturnValue = new ReturnValueApiDescriptionModel + { + Type = "System.Void", + TypeSimple = "void", + }, + AuthorizeDatas = new List(), + }; + controller.AddAction("UploadAsync", action); + + return model; + } +} diff --git a/framework/test/Volo.Abp.Json.Tests/Volo/Abp/Json/AbpDateTimeConverterTimezone_Tests.cs b/framework/test/Volo.Abp.Json.Tests/Volo/Abp/Json/AbpDateTimeConverterTimezone_Tests.cs new file mode 100644 index 0000000000..202c1d59e2 --- /dev/null +++ b/framework/test/Volo.Abp.Json.Tests/Volo/Abp/Json/AbpDateTimeConverterTimezone_Tests.cs @@ -0,0 +1,200 @@ +using System; +using System.Collections.Concurrent; +using System.Linq; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; +using Shouldly; +using Volo.Abp.Timing; +using Xunit; + +namespace Volo.Abp.Json; + +/// +/// Regression tests for the warning +/// "Could not convert DateTime with unspecified Kind using timezone '...'." +/// logged by AbpDateTimeConverterBase.Normalize. +/// +/// When is the converter treats +/// an value as local time in the current user's timezone and +/// converts it to UTC. For a value within the offset distance of / +/// (most commonly the placeholder) a +/// non-zero offset pushes the UTC equivalent outside the supported range, which used to be swallowed +/// and logged as a warning on every serialization. The converter now detects this boundary case and +/// keeps the value unchanged, so no warning is emitted while the serialized output stays the same. +/// +public class AbpDateTimeConverterTimezone_Tests : AbpJsonSystemTextJsonTestBase +{ + private const string WarningFragment = "Could not convert DateTime with unspecified Kind"; + + private static readonly CapturingLoggerProvider LogCapture = new(); + + private readonly IJsonSerializer _jsonSerializer; + private readonly ICurrentTimezoneProvider _currentTimezoneProvider; + + public AbpDateTimeConverterTimezone_Tests() + { + _jsonSerializer = GetRequiredService(); + _currentTimezoneProvider = GetRequiredService(); + } + + protected override void AfterAddApplication(IServiceCollection services) + { + // The warning only happens with a UTC clock, where Unspecified values get converted to UTC. + services.Configure(options => options.Kind = DateTimeKind.Utc); + + LogCapture.Clear(); + services.AddSingleton(LogCapture); + + base.AfterAddApplication(services); + } + + private sealed class FileModel + { + public DateTime DateModified { get; set; } + + public DateTime DateCreated { get; set; } + } + + [Theory] + [InlineData("Asia/Shanghai")] // +08:00 + [InlineData("Europe/Brussels")] // +01:00 / +02:00 + public void Should_Not_Warn_When_Serializing_MinValue_Under_Positive_Offset_Timezone(string timeZoneId) + { + _currentTimezoneProvider.TimeZone = timeZoneId; + LogCapture.Clear(); + + DateTime.MinValue.Kind.ShouldBe(DateTimeKind.Unspecified); + + var json = _jsonSerializer.Serialize(new FileModel + { + DateModified = DateTime.MinValue, + DateCreated = DateTime.MinValue + }); + + // The placeholder is serialized unchanged and no warning is logged. + json.ShouldContain("0001-01-01"); + LogCapture.Warnings.ShouldNotContain(m => m.Contains(WarningFragment)); + } + + [Fact] + public void Should_Not_Warn_When_Serializing_Value_Near_MinValue_Under_Positive_Offset_Timezone() + { + // Not exactly DateTime.MinValue: any value within the offset distance of the lower bound + // overflows the same way, so the converter must absorb it rather than warn. + _currentTimezoneProvider.TimeZone = "Asia/Shanghai"; // +08:00 + LogCapture.Clear(); + + var nearMin = DateTime.MinValue.AddHours(3); // 0001-01-01T03:00:00 - 08:00 underflows + + _jsonSerializer.Serialize(new FileModel + { + DateModified = nearMin, + DateCreated = nearMin + }); + + LogCapture.Warnings.ShouldNotContain(m => m.Contains(WarningFragment)); + } + + [Fact] + public void Should_Not_Warn_When_Serializing_MaxValue_Under_Negative_Offset_Timezone() + { + // The symmetric case: a negative offset would push MaxValue past DateTime.MaxValue. + _currentTimezoneProvider.TimeZone = "America/New_York"; + LogCapture.Clear(); + + var json = _jsonSerializer.Serialize(new FileModel + { + DateModified = DateTime.MaxValue, + DateCreated = DateTime.MaxValue + }); + + json.ShouldContain("9999-12-31"); + LogCapture.Warnings.ShouldNotContain(m => m.Contains(WarningFragment)); + } + + [Fact] + public void Should_Not_Warn_When_Serializing_Real_Utc_Timestamp_Under_Positive_Offset_Timezone() + { + _currentTimezoneProvider.TimeZone = "Asia/Shanghai"; + LogCapture.Clear(); + + var utc = new DateTime(2026, 6, 27, 10, 28, 7, DateTimeKind.Utc); + + var json = _jsonSerializer.Serialize(new FileModel + { + DateModified = utc, + DateCreated = utc + }); + + json.ShouldContain("2026-06-27T10:28:07Z"); + LogCapture.Warnings.ShouldNotContain(m => m.Contains(WarningFragment)); + } + + [Fact] + public void Should_Still_Convert_Real_Unspecified_Timestamp_To_Utc_Under_Positive_Offset_Timezone() + { + // A genuine (non-sentinel) Unspecified value must still be converted to UTC using the offset. + _currentTimezoneProvider.TimeZone = "Asia/Shanghai"; // +08:00 + LogCapture.Clear(); + + var unspecified = new DateTime(2026, 6, 27, 18, 0, 0, DateTimeKind.Unspecified); + + var json = _jsonSerializer.Serialize(new FileModel + { + DateModified = unspecified, + DateCreated = unspecified + }); + + // 18:00 in +08:00 == 10:00 UTC. + json.ShouldContain("2026-06-27T10:00:00Z"); + LogCapture.Warnings.ShouldNotContain(m => m.Contains(WarningFragment)); + } + + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue Warnings { get; } = new(); + + public void Clear() + { + Warnings.Clear(); + } + + public ILogger CreateLogger(string categoryName) + { + return new CapturingLogger(Warnings); + } + + public void Dispose() + { + } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue _sink; + + public CapturingLogger(ConcurrentQueue sink) + { + _sink = sink; + } + + public IDisposable BeginScope(TState state) where TState : notnull + { + return null; + } + + public bool IsEnabled(LogLevel logLevel) + { + return logLevel >= LogLevel.Warning; + } + + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + { + if (logLevel >= LogLevel.Warning) + { + _sink.Enqueue(formatter(state, exception)); + } + } + } + } +} diff --git a/framework/test/Volo.Abp.Mapperly.Tests/Volo/Abp/Mapperly/AbpReverseMapperly_Tests.cs b/framework/test/Volo.Abp.Mapperly.Tests/Volo/Abp/Mapperly/AbpReverseMapperly_Tests.cs index 5d166f7dc8..6dc7b5e2a0 100644 --- a/framework/test/Volo.Abp.Mapperly.Tests/Volo/Abp/Mapperly/AbpReverseMapperly_Tests.cs +++ b/framework/test/Volo.Abp.Mapperly.Tests/Volo/Abp/Mapperly/AbpReverseMapperly_Tests.cs @@ -31,18 +31,18 @@ public partial class MyReverseClassMapper : TwoWayMapperBase Task GetParamsFromQueryAsync(GetParamsInput input); Task GetParamsFromFormAsync(GetParamsInput input); + + Task EchoStatusAsync(); + + Task EchoStatusWithProducesJsonAsync(); + + Task GetBinaryImageAsync(); + + Task ThrowFromStringAsync(); } diff --git a/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/PeopleAppService.cs b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/PeopleAppService.cs index a3920ec8ca..5eb9370754 100644 --- a/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/PeopleAppService.cs +++ b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/PeopleAppService.cs @@ -8,6 +8,7 @@ using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Mvc; using Shouldly; +using Volo.Abp; using Volo.Abp.Application.Dtos; using Volo.Abp.TestApp.Domain; using Volo.Abp.Domain.Repositories; @@ -94,6 +95,30 @@ public class PeopleAppService : CrudAppService, IPeople return new RemoteStreamContent(memoryStream, "download.rtf", "application/rtf"); } + public Task EchoStatusAsync() + { + return Task.FromResult("Open"); + } + + [Produces("application/json")] + public Task EchoStatusWithProducesJsonAsync() + { + return Task.FromResult("Open"); + } + + public Task GetBinaryImageAsync() + { + var bytes = Convert.FromBase64String( + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="); + return Task.FromResult( + new RemoteStreamContent(new MemoryStream(bytes), "tiny.png", "image/png")); + } + + public Task ThrowFromStringAsync() + { + throw new BusinessException("TestApp.StringEndpointBoom", "string endpoint failed"); + } + public async Task UploadAsync(IRemoteStreamContent streamContent) { using (var reader = new StreamReader(streamContent.GetStream())) diff --git a/framework/test/Volo.Abp.Timing.Tests/Volo/Abp/Timing/TimezoneProviderExtensions_Tests.cs b/framework/test/Volo.Abp.Timing.Tests/Volo/Abp/Timing/TimezoneProviderExtensions_Tests.cs new file mode 100644 index 0000000000..6707eb8b82 --- /dev/null +++ b/framework/test/Volo.Abp.Timing.Tests/Volo/Abp/Timing/TimezoneProviderExtensions_Tests.cs @@ -0,0 +1,60 @@ +using System; +using Shouldly; +using Volo.Abp.Testing; +using Xunit; + +namespace Volo.Abp.Timing; + +public class TimezoneProviderExtensions_Tests : AbpIntegratedTest +{ + private readonly ITimezoneProvider _timezoneProvider; + + public TimezoneProviderExtensions_Tests() + { + _timezoneProvider = GetRequiredService(); + } + + [Theory] + [InlineData("Asia/Shanghai")] // +08:00 + [InlineData("Europe/Brussels")] // +01:00 / +02:00 + public void Should_Keep_MinValue_Unchanged_Under_Positive_Offset(string timeZoneId) + { + // A positive offset would push DateTime.MinValue below the supported range; keep it as-is. + var result = _timezoneProvider.ConvertUnspecifiedToUtc(DateTime.MinValue, timeZoneId); + + result.ShouldBe(DateTime.MinValue); + result.Kind.ShouldBe(DateTimeKind.Unspecified); + } + + [Fact] + public void Should_Keep_Value_Near_MinValue_Unchanged_Under_Positive_Offset() + { + var nearMin = DateTime.MinValue.AddHours(3); // 0001-01-01T03:00:00 - 08:00 underflows + + var result = _timezoneProvider.ConvertUnspecifiedToUtc(nearMin, "Asia/Shanghai"); + + result.ShouldBe(nearMin); + result.Kind.ShouldBe(DateTimeKind.Unspecified); + } + + [Fact] + public void Should_Keep_MaxValue_Unchanged_Under_Negative_Offset() + { + var result = _timezoneProvider.ConvertUnspecifiedToUtc(DateTime.MaxValue, "America/New_York"); + + result.ShouldBe(DateTime.MaxValue); + result.Kind.ShouldBe(DateTimeKind.Unspecified); + } + + [Fact] + public void Should_Convert_Unspecified_Value_To_Utc_Using_Offset() + { + var unspecified = new DateTime(2026, 6, 27, 18, 0, 0, DateTimeKind.Unspecified); + + var result = _timezoneProvider.ConvertUnspecifiedToUtc(unspecified, "Asia/Shanghai"); // +08:00 + + // 18:00 in +08:00 == 10:00 UTC. + result.ShouldBe(new DateTime(2026, 6, 27, 10, 0, 0, DateTimeKind.Utc)); + result.Kind.ShouldBe(DateTimeKind.Utc); + } +} diff --git a/latest-versions.json b/latest-versions.json index ccd634c25c..5b6987a34f 100644 --- a/latest-versions.json +++ b/latest-versions.json @@ -1,4 +1,13 @@ [ + { + "version": "10.4.1", + "releaseDate": "", + "type": "stable", + "message": "", + "leptonx": { + "version": "5.4.1" + } + }, { "version": "10.4.0", "releaseDate": "", diff --git a/modules/cms-kit/src/Volo.CmsKit.Admin.Web/CmsKitAdminWebMappers.cs b/modules/cms-kit/src/Volo.CmsKit.Admin.Web/CmsKitAdminWebMappers.cs index 99b07a65fc..fe9dadfd66 100644 --- a/modules/cms-kit/src/Volo.CmsKit.Admin.Web/CmsKitAdminWebMappers.cs +++ b/modules/cms-kit/src/Volo.CmsKit.Admin.Web/CmsKitAdminWebMappers.cs @@ -19,8 +19,8 @@ public partial class BlogFeatureInputDtoToBlogFeatureViewModelMapper : TwoWayMap public override partial FeaturesModalModel.BlogFeatureViewModel Map(BlogFeatureInputDto source); public override partial void Map(BlogFeatureInputDto source, FeaturesModalModel.BlogFeatureViewModel destination); - public override partial BlogFeatureInputDto ReverseMap(FeaturesModalModel.BlogFeatureViewModel destination); - public override partial void ReverseMap(FeaturesModalModel.BlogFeatureViewModel destination, BlogFeatureInputDto source); + public override partial BlogFeatureInputDto ReverseMap(FeaturesModalModel.BlogFeatureViewModel source); + public override partial void ReverseMap(FeaturesModalModel.BlogFeatureViewModel source, BlogFeatureInputDto destination); } [Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)] @@ -29,8 +29,8 @@ public partial class BlogFeatureDtoToBlogFeatureViewModelMapper : TwoWayMapperBa public override partial FeaturesModalModel.BlogFeatureViewModel Map(BlogFeatureDto source); public override partial void Map(BlogFeatureDto source, FeaturesModalModel.BlogFeatureViewModel destination); - public override partial BlogFeatureDto ReverseMap(FeaturesModalModel.BlogFeatureViewModel destination); - public override partial void ReverseMap(FeaturesModalModel.BlogFeatureViewModel destination, BlogFeatureDto source); + public override partial BlogFeatureDto ReverseMap(FeaturesModalModel.BlogFeatureViewModel source); + public override partial void ReverseMap(FeaturesModalModel.BlogFeatureViewModel source, BlogFeatureDto destination); } [Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)] @@ -39,8 +39,8 @@ public partial class CreateBlogPostDtoToCreateBlogPostViewModelMapper : TwoWayMa public override partial CreateModel.CreateBlogPostViewModel Map(CreateBlogPostDto source); public override partial void Map(CreateBlogPostDto source, CreateModel.CreateBlogPostViewModel destination); - public override partial CreateBlogPostDto ReverseMap(CreateModel.CreateBlogPostViewModel destination); - public override partial void ReverseMap(CreateModel.CreateBlogPostViewModel destination, CreateBlogPostDto source); + public override partial CreateBlogPostDto ReverseMap(CreateModel.CreateBlogPostViewModel source); + public override partial void ReverseMap(CreateModel.CreateBlogPostViewModel source, CreateBlogPostDto destination); } [Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)] @@ -49,8 +49,8 @@ public partial class TagUpdateDtoToTagEditViewModelMapper : TwoWayMapperBase> GetGitHubCommitsOrNull(Project project, string documentName, string languageCode, string version) @@ -230,8 +230,8 @@ namespace Volo.Docs.GitHub.Documents var fileCommitsAfterCreation = commits.Take(commits.Count - 1); var commitsToEvaluate = (lastKnownSignificantUpdateTime != null - ? fileCommitsAfterCreation.Where(c => c.Commit.Author.Date.DateTime > lastKnownSignificantUpdateTime) - : fileCommitsAfterCreation).Where(c => c.Commit.Author.Date.DateTime > DateTime.Now.AddDays(-14)); + ? fileCommitsAfterCreation.Where(c => c.Commit.Author.Date.UtcDateTime > lastKnownSignificantUpdateTime) + : fileCommitsAfterCreation).Where(c => c.Commit.Author.Date.UtcDateTime > DateTime.UtcNow.AddDays(-14)); foreach (var gitHubCommit in commitsToEvaluate) { @@ -243,7 +243,7 @@ namespace Volo.Docs.GitHub.Documents if (_githubPatchAnalyzer.HasPatchSignificantChanges(fullCommit.Files.First(f => f.Filename == fileName).Patch)) { - return gitHubCommit.Commit.Author.Date.DateTime; + return gitHubCommit.Commit.Author.Date.UtcDateTime; } } diff --git a/modules/openiddict/Volo.Abp.OpenIddict.slnx b/modules/openiddict/Volo.Abp.OpenIddict.slnx index a67c234a01..3cf219591a 100644 --- a/modules/openiddict/Volo.Abp.OpenIddict.slnx +++ b/modules/openiddict/Volo.Abp.OpenIddict.slnx @@ -16,6 +16,7 @@ + diff --git a/modules/openiddict/src/Volo.Abp.OpenIddict.AspNetCore/Volo/Abp/OpenIddict/AbpOpenIddictAspNetCoreModule.cs b/modules/openiddict/src/Volo.Abp.OpenIddict.AspNetCore/Volo/Abp/OpenIddict/AbpOpenIddictAspNetCoreModule.cs index 48496874d0..26729669e7 100644 --- a/modules/openiddict/src/Volo.Abp.OpenIddict.AspNetCore/Volo/Abp/OpenIddict/AbpOpenIddictAspNetCoreModule.cs +++ b/modules/openiddict/src/Volo.Abp.OpenIddict.AspNetCore/Volo/Abp/OpenIddict/AbpOpenIddictAspNetCoreModule.cs @@ -1,4 +1,5 @@ -using Microsoft.AspNetCore.Mvc.Razor; +using Microsoft.AspNetCore.Identity; +using Microsoft.AspNetCore.Mvc.Razor; using Microsoft.Extensions.DependencyInjection; using OpenIddict.Abstractions; using OpenIddict.Server; @@ -39,6 +40,11 @@ public class AbpOpenIddictAspNetCoreModule : AbpModule { options.ViewLocationFormats.Add("/Volo/Abp/OpenIddict/Views/{1}/{0}.cshtml"); }); + + Configure(options => + { + options.RemoveClientIdClaim(); + }); } private void AddOpenIddictServer(IServiceCollection services) diff --git a/modules/openiddict/src/Volo.Abp.OpenIddict.AspNetCore/Volo/Abp/OpenIddict/AbpOpenIddictSecurityStampValidatorOptionsExtensions.cs b/modules/openiddict/src/Volo.Abp.OpenIddict.AspNetCore/Volo/Abp/OpenIddict/AbpOpenIddictSecurityStampValidatorOptionsExtensions.cs new file mode 100644 index 0000000000..fa4fde8a71 --- /dev/null +++ b/modules/openiddict/src/Volo.Abp.OpenIddict.AspNetCore/Volo/Abp/OpenIddict/AbpOpenIddictSecurityStampValidatorOptionsExtensions.cs @@ -0,0 +1,48 @@ +using System.Linq; +using Microsoft.AspNetCore.Identity; +using Volo.Abp.Security.Claims; + +namespace Volo.Abp.OpenIddict; + +public static class AbpOpenIddictSecurityStampValidatorOptionsExtensions +{ + public static SecurityStampValidatorOptions RemoveClientIdClaim(this SecurityStampValidatorOptions options) + { + // OpenIddictClaimsPrincipalContributor stamps the ambient /connect/authorize request's client_id + // onto every principal built by CreateUserPrincipalAsync. That is meant for the access_token, but the + // cookie security-stamp validator rebuilds the interactive cookie through the same method, so a refresh + // that lands on /connect/authorize leaks client_id into the cookie and corrupts ICurrentClient. + // OnRefreshingPrincipal is the only place the cookie is re-written and never runs for token issuance. + var previousOnRefreshingPrincipal = options.OnRefreshingPrincipal; + options.OnRefreshingPrincipal = async context => + { + // Run the previous callback first: ABP Identity's UpdatePrincipal copies claims that are on the + // current cookie but not on the new principal forward, re-introducing client_id from an + // already-corrupted cookie. Removing it afterwards lets such a cookie self-heal on its next refresh. + if (previousOnRefreshingPrincipal != null) + { + await previousOnRefreshingPrincipal.Invoke(context); + } + + RemoveClientIdClaimsFromPrincipal(context); + }; + + return options; + } + + private static void RemoveClientIdClaimsFromPrincipal(SecurityStampRefreshingPrincipalContext context) + { + if (context.NewPrincipal == null) + { + return; + } + + foreach (var identity in context.NewPrincipal.Identities) + { + foreach (var claim in identity.FindAll(AbpClaimTypes.ClientId).ToArray()) + { + identity.RemoveClaim(claim); + } + } + } +} diff --git a/modules/openiddict/test/Volo.Abp.OpenIddict.AspNetCore.Tests/Volo.Abp.OpenIddict.AspNetCore.Tests.csproj b/modules/openiddict/test/Volo.Abp.OpenIddict.AspNetCore.Tests/Volo.Abp.OpenIddict.AspNetCore.Tests.csproj new file mode 100644 index 0000000000..f4c6815fd6 --- /dev/null +++ b/modules/openiddict/test/Volo.Abp.OpenIddict.AspNetCore.Tests/Volo.Abp.OpenIddict.AspNetCore.Tests.csproj @@ -0,0 +1,21 @@ + + + + + + net10.0 + + + + + + + + + + + + + + + diff --git a/modules/openiddict/test/Volo.Abp.OpenIddict.AspNetCore.Tests/Volo/Abp/OpenIddict/AbpOpenIddictSecurityStampValidatorOptionsExtensions_Tests.cs b/modules/openiddict/test/Volo.Abp.OpenIddict.AspNetCore.Tests/Volo/Abp/OpenIddict/AbpOpenIddictSecurityStampValidatorOptionsExtensions_Tests.cs new file mode 100644 index 0000000000..4231e23b33 --- /dev/null +++ b/modules/openiddict/test/Volo.Abp.OpenIddict.AspNetCore.Tests/Volo/Abp/OpenIddict/AbpOpenIddictSecurityStampValidatorOptionsExtensions_Tests.cs @@ -0,0 +1,154 @@ +using System; +using System.Linq; +using System.Security.Claims; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Identity; +using Shouldly; +using Volo.Abp.Security.Claims; +using Xunit; + +namespace Volo.Abp.OpenIddict; + +public class AbpOpenIddictSecurityStampValidatorOptionsExtensions_Tests +{ + [Fact] + public async Task Should_Remove_ClientId_From_Refreshed_Principal() + { + var context = new SecurityStampRefreshingPrincipalContext + { + NewPrincipal = CreateCookiePrincipal( + new Claim(AbpClaimTypes.UserId, "user-1"), + new Claim(AbpClaimTypes.ClientId, "MyClient")) + }; + + await RefreshPrincipalAsync(context); + + context.NewPrincipal.FindAll(AbpClaimTypes.ClientId).ShouldBeEmpty(); + context.NewPrincipal.FindFirst(AbpClaimTypes.UserId).Value.ShouldBe("user-1"); + } + + [Fact] + public async Task Should_Not_Touch_A_Principal_Without_ClientId() + { + var context = new SecurityStampRefreshingPrincipalContext + { + NewPrincipal = CreateCookiePrincipal(new Claim(AbpClaimTypes.UserId, "user-1")) + }; + + await RefreshPrincipalAsync(context); + + context.NewPrincipal.Claims.Count().ShouldBe(1); + context.NewPrincipal.FindFirst(AbpClaimTypes.UserId).Value.ShouldBe("user-1"); + } + + [Fact] + public async Task Should_Remove_Every_ClientId_Claim_From_Every_Identity() + { + var principal = new ClaimsPrincipal(); + principal.AddIdentity(new ClaimsIdentity( + new[] { new Claim(AbpClaimTypes.UserId, "user-1"), new Claim(AbpClaimTypes.ClientId, "Client-A") }, + IdentityConstants.ApplicationScheme)); + principal.AddIdentity(new ClaimsIdentity( + new[] { new Claim(AbpClaimTypes.ClientId, "Client-B"), new Claim(AbpClaimTypes.ClientId, "Client-C") }, + IdentityConstants.ApplicationScheme)); + + var context = new SecurityStampRefreshingPrincipalContext { NewPrincipal = principal }; + + await RefreshPrincipalAsync(context); + + context.NewPrincipal.FindAll(AbpClaimTypes.ClientId).ShouldBeEmpty(); + context.NewPrincipal.FindFirst(AbpClaimTypes.UserId).Value.ShouldBe("user-1"); + } + + [Fact] + public async Task Should_Not_Throw_When_New_Principal_Is_Null() + { + var context = new SecurityStampRefreshingPrincipalContext { NewPrincipal = null }; + + await Should.NotThrowAsync(() => RefreshPrincipalAsync(context)); + } + + [Fact] + public async Task Should_Remove_ClientId_After_Running_The_Previously_Registered_Callback() + { + // The real module order: ABP Identity's callback is registered first, the removal after it. Identity's + // SecurityStampValidatorCallback.UpdatePrincipal copies client_id from an already-corrupted cookie onto + // the refreshed principal; the removal still strips it, so the cookie self-heals on its next refresh. + var previousCallbackRan = false; + Task PreviousCallback(SecurityStampRefreshingPrincipalContext context) + { + previousCallbackRan = true; + CopyClientIdForward(context); + return Task.CompletedTask; + } + + var refreshingContext = CreateCorruptedCookieRefreshContext(); + + await RefreshPrincipalAsync(refreshingContext, PreviousCallback); + + previousCallbackRan.ShouldBeTrue(); + refreshingContext.NewPrincipal.FindAll(AbpClaimTypes.ClientId).ShouldBeEmpty(); + } + + [Fact] + public async Task Should_Remove_ClientId_When_A_Callback_Is_Registered_After_It() + { + // The reverse order: the removal is registered first and an Identity-style callback (which runs its own + // copy-forward before invoking the previous callback) is registered after it. Because the two wrappers + // chain in opposite directions, the removal still runs last, so the order the modules load does not matter. + var options = new SecurityStampValidatorOptions(); + options.RemoveClientIdClaim(); + + var previousOnRefreshingPrincipal = options.OnRefreshingPrincipal; + options.OnRefreshingPrincipal = async context => + { + CopyClientIdForward(context); + if (previousOnRefreshingPrincipal != null) + { + await previousOnRefreshingPrincipal.Invoke(context); + } + }; + + var refreshingContext = CreateCorruptedCookieRefreshContext(); + + await options.OnRefreshingPrincipal(refreshingContext); + + refreshingContext.NewPrincipal.FindAll(AbpClaimTypes.ClientId).ShouldBeEmpty(); + } + + private static async Task RefreshPrincipalAsync( + SecurityStampRefreshingPrincipalContext context, + Func previousCallback = null) + { + var options = new SecurityStampValidatorOptions { OnRefreshingPrincipal = previousCallback }; + + options.RemoveClientIdClaim().ShouldBeSameAs(options); + + await options.OnRefreshingPrincipal(context); + } + + private static void CopyClientIdForward(SecurityStampRefreshingPrincipalContext context) + { + var clientId = context.CurrentPrincipal.FindFirst(AbpClaimTypes.ClientId); + if (clientId != null) + { + context.NewPrincipal.Identities.First().AddClaim(clientId); + } + } + + private static SecurityStampRefreshingPrincipalContext CreateCorruptedCookieRefreshContext() + { + return new SecurityStampRefreshingPrincipalContext + { + CurrentPrincipal = CreateCookiePrincipal( + new Claim(AbpClaimTypes.UserId, "user-1"), + new Claim(AbpClaimTypes.ClientId, "MyClient")), + NewPrincipal = CreateCookiePrincipal(new Claim(AbpClaimTypes.UserId, "user-1")) + }; + } + + private static ClaimsPrincipal CreateCookiePrincipal(params Claim[] claims) + { + return new ClaimsPrincipal(new ClaimsIdentity(claims, IdentityConstants.ApplicationScheme)); + } +} diff --git a/modules/virtual-file-explorer/app/DemoApp.csproj b/modules/virtual-file-explorer/app/DemoApp.csproj index 4f35545d60..de84b1779e 100644 --- a/modules/virtual-file-explorer/app/DemoApp.csproj +++ b/modules/virtual-file-explorer/app/DemoApp.csproj @@ -46,7 +46,7 @@ - + runtime; build; native; contentfiles; analyzers compile; contentFiles; build; buildMultitargeting; buildTransitive; analyzers; native diff --git a/npm/ng-packs/.gitignore b/npm/ng-packs/.gitignore index 84b48a798c..e991e4a0dd 100644 --- a/npm/ng-packs/.gitignore +++ b/npm/ng-packs/.gitignore @@ -59,4 +59,5 @@ Thumbs.db .nx/ -vitest.config.*.timestamp* \ No newline at end of file +vitest.config.*.timestamp* +.claude/worktrees \ No newline at end of file diff --git a/npm/ng-packs/.prettierignore b/npm/ng-packs/.prettierignore index feffcae59f..b57d35e3b8 100644 --- a/npm/ng-packs/.prettierignore +++ b/npm/ng-packs/.prettierignore @@ -11,3 +11,5 @@ /.nx/cache /.nx/workspace-data .angular + +.nx/self-healing \ No newline at end of file diff --git a/npm/ng-packs/apps/dev-app/project.json b/npm/ng-packs/apps/dev-app/project.json index c397d8d449..991b7111a7 100644 --- a/npm/ng-packs/apps/dev-app/project.json +++ b/npm/ng-packs/apps/dev-app/project.json @@ -166,7 +166,7 @@ "defaultConfiguration": "development" }, "extract-i18n": { - "executor": "@angular-devkit/build-angular:extract-i18n", + "executor": "@angular/build:extract-i18n", "options": { "buildTarget": "dev-app:build" } @@ -179,7 +179,7 @@ "outputs": ["{workspaceRoot}/coverage/apps/dev-app"], "options": { "passWithNoTests": true, - "reportsDirectory": "../../coverage/apps/dev-app", + "reportsDirectory": "{projectRoot}/../../coverage/apps/dev-app", "silent": false } }, diff --git a/npm/ng-packs/apps/dev-app/src/app/app.component.ts b/npm/ng-packs/apps/dev-app/src/app/app.component.ts index 57d3ff6695..595f5caed3 100644 --- a/npm/ng-packs/apps/dev-app/src/app/app.component.ts +++ b/npm/ng-packs/apps/dev-app/src/app/app.component.ts @@ -1,12 +1,13 @@ -import { Component } from '@angular/core'; +import { ChangeDetectionStrategy, Component } from '@angular/core'; import { LoaderBarComponent } from '@abp/ng.theme.shared'; import { DynamicLayoutComponent } from '@abp/ng.core'; @Component({ + changeDetection: ChangeDetectionStrategy.OnPush, selector: 'app-root', template: ` - - + + `, imports: [LoaderBarComponent, DynamicLayoutComponent], }) diff --git a/npm/ng-packs/apps/dev-app/src/app/app.config.ts b/npm/ng-packs/apps/dev-app/src/app/app.config.ts index 6b8bcf2c05..23a3541339 100644 --- a/npm/ng-packs/apps/dev-app/src/app/app.config.ts +++ b/npm/ng-packs/apps/dev-app/src/app/app.config.ts @@ -4,7 +4,7 @@ import { provideClientHydration, withEventReplay, withHttpTransferCacheOptions, - withIncrementalHydration, + withNoIncrementalHydration, } from '@angular/platform-browser'; import { appRoutes } from './app.routes'; @@ -20,7 +20,6 @@ import { provideIdentityConfig } from '@abp/ng.identity/config'; import { provideTenantManagementConfig } from '@abp/ng.tenant-management/config'; import { provideFeatureManagementConfig } from '@abp/ng.feature-management'; import { provideThemeBasicConfig } from '@abp/ng.theme.basic'; -import { provideAnimations } from '@angular/platform-browser/animations'; export const appConfig: ApplicationConfig = { providers: [ @@ -46,12 +45,11 @@ export const appConfig: ApplicationConfig = { provideFeatureManagementConfig(), provideZoneChangeDetection({ eventCoalescing: true }), provideThemeBasicConfig(), - provideAnimations(), provideRouter(appRoutes), provideClientHydration( withEventReplay(), withHttpTransferCacheOptions({}), - withIncrementalHydration(), + withNoIncrementalHydration(), ), ], }; diff --git a/npm/ng-packs/apps/dev-app/src/app/dynamic-form-page/dynamic-form-page.component.html b/npm/ng-packs/apps/dev-app/src/app/dynamic-form-page/dynamic-form-page.component.html index c675dca707..d9f91beae5 100644 --- a/npm/ng-packs/apps/dev-app/src/app/dynamic-form-page/dynamic-form-page.component.html +++ b/npm/ng-packs/apps/dev-app/src/app/dynamic-form-page/dynamic-form-page.component.html @@ -20,9 +20,9 @@ All 16 field types + Nested Forms (Group & Array) with full accessibility support
- @if (formFields.length) { + @if (formFields().length) { { - this.formFields = config; - }); - } + submit(formData: any) { + console.log('✅ Form Submitted Successfully!', formData); + console.table(formData); - submit(formData: any) { - console.log('✅ Form Submitted Successfully!', formData); - console.table(formData); - - // Show success message - alert('✅ Form submitted successfully! Check the console for details.'); - - // Reset form after submission - this.dynamicFormComponent().resetForm(); - } + alert('✅ Form submitted successfully! Check the console for details.'); - cancel() { - console.log('❌ Form Cancelled'); - alert('Form cancelled'); - this.dynamicFormComponent().resetForm(); - } + this.dynamicFormComponent()?.resetForm(); + } + + cancel() { + console.log('❌ Form Cancelled'); + alert('Form cancelled'); + this.dynamicFormComponent()?.resetForm(); + } } diff --git a/npm/ng-packs/apps/dev-app/src/app/home/home.component.html b/npm/ng-packs/apps/dev-app/src/app/home/home.component.html index d8b08c06ae..cea534b296 100644 --- a/npm/ng-packs/apps/dev-app/src/app/home/home.component.html +++ b/npm/ng-packs/apps/dev-app/src/app/home/home.component.html @@ -16,7 +16,7 @@

{{ '::LongWelcomeMessage' | abpLocalization }}

@if (!hasLoggedIn) { - {{ 'AbpAccount::Login' | abpLocalization }} diff --git a/npm/ng-packs/apps/dev-app/src/app/home/home.component.ts b/npm/ng-packs/apps/dev-app/src/app/home/home.component.ts index aa25b046d7..00b79e090d 100644 --- a/npm/ng-packs/apps/dev-app/src/app/home/home.component.ts +++ b/npm/ng-packs/apps/dev-app/src/app/home/home.component.ts @@ -1,10 +1,11 @@ import { AuthService, LocalizationPipe } from '@abp/ng.core'; -import { Component, inject } from '@angular/core'; +import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core'; import { NgTemplateOutlet } from '@angular/common'; import { ButtonComponent, CardBodyComponent, CardComponent } from '@abp/ng.theme.shared'; import { RouterLink } from '@angular/router'; @Component({ + changeDetection: ChangeDetectionStrategy.OnPush, selector: 'app-home', templateUrl: './home.component.html', imports: [ @@ -18,14 +19,14 @@ import { RouterLink } from '@angular/router'; }) export class HomeComponent { protected readonly authService = inject(AuthService); - loading = false; + readonly loading = signal(false); get hasLoggedIn(): boolean { return this.authService.isAuthenticated; } login() { - this.loading = true; + this.loading.set(true); this.authService.navigateToLogin(); } } diff --git a/npm/ng-packs/apps/dev-app/src/app/localization-test/localization-test.component.ts b/npm/ng-packs/apps/dev-app/src/app/localization-test/localization-test.component.ts index 187f6d1e37..9ce6a4a80c 100644 --- a/npm/ng-packs/apps/dev-app/src/app/localization-test/localization-test.component.ts +++ b/npm/ng-packs/apps/dev-app/src/app/localization-test/localization-test.component.ts @@ -1,13 +1,13 @@ -import { Component, inject, OnInit } from '@angular/core'; +import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core'; +import { toSignal } from '@angular/core/rxjs-interop'; import { LocalizationPipe, UILocalizationService, SessionStateService } from '@abp/ng.core'; import { CommonModule } from '@angular/common'; import { CardComponent, CardBodyComponent } from '@abp/ng.theme.shared'; -import { AsyncPipe } from '@angular/common'; @Component({ + changeDetection: ChangeDetectionStrategy.OnPush, selector: 'app-localization-test', - standalone: true, - imports: [CommonModule, LocalizationPipe, CardComponent, CardBodyComponent, AsyncPipe], + imports: [CommonModule, LocalizationPipe, CardComponent, CardBodyComponent], template: `

Hybrid Localization Test

@@ -22,7 +22,7 @@ import { AsyncPipe } from '@angular/common'; -
UI Localization (from /assets/localization/{{ currentLanguage$ | async }}.json)
+
UI Localization (from /assets/localization/{{ currentLanguage() }}.json)

MyProjectName::CustomKey: {{ 'MyProjectName::CustomKey' | abpLocalization }}

MyProjectName::TestMessage: {{ 'MyProjectName::TestMessage' | abpLocalization }}

 @@ -39,20 +39,19 @@ import { AsyncPipe } from '@angular/common';
Loaded UI Localizations
- 
{{ loadedLocalizations | json }}
+ 
{{ loadedLocalizations() | json }}
`, }) -export class LocalizationTestComponent implements OnInit { +export class LocalizationTestComponent { private uiLocalizationService = inject(UILocalizationService); private sessionState = inject(SessionStateService); - loadedLocalizations: any = {}; - currentLanguage$ = this.sessionState.getLanguage$(); + readonly loadedLocalizations = signal(this.uiLocalizationService.getLoadedLocalizations()); - ngOnInit() { - this.loadedLocalizations = this.uiLocalizationService.getLoadedLocalizations(); - } + readonly currentLanguage = toSignal(this.sessionState.getLanguage$(), { + initialValue: this.sessionState.getLanguage(), + }); } diff --git a/npm/ng-packs/apps/dev-app/tsconfig.json b/npm/ng-packs/apps/dev-app/tsconfig.json index f02580de5c..df2232aed6 100644 --- a/npm/ng-packs/apps/dev-app/tsconfig.json +++ b/npm/ng-packs/apps/dev-app/tsconfig.json @@ -28,6 +28,6 @@ "angularCompilerOptions": { "strictInjectionParameters": false, "strictInputAccessModifiers": false, - "strictTemplates": false + "strictTemplates": true } } diff --git a/npm/ng-packs/guides/DEVELOPMENT_GUIDE.md b/npm/ng-packs/guides/DEVELOPMENT_GUIDE.md index a44fd2a49d..9bc8e964fb 100644 --- a/npm/ng-packs/guides/DEVELOPMENT_GUIDE.md +++ b/npm/ng-packs/guides/DEVELOPMENT_GUIDE.md @@ -222,12 +222,52 @@ Example HTML template ### Component Best Practices 1. **Single Responsibility**: Each component should have one clear purpose -2. **Dependency Injection**: Use constructor injection for services -3. **Lifecycle Management**: Implement `OnInit` and `OnDestroy` when needed -4. **State Management**: Use reactive forms and observables -5. **Error Handling**: Implement proper error boundaries -6. **Accessibility**: Follow ARIA guidelines -7. **Performance**: Use `OnPush` change detection when possible +2. **Dependency Injection**: Use `inject()` for services +3. **Change detection**: Set `changeDetection: ChangeDetectionStrategy.OnPush` explicitly on every component +4. **Async state**: Use `signal()` / `computed()` / `toSignal()` — avoid mutating plain properties in `.subscribe()` without a CD trigger +5. **List pages**: Use `toSignal(this.list.hookToQuery(...))` and bind `data().items` in templates +6. **Component IO**: Prefer signal `input()` / `output()` / `model()` over `@Input` / `@Output` +7. **Modal bindings**: `[visible]="isModalVisible()" (visibleChange)="isModalVisible.set($event)"` with `[busy]="modalBusy()"` +8. **`markForCheck()`**: Discouraged — use only in directives, CVAs, or dynamic component hosts where signals cannot apply +9. **Error Handling**: Implement proper error boundaries +10. **Accessibility**: Follow ARIA guidelines + +See [upgrade-notes.md](../upgrade-notes.md) for Angular 22 customer migration guidance. + +### Angular 22 component pattern (recommended) + +```typescript +import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core'; +import { toSignal } from '@angular/core/rxjs-interop'; +import { ListService, PagedResultDto } from '@abp/ng.core'; + +@Component({ + changeDetection: ChangeDetectionStrategy.OnPush, + selector: 'abp-my-list', + providers: [ListService], +}) +export class MyListComponent { + protected readonly list = inject(ListService); + protected readonly service = inject(MyService); + + readonly data = toSignal(this.list.hookToQuery(q => this.service.getList(q)), { + initialValue: { items: [], totalCount: 0 } as PagedResultDto, + }); + + readonly isModalVisible = signal(false); + readonly modalBusy = signal(false); +} +``` + +```html + + + +``` ## Service Layer diff --git a/npm/ng-packs/migrations.json b/npm/ng-packs/migrations.json index 3615f35e50..d4d67927bf 100644 --- a/npm/ng-packs/migrations.json +++ b/npm/ng-packs/migrations.json @@ -1,118 +1,130 @@ { "migrations": [ { - "version": "22.0.0-beta.1", - "description": "Updates release version config based on the breaking changes in Nx v22", - "implementation": "./src/migrations/update-22-0-0/release-version-config-changes", + "cli": "nx", + "version": "22.6.0-beta.10", + "description": "Adds .claude/worktrees to .gitignore", + "implementation": "./dist/src/migrations/update-22-6-0/add-claude-worktrees-to-git-ignore", "package": "nx", - "name": "22-0-0-release-version-config-changes" + "name": "22-6-1-add-claude-worktrees-to-git-ignore" }, { - "version": "22.0.0-beta.2", - "description": "Consolidates releaseTag* options into nested releaseTag object structure", - "implementation": "./src/migrations/update-22-0-0/consolidate-release-tag-config", + "cli": "nx", + "version": "22.7.0-beta.0", + "description": "Adds .nx/polygraph to .gitignore", + "implementation": "./dist/src/migrations/update-22-7-0/add-polygraph-to-git-ignore", "package": "nx", - "name": "22-0-0-consolidate-release-tag-config" + "name": "22-7-0-add-polygraph-to-git-ignore" }, { "cli": "nx", - "version": "22.1.0-beta.5", - "description": "Updates the nx wrapper.", - "implementation": "./src/migrations/update-22-1-0/update-nx-wrapper", + "version": "22.6.0-rc.0", + "description": "Adds .claude/settings.local.json to .gitignore", + "implementation": "./dist/src/migrations/update-17-3-0/update-nxw", "package": "nx", - "name": "22-1-0-update-nx-wrapper" + "name": "22-6-0-add-claude-settings-local-to-git-ignore" }, { - "version": "21.5.0-beta.2", - "description": "Migrate the legacy 'development' custom condition to a workspace-unique custom condition name.", - "factory": "./src/migrations/update-21-5-0/migrate-development-custom-condition", - "package": "@nx/js", - "name": "migrate-development-custom-condition" + "cli": "nx", + "version": "22.7.0-beta.0", + "description": "Adds .nx/self-healing to .gitignore", + "implementation": "./dist/src/migrations/update-22-2-0/add-self-healing-to-gitignore", + "package": "nx", + "name": "22-7-0-add-self-healing-to-gitignore" }, { - "version": "22.0.0-beta.0", - "description": "Remove the deprecated `external` and `externalBuildTargets` options from the `@nx/js:swc` and `@nx/js:tsc` executors.", - "factory": "./src/migrations/update-22-0-0/remove-external-options-from-js-executors", - "package": "@nx/js", - "name": "remove-external-options-from-js-executors" + "version": "22.3.2-beta.0", + "requires": { + "@angular/build": ">=21.0.0" + }, + "description": "Create AI Instructions to help migrate users workspaces past breaking changes for Vitest 4.", + "implementation": "./src/migrations/update-22-1-0/create-ai-instructions-for-vitest-4", + "package": "@nx/vitest", + "name": "update-22-3-2" }, { - "version": "22.1.0-rc.1", - "description": "Removes redundant TypeScript project references from project's tsconfig.json files when runtime tsconfig files (e.g., tsconfig.lib.json, tsconfig.app.json) exist.", - "factory": "./src/migrations/update-22-1-0/remove-redundant-ts-project-references", - "package": "@nx/js", - "name": "remove-redundant-ts-project-references" + "version": "22.6.0-beta.11", + "description": "Prefix reportsDirectory with {projectRoot} to maintain correct resolution after workspace-root-relative behavior change.", + "implementation": "./src/migrations/update-22-6-0/prefix-reports-directory-with-project-root", + "package": "@nx/vitest", + "name": "update-22-6-0-prefix-reports-directory" }, { - "version": "21.3.0-beta.3", - "description": "Rename the CLI option `testPathPattern` to `testPathPatterns`.", - "implementation": "./src/migrations/update-21-3-0/rename-test-path-pattern", - "package": "@nx/jest", - "name": "rename-test-path-pattern" + "version": "22.7.0-beta.12", + "description": "Add missing inputs to @nx/eslint:lint executor target defaults", + "implementation": "./src/migrations/update-21-6-0/update-executor-lint-inputs", + "package": "@nx/eslint", + "name": "update-executor-lint-inputs" }, { - "version": "22.2.0-beta.2", - "description": "Convert jest.config.ts files from ESM to CJS syntax (export default -> module.exports, import -> require) for projects using CommonJS resolution to ensure correct loading under Node.js type-stripping.", - "implementation": "./src/migrations/update-22-2-0/convert-jest-config-to-cjs", + "version": "22.3.2-beta.0", + "requires": { + "jest": ">=30.0.0" + }, + "description": "Replace removed matcher aliases in Jest v30 with their corresponding matcher", + "implementation": "./src/migrations/update-21-3-0/replace-removed-matcher-aliases", "package": "@nx/jest", - "name": "convert-jest-config-to-cjs" + "name": "replace-removed-matcher-aliases-v22-3" }, { - "cli": "nx", - "version": "21.3.0-beta.4", - "requires": { "@angular/core": ">=20.1.0" }, - "description": "Update the @angular/cli package version to ~20.1.0.", - "factory": "./src/migrations/update-21-3-0/update-angular-cli", + "version": "22.3.0-beta.0", + "requires": { + "@angular/core": ">=21.0.0" + }, + "description": "Updates webpack-based SSR configuration to use preserve module format and bundler module resolution.", + "factory": "./src/migrations/update-22-3-0/update-ssr-webpack-config", "package": "@nx/angular", - "name": "update-angular-cli-version-20-1-0" + "name": "update-ssr-webpack-config-22-2-0" }, { - "version": "21.5.0-beta.0", - "description": "Set the 'tsConfig' option to build and test targets to help with Angular migration issues.", - "factory": "./src/migrations/update-21-5-0/set-tsconfig-option", + "version": "22.3.0-beta.0", + "requires": { + "@angular/core": ">=21.0.0-rc.3" + }, + "description": "Update 'module' to 'preserve' and 'moduleResolution' to 'bundler' in TypeScript configurations for Angular projects.", + "factory": "./src/migrations/update-22-3-0/update-module-resolution", "package": "@nx/angular", - "name": "set-tsconfig-option" + "name": "update-module-resolution-22-2-0" }, { - "cli": "nx", - "version": "21.5.0-beta.2", - "requires": { "@angular/core": ">=20.2.0" }, - "description": "Update the @angular/cli package version to ~20.2.0.", - "factory": "./src/migrations/update-21-5-0/update-angular-cli", + "version": "22.3.0-beta.0", + "requires": { + "@angular/core": ">=21.0.0" + }, + "description": "Updates the 'lib' property in tsconfig files to use 'es2022' or a more modern version.", + "factory": "./src/migrations/update-22-3-0/update-typescript-lib", "package": "@nx/angular", - "name": "update-angular-cli-version-20-2-0" + "name": "update-typescript-lib-22-2-0" }, { - "version": "21.5.0-beta.2", - "requires": { "@angular/core": ">=20.2.0" }, - "description": "Remove any Karma configuration files that only contain the default content. The default configuration is automatically available without a specific project configurationfile.", - "factory": "./src/migrations/update-21-5-0/remove-default-karma-configuration-files", + "version": "22.3.0-beta.0", + "requires": { + "@angular/core": ">=21.0.0" + }, + "description": "Update 'vitest' unit test runner option to 'vitest-analog' in generator defaults.", + "factory": "./src/migrations/update-22-3-0/update-unit-test-runner-option", "package": "@nx/angular", - "name": "remove-default-karma-configuration-files" + "name": "update-unit-test-runner-option" }, { - "cli": "nx", - "version": "21.6.1-beta.2", - "requires": { "@angular/core": ">=20.3.0" }, - "description": "Update the @angular/cli package version to ~20.3.0.", - "factory": "./src/migrations/update-21-6-1/update-angular-cli", + "version": "22.3.0-beta.3", + "requires": { + "@angular/core": ">=21.0.0" + }, + "description": "Set 'isolatedModules' to 'true' in TypeScript test configurations for Angular projects.", + "factory": "./src/migrations/update-22-3-0/set-isolated-modules", "package": "@nx/angular", - "name": "update-angular-cli-version-20-3-0" + "name": "set-isolated-modules-22-3-0" }, { - "version": "20.2.0", - "description": "Replaces usages of the deprecated Router.getCurrentNavigation method with the Router.currentNavigation signal", - "factory": "./bundles/router-current-navigation.cjs#migrate", - "optional": true, - "package": "@angular/core", - "name": "router-current-navigation" - }, - { - "version": "20.3.0", - "description": "Adds `BootstrapContext` to `bootstrapApplication` calls in `main.server.ts` to support server rendering.", - "factory": "./bundles/add-bootstrap-context-to-server-main.cjs#migrate", - "package": "@angular/core", - "name": "add-bootstrap-context-to-server-main" + "version": "22.3.0-beta.3", + "requires": { + "@angular/core": ">=21.0.0" + }, + "description": "Replace 'jest-preset-angular/setup-jest' imports with the new 'setupZoneTestEnv' function.", + "factory": "./src/migrations/update-22-3-0/update-jest-preset-angular-setup", + "package": "@nx/angular", + "name": "update-jest-preset-angular-setup" } ] } diff --git a/npm/ng-packs/nx.json b/npm/ng-packs/nx.json index a573c5c59a..f87bf30ba8 100644 --- a/npm/ng-packs/nx.json +++ b/npm/ng-packs/nx.json @@ -111,7 +111,12 @@ } }, "@nx/eslint:lint": { - "inputs": ["default", "{workspaceRoot}/.eslintrc.json"], + "inputs": [ + "default", + "^default", + "{workspaceRoot}/.eslintrc.json", + "{workspaceRoot}/tools/eslint-rules/**/*" + ], "cache": true }, "@angular/build:application": { @@ -135,5 +140,6 @@ "!{projectRoot}/.eslintrc.json" ] }, - "parallel": 3 + "parallel": 3, + "analytics": false } diff --git a/npm/ng-packs/package.json b/npm/ng-packs/package.json index 85a9e98189..f27e905f84 100644 --- a/npm/ng-packs/package.json +++ b/npm/ng-packs/package.json @@ -32,7 +32,7 @@ "dep-graph": "nx dep-graph", "help": "nx help", "build:schematics": "cd scripts && yarn && yarn build:schematics && cd ..", - "dev:schematics": "tsc -p packages/schematics/tsconfig.json -w", + "dev:schematics": "tsc -p packages/schematics/tsconfig.lib.json -w", "mock:schematics": "cd scripts/mock-schematic && yarn && yarn start", "debug:schematics": "./node_modules/.bin/nx g ./packages/schematics/src/collection.json:proxy-add --module identity --apiName __default --source __default --target __default --url https://localhost:44305 --serviceType application --entryPoint __default ", "debug:schematics-dist": "./node_modules/.bin/ng g ./dist/packages/schematics/collection.json:proxy-add --module __default --apiName __default --source __default --target __default --url http://localhost:4300 --service-type application --entryPoint __default", @@ -77,27 +77,27 @@ "@ng-bootstrap/ng-bootstrap": "~20.0.0", "@ngneat/spectator": "~19.6.2", "@ngx-validate/core": "^0.2.0", - "@nx/angular": "~22.2.0", - "@nx/cypress": "~22.2.0", - "@nx/devkit": "~22.2.0", - "@nx/eslint": "~22.2.0", - "@nx/eslint-plugin": "~22.2.0", - "@nx/jest": "~22.2.0", - "@nx/js": "22.2.7", - "@nx/plugin": "~22.2.0", - "@nx/vite": "22.2.7", - "@nx/vitest": "22.2.7", - "@nx/web": "~22.2.0", - "@nx/workspace": "~22.2.0", + "@nx/angular": "~22.7.5", + "@nx/cypress": "~22.7.5", + "@nx/devkit": "~22.7.5", + "@nx/eslint": "~22.7.5", + "@nx/eslint-plugin": "~22.7.5", + "@nx/jest": "~22.7.5", + "@nx/js": "~22.7.5", + "@nx/plugin": "~22.7.5", + "@nx/vite": "~22.7.5", + "@nx/vitest": "~22.7.5", + "@nx/web": "~22.7.5", + "@nx/workspace": "~22.7.5", "@popperjs/core": "~2.11.0", - "@schematics/angular": "~21.2.0", - "@swc-node/register": "1.9.2", - "@swc/cli": "0.6.0", - "@swc/core": "~1.5.7", - "@swc/helpers": "~0.5.11", + "@schematics/angular": "~22.0.0", + "@swc-node/register": "~1.11.1", + "@swc/cli": "~0.7.10", + "@swc/core": "~1.15.8", + "@swc/helpers": "~0.5.23", "@swimlane/ngx-datatable": "~22.0.0", "@types/express": "~5.0.0", - "@types/jest": "29.5.14", + "@types/jest": "~30.0.0", "@types/node": "20.19.9", "@typescript-eslint/eslint-plugin": "7.16.0", "@typescript-eslint/parser": "7.16.0", @@ -117,10 +117,10 @@ "eslint-plugin-cypress": "^3.5.0", "express": "~5.1.0", "got": "^11.0.0", - "jest": "^29.0.0", + "jest": "~30.4.2", "jest-canvas-mock": "^2.0.0", - "jest-environment-jsdom": "^29.0.0", - "jest-preset-angular": "14.6.0", + "jest-environment-jsdom": "~30.4.1", + "jest-preset-angular": "~16.0.0", "jsdom": "~22.1.0", "jsonc-eslint-parser": "^2.0.0", "jsonc-parser": "^2.0.0", @@ -128,9 +128,9 @@ "just-compare": "^2.0.0", "lerna": "^4.0.0", "lint-staged": "^13.0.0", - "ng-packagr": "~21.2.0", + "ng-packagr": "~22.0.0", "ng-zorro-antd": "~21.1.0", - "nx": "~22.2.0", + "nx": "~22.7.5", "postcss": "^8.0.0", "postcss-import": "14.1.0", "postcss-preset-env": "7.5.0", @@ -140,15 +140,16 @@ "@toast-ui/editor": "~3.0.0", "rxjs": "~7.8.0", "should-quote": "^1.0.0", - "ts-jest": "29.4.6", + "ts-jest": "~29.4.6", "ts-node": "10.9.1", "ts-toolbelt": "^9.0.0", "tslib": "^2.3.0", "tslint": "~6.1.0", - "typescript": "~5.9.0", + "typescript": "~6.0.0", "vite": "^8.0.0", "vitest": "^4.0.0", - "zone.js": "~0.15.0" + "zone.js": "~0.15.0", + "jest-util": "~30.4.1" }, "lint-staged": { "**/*.{js,jsx,ts,tsx,html,css,scss}": [ diff --git a/npm/ng-packs/packages/account-core/project.json b/npm/ng-packs/packages/account-core/project.json index 8a201b8006..0825ff6e6f 100644 --- a/npm/ng-packs/packages/account-core/project.json +++ b/npm/ng-packs/packages/account-core/project.json @@ -31,7 +31,7 @@ "executor": "@nx/vitest:test", "outputs": ["{options.reportsDirectory}"], "options": { - "reportsDirectory": "../../coverage/packages/account-core" + "reportsDirectory": "{projectRoot}/../../coverage/packages/account-core" } } } diff --git a/npm/ng-packs/packages/account/project.json b/npm/ng-packs/packages/account/project.json index 5d02bebd76..74231300a2 100644 --- a/npm/ng-packs/packages/account/project.json +++ b/npm/ng-packs/packages/account/project.json @@ -31,7 +31,7 @@ "executor": "@nx/vitest:test", "outputs": ["{options.reportsDirectory}"], "options": { - "reportsDirectory": "../../coverage/packages/account" + "reportsDirectory": "{projectRoot}/../../coverage/packages/account" } } } diff --git a/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.html b/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.html index a10e190664..69608d6bad 100644 --- a/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.html +++ b/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.html @@ -1,11 +1,17 @@ -
- @if (!hideCurrentPassword) { + + @if (!hideCurrentPassword()) {
* + * + * + * + * + * + {{ 'AbpIdentity::Save' | abpLocalization }} + {{ 'AbpIdentity::Save' | abpLocalization }} + diff --git a/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.ts b/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.ts index ad5db820ac..1673601729 100644 --- a/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.ts +++ b/npm/ng-packs/packages/account/src/lib/components/change-password/change-password.component.ts @@ -1,6 +1,13 @@ import { ProfileService } from '@abp/ng.account.core/proxy'; import { ButtonComponent, getPasswordValidators, ToasterService } from '@abp/ng.theme.shared'; -import { Component, Injector, OnInit, inject } from '@angular/core'; +import { + Component, + Injector, + OnInit, + inject, + signal, + ChangeDetectionStrategy, +} from '@angular/core'; import { ReactiveFormsModule, UntypedFormBuilder, @@ -18,6 +25,7 @@ const { required } = Validators; const PASSWORD_FIELDS = ['newPassword', 'repeatNewPassword']; @Component({ + changeDetection: ChangeDetectionStrategy.OnPush, selector: 'abp-change-password-form', templateUrl: './change-password.component.html', exportAs: 'abpChangePasswordForm', @@ -40,9 +48,8 @@ export class ChangePasswordComponent form!: UntypedFormGroup; - inProgress?: boolean; - - hideCurrentPassword?: boolean; + readonly inProgress = signal(false); + readonly hideCurrentPassword = signal(false); mapErrorsFn: Validation.MapErrorsFn = (errors, groupErrors, control) => { if (PASSWORD_FIELDS.indexOf(String(control?.name)) < 0) return errors; @@ -51,7 +58,7 @@ export class ChangePasswordComponent }; ngOnInit(): void { - this.hideCurrentPassword = !this.manageProfileState.getProfile()?.hasPassword; + this.hideCurrentPassword.set(!this.manageProfileState.getProfile()?.hasPassword); const passwordValidations = getPasswordValidators(this.injector); @@ -76,18 +83,18 @@ export class ChangePasswordComponent }, ); - if (this.hideCurrentPassword) this.form.removeControl('password'); + if (this.hideCurrentPassword()) this.form.removeControl('password'); } onSubmit() { if (this.form.invalid) return; - this.inProgress = true; + this.inProgress.set(true); this.profileService .changePassword({ - ...(!this.hideCurrentPassword && { currentPassword: this.form.get('password')?.value }), + ...(!this.hideCurrentPassword() && { currentPassword: this.form.get('password')?.value }), newPassword: this.form.get('newPassword')?.value, }) - .pipe(finalize(() => (this.inProgress = false))) + .pipe(finalize(() => this.inProgress.set(false))) .subscribe({ next: () => { this.form.reset(); @@ -95,8 +102,8 @@ export class ChangePasswordComponent life: 5000, }); - if (this.hideCurrentPassword) { - this.hideCurrentPassword = false; + if (this.hideCurrentPassword()) { + this.hideCurrentPassword.set(false); this.form.addControl('password', new UntypedFormControl('', [required])); } }, diff --git a/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.html b/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.html index 90ad0254af..ba415340b2 100644 --- a/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.html +++ b/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.html @@ -1,28 +1,28 @@

{{ 'AbpAccount::ForgotPassword' | abpLocalization }}

-@if (!isEmailSent) { +@if (!isEmailSent()) {

{{ 'AbpAccount::SendPasswordResetLink_Information' | abpLocalization }}

* + }} + *
{{ 'AbpAccount::Submit' | abpLocalization }} - {{ 'AbpAccount::Login' | abpLocalization }} + + + {{ 'AbpAccount::Login' | abpLocalization }} +
} @else {

diff --git a/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.ts b/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.ts index 5b00896acb..d77ecc3b2b 100644 --- a/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.ts +++ b/npm/ng-packs/packages/account/src/lib/components/forgot-password/forgot-password.component.ts @@ -1,5 +1,5 @@ import { AccountService } from '@abp/ng.account.core/proxy'; -import { Component, inject } from '@angular/core'; +import { Component, inject, signal, ChangeDetectionStrategy } from '@angular/core'; import { ReactiveFormsModule, UntypedFormBuilder, @@ -13,6 +13,7 @@ import { RouterLink } from '@angular/router'; import { NgxValidateCoreModule } from '@ngx-validate/core'; @Component({ + changeDetection: ChangeDetectionStrategy.OnPush, selector: 'abp-forgot-password', templateUrl: 'forgot-password.component.html', imports: [ @@ -29,9 +30,8 @@ export class ForgotPasswordComponent { form: UntypedFormGroup; - inProgress?: boolean; - - isEmailSent = false; + readonly inProgress = signal(false); + readonly isEmailSent = signal(false); constructor() { this.form = this.fb.group({ @@ -42,16 +42,16 @@ export class ForgotPasswordComponent { onSubmit() { if (this.form.invalid) return; - this.inProgress = true; + this.inProgress.set(true); this.accountService .sendPasswordResetCode({ email: this.form.get('email')?.value, appName: 'Angular', }) - .pipe(finalize(() => (this.inProgress = false))) + .pipe(finalize(() => this.inProgress.set(false))) .subscribe(() => { - this.isEmailSent = true; + this.isEmailSent.set(true); }); } } diff --git a/npm/ng-packs/packages/account/src/lib/components/login/login.component.html b/npm/ng-packs/packages/account/src/lib/components/login/login.component.html index 4919253456..d57c78b3db 100644 --- a/npm/ng-packs/packages/account/src/lib/components/login/login.component.html +++ b/npm/ng-packs/packages/account/src/lib/components/login/login.component.html @@ -7,7 +7,7 @@ }} } -

+
err); }), - finalize(() => (this.inProgress = false)), + finalize(() => this.inProgress.set(false)), ) .subscribe(); } diff --git a/npm/ng-packs/packages/account/src/lib/components/manage-profile/manage-profile.component.html b/npm/ng-packs/packages/account/src/lib/components/manage-profile/manage-profile.component.html index 410a1f7ccf..1ca3e1e457 100644 --- a/npm/ng-packs/packages/account/src/lib/components/manage-profile/manage-profile.component.html +++ b/npm/ng-packs/packages/account/src/lib/components/manage-profile/manage-profile.component.html @@ -1,24 +1,24 @@
-
+