dotnet
Feedback on the Common web application architectures article
Type of issue
Other (describe below)
Description
This issue has been moved from a ticket on Developer Community.
To whom it may concern,
I am writing to express my concern and dissatisfaction with the article titled “Common web application architectures” that is published on the Microsoft Learn website. In particular, I have an issue with the section that describes the Clean Architecture.
The article claims that the Clean Architecture is a generic term that has gone by many names over the years, such as Hexagonal Architecture, Ports-and-Adapters, Onion Architecture, etc. It then proceeds to describe a custom architecture that has nothing to do with the original Clean Architecture as defined by Robert C. Martin in his book of the same name.
This is misleading, inaccurate, and disrespectful to the author and his work. The Clean Architecture is not a generic term, but a specific architecture that has a clear definition and structure. It is based on a set of principles and rules that aim to make software systems more understandable, maintainable, testable, and independent of frameworks, databases, or external agencies. It consists of four main layers:
- Enterprise Business Rules (Entities);
- Application Business Rules (Use Cases);
- Interface Adapters;
- Frameworks and Drivers.
The architecture that the article describes introduces new terms and layers that are not part of the Clean Architecture, such as Application Core, Infrastructure, and UI. It also mixes up different architectures and patterns that are not equivalent or interchangeable with the Clean Architecture, such as Hexagonal Architecture, Ports-and-Adapters, Onion Architecture, etc.
These architectures and patterns may have some similarities or overlaps with the Clean Architecture, but they are not the same thing. They have different origins, definitions, structures, and goals. They may also have different advantages and disadvantages depending on the context and requirements of each project. To lump them together under one name and present them as one architecture is confusing and misleading for the readers.
Therefore, I urge you to change the title and content of the section that describes the Clean Architecture. You should either describe the Clean Architecture as it is defined by Robert C. Martin in his book, without making up new terms and layers, or you should not mention the Clean Architecture at all and use a different name for your custom architecture. This way, you will avoid misinforming and misguiding your readers and respect the author and his work.
Thank you for your attention and consideration.
Sincerely,
Dmytro Turskyi
Original Comments
Tracy Wang [MSFT] on 6/18/2023, 05:34 PM:
We have converted this feedback item to a suggestion. This change was done to better reflect the feedback’s nature. It will allow other developers to easily find it and engage on it.
Feedback Bot on 6/18/2023, 07:34 PM:
Thank you for taking the time to provide your suggestion. We will do some preliminary checks to make sure we can proceed further. You will hear from us in about a week on our next steps.
Page URL
https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures
Content source URL
https://github.com/dotnet/docs/blob/main/docs/architecture/modern-web-apps-azure/common-web-application-architectures.md
Document Version Independent Id
b227c667-82ae-97ef-c175-7e17051c5ab2
Article author
@ardalis
@Rick-Anderson
I found this issue floating around. I converted it to github feedback with all the data. But it was originally written by ardalis and I don't think he owns the content anymore. Is there someone on your team that should own this?
@ardalis owns this. @Turskyi what about
~Clean~ Onion architecture
Applications that follow the Dependency Inversion Principle as well as the Domain-Driven Design (DDD) principles ~tend~ FREQUENTLY ~to~ arrive at a similar architecture. This architecture has gone by many names over the years. One of the first names was Hexagonal Architecture, followed by Ports-and-Adapters. More recently, it's been cited as the Onion Architecture AND BORROWS SOME ELEMENTS FROM Clean Architecture. ~The latter name, Clean Architecture, is used as the name for this architecture in this e-book.~
I think we should replace this with Enterprise App Patterns - Modern Web App (MWA) once it's released.
Hi @Rick-Anderson,
Thank you for your response and the suggestion to transition to “Enterprise App Patterns - Modern Web App (MWA)” in future updates. While I appreciate the consideration, I’d like to expand on a few points that I believe are important to address to avoid any further confusion for readers.
Firstly, there are other parts of the documentation that continue to use the term "Clean Architecture," including images and diagrams that explicitly label it as such. Simply replacing the textual references won’t be enough to correct the misrepresentation—these images will also need to be updated accordingly. The visual elements play a significant role in shaping how readers interpret the content, so they must accurately reflect any terminological changes you make.
Additionally, I noticed that you suggested pivoting from “Clean Architecture” to “Onion Architecture” as part of this update. While this could be a good alternative, it’s important to note that "Onion Architecture" also has a very specific definition and structure, as outlined in the original article by Jeffrey Palermo (https://jeffreypalermo.com/2008/07/the-onion-architecture-part-1/). Can Microsoft guarantee that the interpretation described in your documentation doesn’t deviate from the implementation presented by Palermo? If your version introduces different terms, layers, or structures, it risks misrepresenting Onion Architecture in the same way that Clean Architecture was misrepresented.
Based on what I've seen, it feels like there’s an intention to create a hybrid approach that borrows from both Clean and Onion Architecture but follows its own path. If that’s the case, perhaps the best solution would be to come up with a new name altogether, one that better reflects the unique aspects of your approach. You could briefly mention that this new architecture was inspired by both Clean and Onion Architecture and acknowledge the specific layers and components you’ve borrowed. However, by giving it a distinct name, you avoid implying that it is the same as these well-defined existing patterns.
This would not only provide more clarity for your readers but also ensure that both Robert C. Martin’s Clean Architecture and Jeffrey Palermo’s Onion Architecture are respected in their original forms.
Thanks again for considering my feedback. I hope this helps in refining the content to better serve the developer community.
@Turskyi thanks for your detailed response. The changes I proposed were just a sample of the direction I thought the doc should go.
Based on what I've seen, it feels like there’s an intention to create a hybrid approach that borrows from both Clean and Onion Architecture but follows its own path. If that’s the case, perhaps the best solution would be to come up with a new name altogether, one that better reflects the unique aspects of your approach. You could briefly mention that this new architecture was inspired by both Clean and Onion Architecture and acknowledge the specific layers and components you’ve borrowed. However, by giving it a distinct name, you avoid implying that it is the same as these well-defined existing patterns.
I agree.
Clean architecture makes DI the cornerstone of the doc, while Reliable web app pattern for .NET mentions DI:
The reference implementation uses Polly to set up the ASP.NET Core dependency injection. Polly enforces the Retry pattern every time the code constructs an object that calls the IConcertSearchService object.
Let's see how @ardalis responds.
If we were going to choose a more generic term for the architecture I would call it "Domain-Centric Architecture" and cite:
- Ports and Adapters / Hexagonal Architecture
- Onion Architecture
- Clean Architecture
as popular examples of this approach. It would be straightforward to swap that in wherever Clean Architecture is mentioned currently. Would that satisfy @Turskyi ? This is the first/only complaint about this I've seen, and now that Microsoft has shifted maintenance of the eShopOnWeb reference application to NimblePros there are far fewer dotnet developers discovering this content/ebook, anyway, so I don't know that it's worth a major effort to change it much at this stage.
Hi @Rick-Anderson and @ardalis,
Thank you both for your responses.
@Rick-Anderson, I understand the changes you suggested were just a starting point, and I agree that the direction seems to be a hybrid approach borrowing from both Clean and Onion Architecture while following its own path.
@ardalis, I think "Domain-Centric Architecture" works well as a more generic term, especially when citing examples like Ports and Adapters / Hexagonal, Onion, and Clean Architecture. This way, it avoids confusion about strictly following any one specific pattern and gives the approach its own identity, which addresses main concern.
Regarding the scope of changes, while I understand the reduced attention to the eShopOnWeb reference app, I believe updating key areas to reflect this new term—especially in both the text and related images—would help with clarity, especially for developers who might use this as a learning resource.
Thanks again for taking my input seriously. I'm glad we’re moving toward a solution that respects the original patterns while giving this approach its own identity.