Skip to main content
Version: Next

Application Service Contract Definition

Files referenced in this document

Table of Contents​

  1. Introduction
  2. Interface Inheritance and Extension
  3. Core Method Details
  4. Data Transfer Object (DTO) Design
  5. RESTful API Mapping
  6. Exception Handling Mechanism
  7. Import and Export Implementation
  8. Invocation Examples
  9. Dependencies and Architecture Diagram
  10. Conclusion

Introduction​

IMyEntityNameAppService is the core application service contract interface for managing MyEntityName entities in the CMS plugin system. This interface extends the ICrudAppService from the ABP framework, providing complete CRUD (Create, Read, Update, Delete) operations, and additionally supports business functions such as batch cloning, sorting adjustment, and data import/export.

Through this interface, front-end or other clients can interact with backend services in a standardized way. All operations are encapsulated through DTOs (Data Transfer Objects), ensuring type safety and data consistency. The interface is exposed as RESTful API endpoints via controllers, supporting advanced query functions like pagination, sorting, and filtering.

Section sources

Interface Inheritance and Extension​

The IMyEntityNameAppService interface inherits from the ICrudAppService<TDto, TKey, TGetListInput, TCreateInput, TUpdateInput> generic interface provided by the ABP framework. The specific implementation is as follows:

public interface IMyEntityNameAppService : ICrudAppService<
    MyEntityNameDto,           // Data Transfer Object
    Guid,                      // Entity Primary Key Type
    GetMyEntityNamesInput,     // Query Input Parameters
    MyEntityNameCreateDto,     // Create Input Parameters
    MyEntityNameUpdateDto      // Update Input Parameters
>

This design naturally equips the service with the following standard operations:

  • GetAsync(id): Get a single entity by ID
  • GetListAsync(input): Get a list of entities with pagination
  • CreateAsync(input): Create a new entity
  • UpdateAsync(id, input): Update an existing entity
  • DeleteAsync(id): Delete an entity

Based on this, the interface further extends plugin-specific business methods, such as batch deletion, cloning, sort adjustment, import, and export.

Section sources

Core Method Details​

Standard CRUD Methods​

MethodInput ParametersReturn TypeDescription
GetAsyncGuid idTask<MyEntityNameDto>Get a single MyEntityName entity by unique identifier
GetListAsyncGetMyEntityNamesInput inputTask<PagedResultDto<MyEntityNameDto>>Paged query of MyEntityName list, supporting filtering and sorting
CreateAsyncMyEntityNameCreateDto inputTask<MyEntityNameDto>Create a new MyEntityName entity
UpdateAsyncGuid id, MyEntityNameUpdateDto inputTask<MyEntityNameDto>Update the MyEntityName entity with the specified ID
DeleteAsyncGuid idTaskDelete the MyEntityName entity with the specified ID

Extended Business Methods​

MethodInput ParametersReturn TypeDescription
CloneAsyncIEnumerable<Guid> idsTask<List<MyEntityNameDto>>Batch clone entities with specified IDs, appending "Copy" tag to names automatically
DeleteManyAsyncIEnumerable<Guid> idsTaskBatch delete multiple entities
AdjustSortAsyncGuid id, int sortTaskAdjust the sort value of a specified entity and automatically reorder others
ImportAsyncMyEntityNamesImportModel inputTaskImport MyEntityName data from Excel, supporting incremental updates
ExportAsyncGetMyEntityNamesInput inputTask<(Dictionary<string, object>, string)>Export data to Excel format, returning worksheet data and filename

Section sources

Data Transfer Object (DTO) Design​

MyEntityNameDto​

Represents the data transfer object for the MyEntityName entity, inheriting from ExtensibleEntityDto<Guid> and implementing IHasConcurrencyStamp for concurrency control.

Property Description:

  • Code: Code (String)
  • Name: Name (String)
  • Sort: Sort (Integer)
  • Remark: Remark (String)
  • IsDisabled: Is Disabled (Boolean)
  • ConcurrencyStamp: Concurrency Stamp (Used for Optimistic Locking)

Section sources

GetMyEntityNamesInput​

