It is not proper to implement this rule in the Application Service, because it is a core business (domain) rule that should always be checked. Sometimes, it seems appealing to reuse the same DTO class for two use cases, because they are almost same.

You typically want to use the full power of the SQL Server or even use a separate data source (like ElasticSearch) for reporting purpose. Example: Returning Different DTO types from different methods, (We didn't use async methods to make the example cleaner, but use async in your real world application!). It is a useful utility application that you can use it in development as well as in production environment. This requirement is not necessary when you use relational databases and ORMs. This rule seems unnecessary first. There can be different types of the use cases directly or indirectly changes an entity. Otherwise, some properties are not used in some cases and this violates the rule defined above: Do not Define Unused Properties for Input DTOs. In these cases, you may want to create specialized output DTOs with minimal information. Assume that we have another specification that returns true only if the Issue is in a Milestone: This Specification is parametric as a difference from the InActiveIssueSpecification. First, we can make the Issue constructor internal, instead of public: This prevents Application Services to directly use the constructor, so they will use the IssueManager. They are seen as details and the business layers should not depend on them. _issueRepository.GetAsync method gets an optional parameter, includeDetails, that you can pass false to disable this behavior when you need it. For example, let's say that we want to add an bool IsInActive() method on the Issue entity. This repository works with such an Issue class: (the code shows only the properties we need for this example), The rule says the repository shouldn't know the business rules. Even if they are same now, they will probably become different by the time and you will come to the same problem. If you do that, you find a copy of the destination aggregate object in the database collection of the source aggregate since it is being serialized to JSON on save. While the implementation details rely on the ABP Framework infrastructure, core concepts, principles and patterns are applicable in any kind of solution, even if it is not a .NET solution. The suggestions above are especially for applications where maintaining the codebase is more important than negligible performance lost.

The sub sections below explains the projects in the solution; Your solution structure may be slightly different if you choose a different UI or Database provider. Let's see the CreateAsync method step by step to discuss if the code part should be in the Application Service, or not; Discussion: Why don't we move the payment logic into the domain service? Example: Creating a new Organization in a Domain Service. In these cases; Issue class throws an IssueStateException in these cases to force the business rules: There are two potential problems of throwing such exceptions; ABP's Exception Handling system solves these and similar problems. An aggregate should maintain its self integrity and validity by implementing domain rules and constraints. If a use case works with a single aggregate, reads and saves it as a single unit, all the changes made to the aggregate objects are saved together as an atomic operation and you don't need to an explicit database transaction. Once your application grows, it will be hard to follow these rules. The figure below shows some of the aggregates, aggregate roots, entities, value object and the relations between them: Issue Aggregate consists of an Issue Aggregate Root that contains Comment and IssueLabel collections. Now, we can explain the reasons of the dependencies; When you investigate the solution, you will see two more dependencies shown with the dashed lines in the figure above. They should only depend on the Repository interfaces and the Repository interfaces don't use any ORM specific objects. An entity (that's not the aggregate root) in an aggregate can use a composite primary key. It is just a demo application and you can safely delete it. For this example, a simple question can help us to make the decision: "If we have another way (use case) of creating an issue, should we still apply the same rule? So, when you get an aggregate, all the sub-collections are already retrieved as a part of the query, without any additional configuration. (we will discuss the difference later with more details). However, the Domain and Application layers will be same and this is the essential point for the DDD perspective. However, the saved time in the short term will bring much more time loss in the middle and long term. So, whenever we need to create an instance of that entity, we should always use that constructor. It also prevents different aggregates manipulate each other and leaking business logic of an aggregate to one another. Especially, if there are multiple applications are being developed in a single domain, then the Domain Logic vs Application Logic separation becomes much more important. You may think "Why do we have a second way of creating an issue?". IIssueRepository extends the standard IRepository<> interface by adding a GetInActiveIssuesAsync method. An aggregate (with the root entity and sub-collections) should be serializable and transferrable on the wire as a single unit. In some cases, you may need to have duplicate logic in the application and presentation layers. Make client code easy to develop and extend; Make the server side code easy to develop and extend; Returning same types from different methods make it easy and clear to create. If you want to assign this issue to a user, you need to use, If there is no duplication, it creates and returns a new. DbMigrations project contains a union of the modules to track and apply a single migration path. It is used by the Presentation Layer. Is that rule should always be implemented". So, determine your aggregate boundaries and size based on the following considerations; For example, see the Aggregate root and the Entity below: That doesn't mean sub-collection entities should always have composite PKs. However, EF Core & relational database developers may find this restrictive rule unnecessary since EF Core can handle it on database read and write. However, ABP also supports FluentValidation integration if you prefer the other approach. You will write optimized queries, create indexes and even stored procedures(!). Input DTOs (those are passed to the Application Service methods) have different natures than Output DTOs (those are returned from the Application Service methods). It is a use-case specific application logic. Who would define unused parameters (input DTO properties) for a method? You can follow these rules and apply in your solution while implementing the Domain Driven Design. Domain Services implement domain logic which; Domain Services work with Domain Objects. Some developers think it is better to separate the validation rules and DTO classes.

