Copilot instructions

1# ABP Framework – GitHub Copilot Instructions
2 
3> **Scope**: ABP Framework repository (abpframework/abp) — for developing ABP itself, not ABP-based applications.
4>
5> **Goal**: Enforce ABP module architecture best practices (DDD, layering, DB/ORM independence), maintain backward compatibility, ensure extensibility, and align with ABP contribution guidelines.
6 
7---
8 
9## Global Defaults
10 
11- Follow existing patterns in this repository first. Before generating new code, search for similar implementations and mirror their structure, naming, and conventions.
12- Prefer minimal, focused diffs. Avoid drive-by refactors and formatting churn.
13- Preserve public APIs. Avoid breaking changes unless explicitly requested and justified.
14- Keep layers clean. Do not introduce forbidden dependencies between packages.
15 
16---
17 
18## Module / Package Architecture (Layering)
19 
20Use a layered module structure with explicit dependencies:
21 
22| Layer | Purpose | Allowed Dependencies |
23|-------|---------|---------------------|
24| `*.Domain.Shared` | Constants, enums, shared types safe for all layers and 3rd-party clients. MUST NOT contain entities, repositories, domain services, or business objects. | None |
25| `*.Domain` | Entities/aggregate roots, repository interfaces, domain services. | Domain.Shared |
26| `*.Application.Contracts` | Application service interfaces and DTOs. | Domain.Shared |
27| `*.Application` | Application service implementations. | Domain, Application.Contracts |
28| `*.EntityFrameworkCore` / `*.MongoDb` | ORM integration packages. MUST NOT depend on other layers. | Domain only |
29| `*.HttpApi` | REST controllers. MUST depend ONLY on Application.Contracts (NOT Application). | Application.Contracts |
30| `*.HttpApi.Client` | Remote client proxies. MUST depend ONLY on Application.Contracts. | Application.Contracts |
31| `*.Web` | UI layer. MUST depend ONLY on HttpApi. | HttpApi |
32 
33### Dependency Direction
34```
35Web -> HttpApi -> Application.Contracts
36Application -> Domain + Application.Contracts
37Domain -> Domain.Shared
38ORM integration -> Domain
39```
40 
41Do not leak web concerns into application/domain.
42 
43---
44 
45## Domain Layer – Entities & Aggregate Roots
46 
47- Define entities in the domain layer.
48- Entities must be valid at creation:
49  - Provide a primary constructor that enforces invariants.
50  - Always include a `protected` parameterless constructor for ORMs.
51  - Always initialize sub-collections in the primary constructor.
52  - Do NOT generate Guid keys inside constructors; accept `id` and generate using `IGuidGenerator` from the calling code.
53- Make members `virtual` where appropriate (ORM/proxy compatibility).
54- Protect consistency:
55  - Use non-public setters (`private`/`protected`/`internal`) when needed.
56  - Provide meaningful domain methods for state transitions.
57 
58### Aggregate Roots
59- Always use a single `Id` property. Do NOT use composite keys.
60- Prefer `Guid` keys for aggregate roots.
61- Inherit from `AggregateRoot<TKey>` or audited base classes as required.
62- Keep aggregates small. Avoid large sub-collections unless necessary.
63 
64### References
65- Reference other aggregate roots by Id only.
66- Do NOT add navigation properties to other aggregate roots.
67 
68---
69 
70## Repositories
71 
72- Define repository interfaces in the domain layer.
73- Create one dedicated repository interface per aggregate root (e.g., `IProductRepository`).
74- Public repository interfaces exposed by modules:
75  - SHOULD inherit from `IBasicRepository<TEntity, TKey>` (or `IReadOnlyRepository<...>` when suitable).
76  - SHOULD NOT expose `IQueryable` in the public contract.
77  - Internal implementations MAY use `IRepository<TEntity, TKey>` and `IQueryable` as needed.
78- Do NOT define repositories for non-aggregate-root entities.
79 
80### Method Conventions
81- All methods async.
82- Include optional `CancellationToken cancellationToken = default` in every method.
83- For single-entity returning methods: include `bool includeDetails = true`.
84- For list returning methods: include `bool includeDetails = false`.
85- Do NOT return composite projection classes like `UserWithRoles`. Use `includeDetails` for eager-loading.
86- Avoid projection-only view models from repositories by default; only allow when performance is critical.
87 
88---
89 
90## Domain Services
91 
92- Define domain services in the domain layer.
93- Default: do NOT create interfaces for domain services unless necessary (mocking/multiple implementations).
94- Naming: use `*Manager` suffix.
95 
96### Method Guidelines
97- Focus on operations that enforce domain invariants and business rules.
98- Query methods are acceptable when they encapsulate domain-specific lookup logic (e.g., normalized lookups, caching, complex resolution). Simple queries belong in repositories.
99- Define methods that mutate state and enforce domain rules.
100- Use specific, intention-revealing names (avoid generic `UpdateXAsync`).
101- Accept valid domain objects as parameters; do NOT accept/return DTOs.
102- On rule violations, throw `BusinessException` (or custom business exceptions).
103- Use unique, namespaced error codes suitable for localization (e.g., `IssueTracking:ConcurrentOpenIssueLimit`).
104- Do NOT depend on authenticated user logic; pass required values from application layer.
105 
106---
107 
108## Application Services
109 
110### Contracts
111- Define one interface per application service in `*.Application.Contracts`.
112- Interfaces must inherit from `IApplicationService`.
113- Naming: `I*AppService`.
114- Do NOT accept/return entities. Use DTOs and primitive parameters.
115 
116### Method Naming & Shapes
117- All service methods async and end with `Async`.
118- Do not repeat entity names in method names (use `GetAsync`, not `GetProductAsync`).
119 
120**Standard CRUD:**
121```csharp
122Task<ProductDto> GetAsync(Guid id);
123Task<PagedResultDto<ProductDto>> GetListAsync(GetProductListInput input);
124Task<ProductDto> CreateAsync(CreateProductInput input);
125Task<ProductDto> UpdateAsync(Guid id, UpdateProductInput input);  // id NOT inside DTO
126Task DeleteAsync(Guid id);
127```
128 
129### DTO Usage (Inputs)
130- Do not include unused properties.
131- Do NOT share input DTOs between methods.
132- Do NOT use inheritance between input DTOs (except rare abstract base DTO cases; be very cautious).
133 
134### Implementation
135- Application layer must be independent of web.
136- Implement interfaces in `*.Application`, name `ProductAppService` for `IProductAppService`.
137- Inherit from `ApplicationService`.
138- Make all public methods `virtual`.
139- Avoid private helper methods; prefer `protected virtual` helpers for extensibility.
140 
141### Data Access
142- Use dedicated repositories (e.g., `IProductRepository`).
143- Do NOT put LINQ/SQL queries inside application service methods; repositories perform queries.
144 
145### Entity Mutation
146- Load required entities from repositories.
147- Mutate using domain methods.
148- Call repository `UpdateAsync` after updates (do not assume change tracking).
149 
150### Files
151- Do NOT use web types like `IFormFile` or `Stream` in application services.
152- Controllers handle upload; pass `byte[]` (or similar) to application services.
153 
154### Cross-Service Calls
155- Do NOT call other application services within the same module.
156- For reuse, push logic into domain layer or extract shared helpers carefully.
157- You MAY call other modules' application services only via their Application.Contracts.
158 
159---
160 
161## DTO Conventions
162 
163- Define DTOs in `*.Application.Contracts`.
164- Prefer ABP base DTO types (`EntityDto<TKey>`, audited DTOs).
165- For aggregate roots, prefer extensible DTO base types so extra properties can map.
166- DTO properties: public getters/setters.
167 
168### Input DTO Validation
169- Use data annotations.
170- Reuse constants from Domain.Shared wherever possible.
171 
172### General Rules
173- Avoid logic in DTOs; only implement `IValidatableObject` when necessary.
174- Do NOT use `[Serializable]` attribute (BinaryFormatter is obsolete); ABP uses JSON serialization.
175 
176### Output DTO Strategy
177- Prefer a Basic DTO and a Detailed DTO; avoid many variants.
178- Detailed DTOs: include reference details as nested basic DTOs; avoid duplicating raw FK ids unnecessarily.
179 
180---
181 
182## EF Core Integration
183 
184- Define a separate DbContext interface + class per module.
185- Do NOT rely on lazy loading; do NOT enable lazy loading.
186 
187### DbContext Interface
188```csharp
189[ConnectionStringName("ModuleName")]
190public interface IModuleNameDbContext : IEfCoreDbContext
191{
192    DbSet<Product> Products { get; }  // No setters, aggregate roots only
193}
194```
195 
196### DbContext Class
197```csharp
198[ConnectionStringName("ModuleName")]
199public class ModuleNameDbContext : AbpDbContext<ModuleNameDbContext>, IModuleNameDbContext
200{
201    public static string TablePrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;
202    public static string? Schema { get; set; } = ModuleNameConsts.DefaultDbSchema;
203    
204    public DbSet<Product> Products { get; set; }
205}
206```
207 
208### Table Prefix/Schema
209- Provide static `TablePrefix` and `Schema` defaulted from constants.
210- Use short prefixes; `Abp` prefix reserved for ABP core modules.
211- Default schema should be `null`.
212 
213### Model Mapping
214- Do NOT configure entities directly inside `OnModelCreating`.
215- Create `ModelBuilder` extension method `ConfigureX()` and call it.
216- Call `b.ConfigureByConvention()` for each entity.
217 
218### Repository Implementations
219- Inherit from `EfCoreRepository<TDbContextInterface, TEntity, TKey>`.
220- Use DbContext interface as generic parameter.
221- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.
222- Implement `IncludeDetails(include)` extension per aggregate root with sub-collections.
223- Override `WithDetailsAsync()` where needed.
224 
225---
226 
227## MongoDB Integration
228 
229- Define a separate MongoDbContext interface + class per module.
230 
231### MongoDbContext Interface
232```csharp
233[ConnectionStringName("ModuleName")]
234public interface IModuleNameMongoDbContext : IAbpMongoDbContext
235{
236    IMongoCollection<Product> Products { get; }  // Aggregate roots only
237}
238```
239 
240### MongoDbContext Class
241```csharp
242public class ModuleNameMongoDbContext : AbpMongoDbContext, IModuleNameMongoDbContext
243{
244    public static string CollectionPrefix { get; set; } = ModuleNameConsts.DefaultDbTablePrefix;
245}
246```
247 
248### Mapping
249- Do NOT configure directly inside `CreateModel`.
250- Create `IMongoModelBuilder` extension method `ConfigureX()` and call it.
251 
252### Repository Implementations
253- Inherit from `MongoDbRepository<TMongoDbContextInterface, TEntity, TKey>`.
254- Pass cancellation tokens using `GetCancellationToken(cancellationToken)`.
255- Ignore `includeDetails` for MongoDB in most cases (documents load sub-collections).
256- Prefer `GetQueryableAsync()` to ensure ABP data filters are applied.
257 
258---
259 
260## ABP Module Classes
261 
262- Every package must have exactly one `AbpModule` class.
263- Naming: `Abp[ModuleName][Layer]Module` (e.g., `AbpIdentityDomainModule`, `AbpIdentityApplicationModule`).
264- Use `[DependsOn(typeof(...))]` to declare module dependencies explicitly.
265- Override `ConfigureServices` for DI registration and configuration.
266- Override `OnApplicationInitialization` sparingly; prefer `ConfigureServices` when possible.
267- Each module must be usable standalone; avoid hidden cross-module coupling.
268 
269---
270 
271## Framework Extensibility
272 
273- All public and protected members should be `virtual` for inheritance-based extensibility.
274- Prefer `protected virtual` over `private` for helper methods to allow overriding.
275- Use `[Dependency(ReplaceServices = true)]` patterns for services intended to be replaceable.
276- Provide extension points via interfaces and virtual methods.
277- Document extension points with XML comments explaining intended usage.
278- Consider providing `*Options` classes for configuration-based extensibility.
279 
280---
281 
282## Backward Compatibility
283 
284- Do NOT remove or rename public API members without a deprecation cycle.
285- Use `[Obsolete("Message. Use X instead.")]` with clear migration guidance before removal.
286- Maintain binary and source compatibility within major versions.
287- Add new optional parameters with defaults; do not change existing method signatures.
288- When adding new abstract members to base classes, provide default implementations if possible.
289- Prefer adding new interfaces over modifying existing ones.
290 
291---
292 
293## Localization Resources
294 
295- Define localization resources in Domain.Shared.
296- Resource class naming: `[ModuleName]Resource` (e.g., `IdentityResource`, `PermissionManagementResource`).
297- JSON files under `/Localization/[ModuleName]/` directory.
298- Use `LocalizableString.Create<TResource>("Key")` for localizable exceptions and messages.
299- All user-facing strings must be localized; no hardcoded English text in code.
300- Error codes should be namespaced: `ModuleName:ErrorCode` (e.g., `Identity:UserNameAlreadyExists`).
301 
302---
303 
304## Settings & Features
305 
306- Define settings in `*SettingDefinitionProvider` in Domain.Shared or Domain.
307- Setting names must follow `Abp.[ModuleName].[SettingName]` convention.
308- Define features in `*FeatureDefinitionProvider` in Domain.Shared.
309- Feature names must follow `[ModuleName].[FeatureName]` convention.
310- Use constants for setting/feature names; never hardcode strings.
311 
312---
313 
314## Permissions
315 
316- Define permissions in `*PermissionDefinitionProvider` in Application.Contracts.
317- Permission names must follow `[ModuleName].[Permission]` convention.
318- Use constants for permission names (e.g., `IdentityPermissions.Users.Create`).
319- Group related permissions logically.
320 
321---
322 
323## Event Bus & Distributed Events
324 
325- Use `ILocalEventBus` for intra-module communication within the same process.
326- Use `IDistributedEventBus` for cross-module or cross-service communication.
327- Define Event Transfer Objects (ETOs) in Domain.Shared for distributed events.
328- ETO naming: `[EntityName][Action]Eto` (e.g., `UserCreatedEto`, `OrderCompletedEto`).
329- Event handlers belong in the Application layer.
330- ETOs should be simple, serializable, and contain only primitive types or nested ETOs.
331 
332---
333 
334## Testing
335 
336- Unit tests: `*.Tests` projects for isolated logic testing with mocked dependencies.
337- Integration tests: `*.EntityFrameworkCore.Tests` / `*.MongoDB.Tests` for repository and DB tests.
338- Use `AbpIntegratedTest<TModule>` or `AbpApplicationTestBase<TModule>` base classes.
339- Test modules should use `[DependsOn]` on the module under test.
340- Use `Shouldly` assertions (ABP convention).
341- Test both EF Core and MongoDB implementations when the module supports both.
342- Include tests for permission checks, validation, and edge cases.
343- Name test methods: `MethodName_Scenario_ExpectedResult` or `Should_ExpectedBehavior_When_Condition`.
344 
345---
346 
347## Contribution Discipline (PR / Issues / Tests)
348 
349- Before significant changes, align via GitHub issue/discussion.
350 
351### PRs
352- Keep changes scoped and reviewable.
353- Add/update unit/integration tests relevant to the change.
354- Build and run tests for the impacted area when possible.
355 
356### Localization
357- Prefer the `abp translate` workflow for adding missing translations (generate `abp-translation.json`, fill, apply, then PR).
358 
359---
360 
361## Review Checklist
362 
363- [ ] Layer dependencies respected (no forbidden references).
364- [ ] No `IQueryable` leaking into public repository contracts.
365- [ ] Entities maintain invariants; Guid id generation not inside constructors.
366- [ ] Repositories follow async + CancellationToken + includeDetails conventions.
367- [ ] No web types in application services.
368- [ ] DTOs in contracts, validated, minimal, no logic.
369- [ ] EF/Mongo integration follows context + mapping + repository patterns.
370- [ ] Public members are `virtual` for extensibility.
371- [ ] Backward compatibility maintained; no breaking changes without deprecation.
372- [ ] Minimal diff; no unnecessary API surface expansion.
373