Query input parameters, inheriting from ExtensiblePagedAndSortedResultRequestDto, supporting pagination, sorting, and filtering.

Property Description:

  • Filter: General filter condition
  • Name: Exact query by name

Section sources

MyEntityNameCreateDto and MyEntityNameUpdateDto​

Used for create and update operations respectively, both inheriting from MyEntityNameCreateOrUpdateDtoBase.

Common Properties:

  • Code: Code
  • Name: Name
  • Remark: Remark

Specific Properties:

  • MyEntityNameCreateDto: Sort (Optional sort value), IsDisabled (Default false)
  • MyEntityNameUpdateDto: ConcurrencyStamp (Concurrency control stamp)

Section sources

Import and Export Models​

MyEntityNamesImportModel​

Used for Excel import, containing a list of MyEntityNameImportModel, where each model corresponds to a row of data.

MyEntityNamesExportModel​

Used for Excel export, defining export column names and widths, annotated via ExcelColumn attribute.

Section sources

RESTful API Mapping​

MyEntityNameController maps the IMyEntityNameAppService interface to standard RESTful API endpoints:

Diagram sources

Section sources

Exception Handling Mechanism​

The service may throw the following types of exceptions during execution:

  • UserFriendlyException: User-friendly exception, used to prompt specific error information to front-end users, such as:

    • Name already exists
    • Import data format error
    • Required field is empty

  • AbpValidationException: Parameter validation exception, automatically triggered by the ABP framework when input DTO does not conform to validation rules.

  • ConcurrencyException: Concurrency conflict exception, triggered when multiple users modify the same entity simultaneously (controlled via ConcurrencyStamp).

All exceptions are uniformly handled by the global exception filter (CMSExceptionFilter) and return standardized error responses.

Section sources

Import and Export Implementation​

Import Flow​

  1. Frontend uploads Excel file
  2. Backend reads data from "Configuration" worksheet
  3. Validate data integrity (duplicate names, required fields, etc.)
  4. Distinguish between insert and update operations
  5. Call CreateAsync or UpdateAsync for batch processing
  6. Transactional commit, rolling back entirely on any failure

Export Flow​

  1. Receive query parameters GetMyEntityNamesInput
  2. Call ExportAsync to get data
  3. Use MiniExcel library to fill template file
  4. Return FileStreamResult to download file

Diagram sources

Invocation Examples​

Get Entity List (GET)​

GET /api/v1/MyPluginName/MyEntityName?Filter=test&Sorting=Name&MaxResultCount=10&SkipCount=0
Authorization: Bearer <token>

Create Entity (POST)​

POST /api/v1/MyPluginName/MyEntityName
Content-Type: application/json
Authorization: Bearer <token>

{
  "code": "TEST001",
  "name": "Test Entity",
  "remark": "This is a test",
  "sort": 1
}

Batch Delete (DELETE)​

DELETE /api/v1/MyPluginName/MyEntityName
Content-Type: application/json
Authorization: Bearer <token>

["a1b2c3d4-e5f6-7890-1234-567890abcdef"]

Import Data (POST)​

POST /api/v1/MyPluginName/MyEntityName/Import
Content-Type: multipart/form-data
Authorization: Bearer <token>

File: data.xlsx

Export Data (GET)​

GET /api/v1/MyPluginName/MyEntityName/Export?Filter=ProductionEnv
Authorization: Bearer <token>

Section sources

Dependencies and Architecture Diagram​

Diagram sources

Conclusion​

The IMyEntityNameAppService interface implements standardized CRUD operations by inheriting from the ABP framework's ICrudAppService and extends practical functions such as cloning, sorting, and import/export on this basis. The interface design follows RESTful principles and encapsulates data through DTOs, ensuring type safety and maintainability.

The controller layer maps interface methods to HTTP endpoints, supporting multiple interaction methods such as JSON and file upload. The entire service adopts dependency injection and repository patterns, achieving decoupling of business logic and data access, facilitating testing and extension.

This interface provides a stable and predictable API contract for the frontend and is the core service contract for entity management in the plugin system.

Section sources

Last updated on