# Repository: abpframework/abp
# Stars: 14206

## .cursorrules

# ABP Framework – Cursor Rules
# Scope: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.
# Goal: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence),
# maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.

## Global Defaults
- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.
- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.
- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.
- Keep layers clean. Do not introduce forbidden dependencies between packages.

## Module / Package Architecture (Layering)
- Use a layered module structure with explicit dependencies:
  - *.Domain.Shared: constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects.
  - *.Domain: entities/aggregate roots, repository interfaces, domain services.
  - *.Application.Contracts: application service interfaces and DTOs.
  - *.Application: application service implementations.
  - *.EntityFrameworkCore / *.MongoDb: ORM integration packages depend on *.Domain only. MUST NOT depend on other layers.
  - *.HttpApi: REST controllers. MUST depend ONLY on *.Application.Contracts (NOT *.Application).
  - *.HttpApi.Client: remote client proxies. MUST depend ONLY on *.Application.Contracts.
  - *.Web: UI. MUST depend ONLY on *.HttpApi.
- Enforce dependency direction:
  - Web -> HttpApi -> Application.Contracts
  - Application -> Domain + Application.Contracts
  - Domain -> Domain.Shared
  - ORM integration -> Domain
- Do not leak web concerns into application/domain.

## Domain Layer – Entities & Aggregate Roots
- Define entities in the domain layer.
- Entities must be valid at creation:
  - Provide a primary constructor that enforces invariants.
  - Always include a protected parameterless constructor for ORMs.
  - Always initialize sub-collections in the primary constructor.
  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.
- Make members `virtual` where appropriate (ORM/proxy compatibility).
- Protect consistency:
  - Use non-public setters (private/protected/internal) when needed.
  - Provide meaningful domain methods for state transitions; prefer returning `this` from setters when applicable.
- Aggregate roots:
  - Always use a single `Id` property. Do NOT use composite keys.
  - Prefer `Guid` keys for aggregate roots.
  - Inherit from `AggregateRoot<TKey>` or audited base classes as required.
- Aggregate boundaries:
  - Keep aggregates small. Avoid large sub-collections unless necessary.
- References:
  - Reference other aggregate roots by Id only.
  - Do NOT add navigation properties to other aggregate roots.

## Repositories
- Define repository interfaces in the domain layer.
- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).
- Public repository interfaces exposed by modules:
  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).
  - SHOULD NOT expose `IQueryable` in the public contract.
  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.
- Do NOT define repositories for non-aggregate-root entities.
- Repository method conventions:
  - All methods async.
  - Include optional `CancellationToken cancellationToken = default` in every method.
  - For single-entity returning methods: include `bool includeDetails = true`.
  - For list returning methods: include `bool includeDetails = false`.
  - Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.
  - Avoid projection-only view models from repositories by default; only allow when performance is critical.

## Domain Services
- Define domain services in the domain layer.
- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).
- Naming: use `*Manager` suffix.
- Domain service methods:
  - Focus on operations that enforce domain invariants and business rules.
  - Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.
  - Define methods that mutate state and enforce domain rules.
  - Use specific, intention-revealing names (avoid generic `UpdateXAsync`).
  - Accept valid domain objects as parameters; do NOT accept/return DTOs.
  - On rule violations, throw `BusinessException` (or custom business exceptions).
  - Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).
  - Do NOT depend on authenticated user logic; pass required values from application layer.

## Application Services (Contracts + Implementation)
### Contracts
- Define one interface per application service in *.Application.Contracts.
- Interfaces must inherit from `IApplicationService`.
- Naming: `I*AppService`.
- Do NOT accept/return entities. Use DTOs and primitive parameters.

### Method Naming & Shapes
- All service methods async and end with `Async`.
- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).
- Standard CRUD:
  - `GetAsync(Guid id)` returns a detailed DTO.
  - `GetListAsync(QueryDto queryDto)` returns a list of detailed DTOs.
  - `CreateAsync(CreateDto dto)` returns detailed DTO.
  - `UpdateAsync(Guid id, UpdateDto dto)` returns detailed DTO (id MUST NOT be inside update DTO).
  - `DeleteAsync(Guid id)` returns void/Task.