The projects have been explained before. IssueAssignDto in this example is a simple DTO class: A DTO is a simple object that is used to transfer state (data) between the Application and Presentation Layers. The constructor is located where the lifecycle of an entity begins. Because, in this example, whenever you change a filter, you have to make the necessary changes in all the methods to have a consistent reporting system. DDD helps to deal with complexity when your system is large. Because, our system doesn't allow to move issues across repositories (think as GitHub repositories). So, they will be treated differently. Let's see the CreateAsync method step by step to discuss if the code part should be in the Domain Service, or not; Example: Creating a new Organization in an Application Service. We may have other use cases where we don't charge money to create a new Organization.

That's why this logic is a core domain logic, should be located in the Domain Layer and should not be duplicated in all these application service methods.

Actually, we should try to implement business rules in the entities wherever possible. Once an entity is created, it is updated/manipulated by the use cases until it is deleted from the system. The examples will use some concepts those are used by GitHub, like Issue, Repository, Label and User, you are already familiar with. However, being important is not sufficient to consider a code as a Core Business Logic. See the Entity Creation section below for an example implementation of the suggestions made in this section. This Application Service does nothing itself and delegates all the work to the Domain Service. The result will be same. Issue.AddComment gets a userId and comment text, implements the necessary business rules and adds the comment to the Comments collection of the Issue. We think the business code should be explicit, clear and easy to understand. The example above may seem strange to you! If additional actions cancel the entity creation because of a business rule, the transaction should be rolled back in the database. ABP Framework automatically validates input DTOs, throws AbpValidationException and returns HTTP Status 400 to the client in case of an invalid input. The solution is layered by considering DDD principles as well as development and deployment practicals. They may have single Id properties when it's needed. DDD mostly focuses on the Domain & Application Layers and ignores the Presentation and Infrastructure. As you can guess, there will be a lot of code duplications for querying data, mapping entities to DTOs. Otherwise, we would need to perform one Insert (in the IssueManager) and one Update (after the Assignment). This section will introduce the principles and rules related to the Aggregates. If your application doesn't have fancy dashboards and reports, who would use it? For example, assume that you don't want to allow to create an issue if there is already an issue with exactly the same Title. Instead, an IssueTracking.HttpApi.Host application will be in the solution to serve the HTTP APIs as a standalone endpoint to be consumed by the UI applications via HTTP API calls. However, it is an important practice of Domain Driven Design. A good solution to this problem is the Specification Pattern!

We think the declarative (Data Annotation) approach is practical and useful and doesn't cause any design problem. In this way, we can check activeness when we have an issue entity. They are very important. Use domain objects (domain services, entities, etc.) See the example below: Role aggregate has a collection of UserRole value objects to track the users assigned for this role. If you've multiple applications with a single domain; Such a design makes it even more important to distinguish between Domain logic and Application Logic. This is why we suggest to return the entity DTO (UserDto here) as return value from the Create and Update operations. If you want to take advantage of this EF Core feature, please see the Discussion About the Database Independence Principle section above. Your code base becomes complicated and hard to maintain. Notice that UserRole is not another aggregate and it is not a problem for the rule Reference Other Aggregates Only By Id. First, made SetTitle internal in the Issue class: Then added a new method to the IssueManager to change the Title: As mentioned before, Business Logic in the Domain Driven Design is spitted into two parts (layers): Domain Logic and Application Logic: Domain Logic consists of the Core Domain Rules of the system while Application Logic implements application specific Use Cases. We had to copy/paste/modify the code. Let's see the implementation to understand it: (Used EF Core for the implementation.

So, you actually don't need to call _issueRepository.UpdateAsync. Why don't we just execute an SQL Insert command to database without querying any data? Example: Business Rule: Can not assign more than 3 open issues to a user concurrently. Then we can add a CreateAsync method to the IssueManager: The IssueAppService is changed as shown below in order to use the IssueManager's CreateAsync method: You may ask "Why didn't IssueManager save the Issue to the database?". It uses and coordinates the domain objects (entities, repositories, etc.) UI frameworks and database providers have their own rules and best practices that you need to know and apply. This is because the example code above just focuses on the constructor. We think it is the responsibility of the Application Service. The picture below shows a Visual Studio Solution created using the ABP's application startup template: The solution name is IssueTracking and it consists of multiple projects. Remember; Entities can not inject services!