- `GetListAsync` query DTO:
  - Filtering/sorting/paging fields optional with defaults.
  - Enforce a maximum page size for performance.

### DTO Usage
- Inputs:
  - Do not include unused properties.
  - Do NOT share input DTOs between methods.
  - Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).

### Implementation
- Application layer must be independent of web.
- Implement interfaces in *.Application, name `ProductAppService` for `IProductAppService`.
- Inherit from `ApplicationService`.
- Make all public methods `virtual`.
- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.
- Data access:
  - Use dedicated repositories (e.g., `IProductRepository`).
  - Do NOT use generic repositories.
  - Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.
- Entity mutation:
  - Load required entities from repositories.
  - Mutate using domain methods.
  - Call repository `UpdateAsync` after updates (do not assume change tracking).
- Extra properties:
  - Use `MapExtraPropertiesTo` or configure object mapper for `MapExtraProperties`.
- Files:
  - Do NOT use web types like `IFormFile` or `Stream` in application services.
  - Controllers handle upload; pass `byte[]` (or similar) to application services.
- Cross-application-service calls:
  - Do NOT call other application services within the same module.
  - For reuse, push logic into domain layer or extract shared helpers carefully.
  - You MAY call other modules’ application services only via their Application.Contracts.

## DTO Conventions
- Define DTOs in *.Application.Contracts.
- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).
- For aggregate roots, prefer extensible DTO base types so extra properties can map.
- DTO properties: public getters/setters.
- Input DTO validation:
  - Use data annotations.
  - Reuse constants from Domain.Shared wherever possible.
- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.
- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.
- Output DTO strategy:
  - Prefer a Basic DTO and a Detailed DTO; avoid many variants.
  - Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.

## EF Core Integration
- Define a separate DbContext interface + class per module.
- Do NOT rely on lazy loading; do NOT enable lazy loading.
- DbContext interface:
  - Inherit from `IEfCoreDbContext`.
  - Add `[ConnectionStringName("...")]`.
  - Expose `DbSet<TEntity>` ONLY for aggregate roots.
  - Do NOT include setters in the interface.
- DbContext class:
  - Inherit `AbpDbContext<TDbContext>`.
  - Add `[ConnectionStringName("...")]` and implement the interface.
- Table prefix/schema:
  - Provide static `TablePrefix` and `Schema` defaulted from constants.
  - Use short prefixes; `Abp` prefix reserved for ABP core modules.
  - Default schema should be `null`.
- Model mapping:
  - Do NOT configure entities directly inside `OnModelCreating`.
  - Create `ModelBuilder` extension method `ConfigureX()` and call it.
  - Call `b.ConfigureByConvention()` for each entity.
- Repository implementations:
  - Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.
  - Use DbContext interface as generic parameter.
  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.
  - Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.
  - Override `WithDetailsAsync()` where needed.

## MongoDB Integration
- Define a separate MongoDbContext interface + class per module.
- MongoDbContext interface:
  - Inherit from `IAbpMongoDbContext`.
  - Add `[ConnectionStringName("...")]`.
  - Expose `IMongoCollection<TEntity>` ONLY for aggregate roots.
- MongoDbContext class:
  - Inherit `AbpMongoDbContext` and implement the interface.
- Collection prefix:
  - Provide static `CollectionPrefix` defaulted from constants.
  - Use short prefixes; `Abp` prefix reserved for ABP core modules.
- Mapping:
  - Do NOT configure directly inside `CreateModel`.
  - Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.
- Repository implementations:
  - Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.
  - Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.
  - Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).
  - Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.

## ABP Module Classes
- Every package must have exactly one `AbpModule` class.
- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).
- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.
- Override `ConfigureServices` for DI registration and configuration.
- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.
- Each module must be usable standalone; avoid hidden cross-module coupling.

## Framework Extensibility
- All public and protected members should be `virtual` for inheritance-based extensibility.
- Prefer `protected virtual` over `private` for helper methods to allow overriding.
- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.
- Provide extension points via interfaces and virtual methods.
- Document extension points with XML comments explaining intended usage.
- Consider providing `*Options` classes for configuration-based extensibility.

## Backward Compatibility
- Do NOT remove or rename public API members without a deprecation cycle.
- Use `[Obsolete("Message. Use X instead.")]` with clear migration guidance before removal.
- Maintain binary and source compatibility within major versions.
- Add new optional parameters with defaults; do not change existing method signatures.
- When adding new abstract members to base classes, provide default implementations if possible.
- Prefer adding new interfaces over modifying existing ones.

## Localization Resources
- Define localization resources in Domain.Shared.
- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).
- JSON files under `/Localization/[ModuleName]/` directory.
- Use `LocalizableString.Create<TResource>("Key")` for localizable exceptions and messages.
- All user-facing strings must be localized; no hardcoded English text in code.
- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).

## Settings & Features
- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.
- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.
- Define features in `*FeatureDefinitionProvider` in Domain.Shared.
- Feature names must follow `[ModuleName].[FeatureName]` convention.
- Use constants for setting/feature names; never hardcode strings.

## Permissions
- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.
- Permission names must follow `[ModuleName].[Permission]` convention.
- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).
- Group related permissions logically.

## Event Bus & Distributed Events
- Use `ILocalEventBus` for intra-module communication within the same process.
- Use `IDistributedEventBus` for cross-module or cross-service communication.
- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.
- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).
- Event handlers belong in the Application layer.
- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.

## Testing
- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.
- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.
- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.
- Test modules should use `[DependsOn]` on the module under test.
- Use `Shouldly` assertions (ABP convention).
- Test both EF Core and MongoDB implementations when the module supports both.
- Include tests for permission checks, validation, and edge cases.
- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.

## Contribution Discipline (PR / Issues / Tests)
- Before significant changes, align via GitHub issue/discussion.
- PRs:
  - Keep changes scoped and reviewable.
  - Add/update unit/integration tests relevant to the change.
  - Build and run tests for the impacted area when possible.
- Localization:
  - Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).

## Review Checklist
- Layer dependencies respected (no forbidden references).
- No `IQueryable` or generic repository usage leaking into application/domain.
- Entities maintain invariants; Guid id generation not inside constructors.
- Repositories follow async + CancellationToken + includeDetails conventions.
- No web types in application services.
- DTOs in contracts, serializable, validated, minimal, no logic.
- EF/Mongo integration follows context + mapping + repository patterns.
- Minimal diff; no unnecessary API surface expansion.