While this works out of the box for MongoDB, you need to configure your aggregate details for the EF Core. For example, if you have a reporting page that has some filters and you have multiple Application Service methods (like screen report, excel report and csv report methods) use the same filters but returns different results, you may want to reuse the same filter input DTO to couple these use cases. There are four fundamental layers of a Domain Driven Based Solution; Business Logic places into two layers, the Domain layer and the Application Layer, while they contain different kinds of business logic; The same layering can be shown as the diagram below and known as the Clean Architecture, or sometimes the Onion Architecture: In the Clean Architecture, each layer only depends on the layer directly inside it. to implement the. Since the Application Layer gracefully abstracts the Domain Layer, the refactoring process doesn't effect the UI Layer and other clients. It is mostly related to modularity. Most of the time, API Controllers are just wrappers around the Application Services to expose them to the remote clients. This principle is relatively easy to implement and ABP's startup template makes it even easier. The next step is to create a domain service, named IssueManager, that has AssignToAsync to assign the given issue to the given user. It is simple to implement a business rule in an entity method when the business logic only uses the properties of that entity.

Finally, we use _issueRepository.UpdateAsync to save changes to the database. However, reporting is another topic. In this section, we will discuss a typical update operation that changes multiple properties of an Issue. Other aggregates are shown as simple since we will focus on the Issue Aggregate: As said before, an Aggregate is a cluster of objects (entities and value objects) bound together by an Aggregate Root object. This design decision potentially allows you to use Entities and EF Core objects in the Presentation Layer which should be strictly avoided. However, in real life, you have; We can give more examples. For example, you may need to duplicate the validation and authorization checks in both layers. However, the developer may then set the Title property to null without any control. Now, we can re-use the InActiveIssueSpecification in the Issue entity and EfCoreIssueRepository classes. The diagram below shows the essential dependencies (project references) between the projects in the solution (IssueTracking. Example: Get inactive issues from a repository. See the Repositories document for more information. It is very important to design the Domain and Application Layers to be completely unaware of the presentation technology/framework. Example: Throwing a business exception with code. First, starting from the repository interface: Renamed GetInActiveIssuesAsync to simple GetIssuesAsync by taking a specification object. In such cases, create Domain Service methods, but only for those really necessary. That means you can not add navigation properties to other aggregates. If we declare all the properties with public setters (like the example Issue class above), we can't force validity and integrity of the entity in its lifecycle. So, a good understanding of OOP & SOLID helps you a lot while truly implementing the DDD. You may wonder why the payment code is not inside the OrganizationManager. However, in real life, you may need to change more than one aggregate instances in a single use case and you need to use database transactions to ensure atomic update and data consistency. An aggregate is generally considered as a transaction boundary. There are some reasons why you should not use input DTO to Entity auto mapping; While some of these problems can be solved through mapping configurations (For example, AutoMapper allows to define custom mapping rules), it makes your business code implicit/hidden and tightly coupled to the infrastructure. Code duplication is a better practice than coupling use cases. Because, the Application Service may require additional changes/operations on the Issue object before saving it. Now, we can change the ReOpen method as shown below: And add an entry to the localization resource like below: For this example, you could directly throw BusinessException instead of defining a specialized IssueStateException. This rule should be implemented in a Domain Service, IssueManager in this case. Do it when you need and refactor the existing code. While the definition is clear, the implementation may not be easy. On the other hand, for example, in MongoDB you don't need to define PK for the sub-collection entities at all since they are stored as a part of the aggregate root. The question here is "What is an inactive issue? We think this is reasonable; While there is a tradeoff between two approaches, we prefer to create Domain Services when the business logic requires to work with external services. ABP Framework provides necessary infrastructure to easily create specification classes and use them inside your application code. There are two common ways of implementing such a business logic: Domain Services will be explained later. That doesn't mean they are not important. Each module has its own independent DbContext and your application has also one DbContext.

We refer the term Entity both for Aggregate Root and sub-collection entities unless we explicitly write Aggregate Root or sub-collection entity. ABP Framework helps to implement this principle in your applications.

Domain-driven design (DDD) is an approach to software development for complex needs by connecting the implementation to an evolving model; DDD is suitable for complex domains and large-scale applications rather than simple CRUD applications. When you throw the exception, ABP automatically uses this localized message (based on the current language) to show to the end user. There are more combining methods are available, like Or() and AndNot(). to implement the use cases. Just moved the expression here, from the repository. That doesn't mean the Presentation and Infrastructure layers are not important. Especially, the reason 1 deeply effects your domain object design (especially, the entity relations) and application code. We see this an important rule that helps to reduce the complexity of the domain prevents potential problems and we strongly suggest to implement this rule. Before going into details, let's see some overall DDD principles; The domain and the application layers should be ORM / Database Provider agnostic. See the Unit Of Work documentation for more info. Exceptional Case: There can be some exceptions for this rule: If you always want to develop two methods in parallel, they may share the same input DTO (by inheritance or direct reuse). Otherwise, it will be confusing for the clients to use the Application Service method.

We will introduce and explain some explicit rules with examples. One good practice is to keep an aggregate simple and small. Query (load/save) performance and memory consumption.

However, it brings a new question "How did you decide that it is a core domain logic, but not an application logic?" A Repository is a collection-like interface that is used by the Domain and Application Layers to access to the data persistence system (the database) to read and write the Business Objects, generally the Aggregates. Mixing all these logics into a single application layer makes your services contain too many if conditions with complicated business logic makes your code harder to develop, maintain and test and leads to potential bugs. Example: Using Data Annotation Attributes. While most of the time you don't need to know it, you can see the EF Core migrations document for more information. In this case, the same information is duplicated in different collections and it will be hard to maintain data consistency (whenever you add an item to User.Roles, you need to add it to Role.Users too). Implementing DDD highly relies on the Object Oriented Programming (OOP) and SOLID principles. The example code above returns different DTO types for each method. DDD ignores reporting and mass querying. There is a Console Application in the test folder of the solution, named IssueTracking.HttpApi.Client.ConsoleTestApp. Playing football is very simple, but playing simple football is the hardest thing there is. So, we need to force the Application Layer always to use the IssueManager to create a new Issue. We should not forget to update both places. It will be automatically saved thanks to ABP's Unit Of Work system that automatically calls DbContext.SaveChanges() at the end of the method. Updated implementation of the repository can be like that: Since ToExpression() method returns an expression, it can be directly passed to the Where method to filter the entities. Some of the output DTO suggestions may not fit in every scenario. The Aggregate Root Entities are also responsible for their sub-collection entities. You are free to do all these things as long as you don't infect them into your business logic. After updating a user, you can get the return value and update it on the UI. Get the related domain objects from database to implement the use case. See the Specifications document for more details about the specification infrastructure provided by the ABP Framework. If you are more interested in the Domain Driven Design and building large-scale enterprise systems, the following books are recommended as reference books; Build maintainable .NET solutions by following software development best practices using ABP. Let's see the Update implementation in the IssueAppService: As said, we need some changes in the Issue and IssueManager classes. However, the startup solution includes it for the cases you need to manually create API controllers. If Domain Service saves it, then the Save operation is duplicated; When you check the IssueAppService, you will see the advantage of not saving Issue to the database in the IssueManager.CreateAsync. See the Validation document for all validation options. In MongoDB, an aggregate object (with sub-collections) is saved in a single collection in the database (while it is distributed into several tables in a relational database). Assume that you are using Entity Framework Core with a relational database. See the exception handling document for all the details. It is internal and changing it is possible only inside the same Assembly, the IssueTracking.Domain project for this example solution.

That's perfectly normal and necessary. However these are not in the topics of DDD. The Aggregate / Aggregate Root Rules & Best Practices section suggests to create a primary constructor for the Entity class that guarantees to create a valid entity. It simply uses the IssueTracking.HttpApi.Client project to consume the APIs exposed by the application. We can combine both specifications to get a list of inactive issues in a specific milestone: The example above uses the And extension method to combine the specifications. Another way of reusing input DTOs is inheriting DTOs from each other. UserDto is defined below: This is more maintainable approach although more code is written. See the Loading Related Entities section of the EF Core document for the configuration and alternative scenarios. See the Issue Aggregate Root class below: Let's see an Application Service method that is used to create an issue: The example Issue entity has no business rule on entity creation, except some formal validations in the constructor. The following rules will already bring the serializability. However, it has some problems; An alternative way of implementing this business logic is to introduce a Domain Service, which will be explained later. A specification is a named, reusable, combinable and testable class to filter the Domain Objects based on the business rules. Composite PKs are actually a concept of relational databases since the sub-collection entities have their own tables and needs to a PK. Define public methods to manipulate such properties. In a DDD implementation, you may have a single Infrastructure project to implement all the abstractions and integrations, or you may have different projects for each dependency. Remember how an issue assignment has been implemented in the Issue entity: Here, we will move this logic into a Domain Service. One powerful side of the Specifications is they are combinable. This method perfectly guarantees to apply the business logic when you want to assign an issue to a user. You see two aggregate roots, GitRepository and Issue in the example below; So, when you have an Issue and need to have GitRepository related to this issue, you need to explicitly query it from database by the RepositoryId.