## README.md

 
![build and test](https://img.shields.io/github/actions/workflow/status/abpframework/abp/build-and-test.yml?branch=dev&style=flat-square) 🔹 [![codecov](https://codecov.io/gh/abpframework/abp/branch/dev/graph/badge.svg?token=jUKLCxa6HF)](https://codecov.io/gh/abpframework/abp) 🔹 [![NuGet](https://img.shields.io/nuget/v/Volo.Abp.Core.svg?style=flat-square)](https://www.nuget.org/packages/Volo.Abp.Core) 🔹 [![NuGet (with prereleases)](https://img.shields.io/nuget/vpre/Volo.Abp.Core.svg?style=flat-square)](https://www.nuget.org/packages/Volo.Abp.Core) 🔹 [![MyGet (nightly builds)](https://img.shields.io/myget/abp-nightly/vpre/Volo.Abp.svg?style=flat-square)](https://abp.io/docs/latest/release-info/nightly-builds) 🔹 
[![NuGet Download](https://img.shields.io/nuget/dt/Volo.Abp.Core.svg?style=flat-square)](https://www.nuget.org/packages/Volo.Abp.Core) 🔹 [![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](https://github.com/abpframework/abp/blob/dev/CODE_OF_CONDUCT.md) 🔹 [![CLA Signed](https://cla-assistant.io/readme/badge/abpframework/abp)](https://cla-assistant.io/abpframework/abp) 🔹 [![Discord Shield](https://discord.com/api/guilds/951497912645476422/widget.png?style=shield)](https://abp.io/join-discord)

[ABP](https://abp.io/) offers an **opinionated architecture** to build enterprise software solutions with **best practices** on top of the **.NET** and the **ASP.NET Core** platforms. It provides the fundamental infrastructure, production-ready startup templates, pre-built application modules, UI themes, tooling, guides and documentation to implement that architecture properly and **automate the details** and repetitive works as much as possible.

[![ABP Platform](https://github.com/user-attachments/assets/c4356ec7-4d0f-4e00-a1d2-fc74ad985fb8)](https://abp.io) 
 


## Getting Started

- [The Getting Started guide](https://abp.io/docs/latest/get-started) can be used to create and run ABP-based solutions with different options and details.
- [Quick Start](https://abp.io/docs/latest/tutorials/todo) is a single-part, quick-start tutorial to build a simple application with the ABP Framework. Start with this tutorial if you want to understand how ABP works quickly.
- [Web Application Development Tutorial](https://abp.io/docs/latest/tutorials/book-store) is a complete tutorial on developing a full-stack web application with all aspects of a real-life solution.
- [Modular Monolith Application](https://abp.io/docs/latest/tutorials/modular-crm/index): A multi-part tutorial that demonstrates how to create application modules, compose and communicate them to build a monolith modular web application.
- [Microservice Tutorial](https://abp.io/docs/latest/tutorials/microservice/index): A multi-part guide that walks you through building a microservice solution with ABP, from creating independent services and enabling inter-service communication to exposing them through an API Gateway and generating CRUD pages with ABP Suite.

## What ABP Provides?

ABP bridges the gap between ASP.NET Core and real-world business application requirements, and makes you focus on your own business code.

The following diagram contains the core components of the **ABP Platform** and shows how ABP sits between **ASP.NET Core** and **Your Application**:

![abp-overall-diagram](docs/en/images/abp-overall-diagram.png)

### Architecture

ABP offers a complete architectural model to build modern enterprise software solutions. Here, the fundamental architectural structures offered and first-class supported by ABP:

* [Domain Driven Design (DDD)](https://abp.io/docs/latest/framework/architecture/domain-driven-design)
* [Microservices](https://abp.io/docs/latest/framework/architecture/microservices)
* [Modularity](https://abp.io/docs/latest/framework/architecture/modularity/basics)
* [Multi-Tenancy](https://abp.io/docs/latest/framework/architecture/multi-tenancy)

### Infrastructure

There are a lot of infrastructure features provided by the ABP Framework to achieve real-world scenarios easier, like [Event Bus](https://abp.io/docs/latest/framework/infrastructure/event-bus), [Background Job System](https://abp.io/docs/latest/framework/infrastructure/background-jobs), [Audit Logging](https://abp.io/docs/latest/framework/infrastructure/audit-logging), [BLOB Storing](https://abp.io/docs/latest/framework/infrastructure/blob-storing), [Data Seeding](https://abp.io/docs/latest/framework/infrastructure/data-seeding), [Data Filtering](https://abp.io/docs/latest/framework/infrastructure/data-filtering), and much more.

[See ABP Framework features](https://abp.io/framework)

#### Cross-Cutting Concerns

ABP also simplifies (and even automates wherever possible) cross-cutting concerns and common non-functional requirements like [Exception Handling](https://abp.io/docs/latest/framework/fundamentals/exception-handling), [Validation](https://abp.io/docs/latest/framework/fundamentals/validation), [Authorization](https://abp.io/docs/latest/framework/fundamentals/authorizationn), [Localization](https://abp.io/docs/latest/framework/fundamentals/localization), [Caching](https://abp.io/docs/latest/framework/fundamentals/caching), [Dependency Injection](https://abp.io/docs/latest/framework/fundamentals/dependency-injection), [Setting Management](https://abp.io/docs/latest/framework/infrastructure/settings), etc.

### Application Modules

ABP is a modular framework and the [application modules](https://abp.io/modules) provide **pre-built application functionalities**. 

Some examples:

- [**Account**](https://abp.io/modules/Volo.Account.Pro): Provides UI for the account management and allows user to login/register to the application.
- [CMS Kit](https://abp.io/modules/Volo.CmsKit):  Brings CMS (Content Management System) capabilities to your application.
- **[Identity](https://abp.io/modules/Volo.Identity.Pro)**: Manages organization units, roles, users and their permissions based on the Microsoft Identity library.
- [**OpenIddict**](https://abp.io/modules/Volo.OpenIddict.Pro): Integrates to OpenIddict library and provides a management UI.
- [**SaaS**](https://abp.io/modules/Volo.Saas): Manages tenants and editions for a [multi-tenant](https://abp.io/docs/latest/framework/architecture/multi-tenancy) (SaaS) application.

See [all official modules](https://abp.io/modules).

### Startup Templates

The [Startup templates](https://abp.io/docs/latest/solution-templates) are pre-built Visual Studio solution templates. You can create your own solution based on these templates to **immediately start your development**.

### Tooling

ABP provides CLI and UI tools to simplify your daily development work flows.

#### ABP Studio

[ABP Studio](https://abp.io/studio) is a cross-platform desktop application for ABP developers.

It is well integrated to the ABP Framework and aims to provide a comfortable development environment for you by automating things, providing insights about your solution, making develop, run and deploy your solutions much easier.

#### ABP Suite

[ABP Suite](https://abp.io/suite) allows you to automatically generate web pages in a matter of minutes.

#### ABP CLI

[ABP CLI](https://abp.io/cli) is a command line tool to perform common operations for ABP based solutions.

## Mastering ABP Framework Book

This book will help you to gain a complete understanding of the ABP Framework and modern web application development techniques. It is written by the creator and team lead of the ABP Framework. You can buy from [Amazon](https://www.amazon.com/gp/product/B097Z2DM8Q) or [Packt Publishing](https://www.packtpub.com/product/mastering-abp-framework/9781801079242). Find further info about the book at [abp.io/books/mastering-abp-framework](https://abp.io/books/mastering-abp-framework).

![book-mastering-abp-framework](docs/en/images/book-mastering-abp-framework.png)



## The Community

### ABP Community Web Site

The [ABP Community](https://abp.io/community) is a central hub to publish **articles** and share **knowledge** about the ABP Framework.

### Blog

Follow the [ABP Blog](https://abp.io/blog) to learn the latest happenings in the ABP Framework.

### Samples

See the [sample projects](https://abp.io/docs/latest/samples) built with the ABP Framework.

### Want to Contribute?

ABP is a community-driven open-source project. See [the contribution guide](https://abp.io/docs/latest/contribution) if you want to participate in this project.

## Official Links

* [Home Website](https://abp.io)
  * [Get Started](https://abp.io/get-started)
  * [Features](https://abp.io/framework)
* [Documents](https://abp.io/docs/latest)
* [Samples](https://abp.io/docs/latest/samples)
* [Blog](https://abp.io/blog)
* [Community](https://abp.io/community)
* [Stackoverflow](https://stackoverflow.com/questions/tagged/abp)
* [Twitter](https://twitter.com/abpframework)

## Support ABP

GitHub repository stars are an important indicator of popularity and the size of the community. If you like ABP Framework, support us by clicking the star :star: on the repository.

## Discord Server

We have a Discord server where you can chat with other ABP users. Share your ideas, report technical issues, showcase your creations, share the tips that worked for you and catch up with the latest news and announcements about ABP Framework. Join 👉 https://abp.io/join-discord.