Browse Source

Merge remote-tracking branch 'origin/dev' into auto-merge-forward/rel-10.7-to-dev-71

pull/26246/head
sumeyye 1 month ago
parent
commit
eac33ed6c8
  1. 10
      Directory.Packages.props
  2. 22
      abp_io/AbpIoLocalization/AbpIoLocalization/Account/Localization/Resources/pt.json
  3. 4
      common.props
  4. 2
      docs/en/Blog-Posts/2024-07-31 v8_3_Preview/post.md
  5. 2
      docs/en/Blog-Posts/2024-09-17-My-Impressions-at-DotNext-2024-Conference/post.md
  6. 2
      docs/en/Blog-Posts/2024-10-23 v9_0_Preview/POST.md
  7. 2
      docs/en/Blog-Posts/2025-06-10-Announcing-ABP-Studio-1.0-Stable-Release/POST.md
  8. 18
      docs/en/Blog-Posts/2025-12-24-Announcing-Aspire-For-Microservice-Template/POST.md
  9. 4
      docs/en/Blog-Posts/2026-08-05 v10_7_Preview/POST.md
  10. BIN
      docs/en/Blog-Posts/2026-08-05 v10_7_Preview/react-crud-page.gif
  11. 4
      docs/en/Community-Articles/2024-01-15-Abp-Supports-NET8/Post.md
  12. 2
      docs/en/Community-Articles/2024-03-19-join-abpio-at-modern-net-web-day/post.md
  13. 2
      docs/en/Community-Articles/2024-04-16-welcome-to-abp-dotnet-conf24-a-decade-of-net-innovation/post.md
  14. 2
      docs/en/Community-Articles/2024-05-16-abp-dotnet-conference-2024-wrap-up/post.md
  15. 40
      docs/en/Community-Articles/2024-06-27-how-to-use-Aspire-with-ABP-framework/How to use Aspire with ABP framework.md
  16. 2
      docs/en/Community-Articles/2024-08-01-abpio-platform-83-rc-has-been-published/post.md
  17. 2
      docs/en/Community-Articles/2024-08-12-join-abp-at-net-conf-focus-on-ai/post.md
  18. 6
      docs/en/Community-Articles/2024-10-01-SignalR-9-New-Features/Post.md
  19. 54
      docs/en/Community-Articles/2024-10-11-NET-Aspire-vs-ABP-Studio/POST.md
  20. 2
      docs/en/Community-Articles/2024-10-23-abpio-platform-90-rc-has-been-published/post.md
  21. 26
      docs/en/Community-Articles/2024-11-05-.NET Aspire 9.0 Features/Post.md
  22. 6
      docs/en/Community-Articles/2025-11-30-NET-Conf-China-2025/POST.md
  23. 450
      docs/en/Community-Articles/2026-07-07-resource-based-api-for-angular/POST.md
  24. 511
      docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/Post.md
  25. BIN
      docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/abp-layers.png
  26. BIN
      docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/abp-learning-path.png
  27. BIN
      docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/cover.png
  28. BIN
      docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/crud-vs-manual.png
  29. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/12m9D9rhnUDaiDElvNysSXw.png
  30. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1479e3iBZ4il0F0tlpUQDYw.png
  31. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1EBeje4kIw0tQ4dGrI5i18A.png
  32. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1U_z6zDB8GIK2oVVTbKmslg.png
  33. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1YCRTIV3eHwgGvEOVlHBDCg.png
  34. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1Zz-6JQ0gzPq2AvN1_FjbtA.png
  35. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1tKQUwPK70eQXvad1eiXoPA.png
  36. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/Cover.png
  37. 308
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/Post.md
  38. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816150848261.png
  39. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816151051144.png
  40. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816151255530.png
  41. BIN
      docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816151702299.png
  42. 601
      docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/Post.md
  43. BIN
      docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/cover.png
  44. BIN
      docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/inline-1.png
  45. BIN
      docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/inline-2.png
  46. BIN
      docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/inline-3.png
  47. BIN
      docs/en/Community-Articles/2026-09-02-abp-studio-vs-aspire-ai-ides-and-crud-generators/ABP-Studio-vs-Alternatives-Cover.png
  48. BIN
      docs/en/Community-Articles/2026-09-02-abp-studio-vs-aspire-ai-ides-and-crud-generators/ABP-Studio-vs-Alternatives-Inline.png
  49. 163
      docs/en/Community-Articles/2026-09-02-abp-studio-vs-aspire-ai-ides-and-crud-generators/Post.md
  50. BIN
      docs/en/Community-Articles/2026-09-02-abp-vs-clean-architecture-templates-and-starter-kits/ABP-vs-Alternatives-Cover.png
  51. BIN
      docs/en/Community-Articles/2026-09-02-abp-vs-clean-architecture-templates-and-starter-kits/ABP-vs-Alternatives-Inline.png
  52. 223
      docs/en/Community-Articles/2026-09-02-abp-vs-clean-architecture-templates-and-starter-kits/Post.md
  53. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/Cover.png
  54. 177
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/Post.md
  55. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906201600152.png
  56. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906202807792.png
  57. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906203343446.png
  58. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906204302915-1788717035148-1.png
  59. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906210745253.png
  60. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906212109817.png
  61. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906212829582.png
  62. BIN
      docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906225734694.png
  63. 137
      docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/Post.md
  64. BIN
      docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/ai-connection-settings.png
  65. BIN
      docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/cover.png
  66. BIN
      docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/included-models-catalog.png
  67. 406
      docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/POST.md
  68. BIN
      docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/cover.png
  69. BIN
      docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/demo-article-detail.png
  70. BIN
      docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/demo-three-strategies.png
  71. BIN
      docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/exact-vs-approximate.png
  72. BIN
      docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/hybrid-search.png
  73. BIN
      docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/2-conflict.jpeg
  74. BIN
      docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/2-manifest.jpeg
  75. BIN
      docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/3-podman.jpeg
  76. BIN
      docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/5-checklist.jpeg
  77. 79
      docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/Post.md
  78. BIN
      docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/cover-image.jpeg
  79. BIN
      docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/async-validation-pipeline.png
  80. BIN
      docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/join-family.png
  81. BIN
      docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/net-11-in practice-cover.png
  82. 512
      docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/post.md
  83. BIN
      docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/sample-app-architecture.png
  84. BIN
      docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/tracing-rules.png
  85. 516
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/ARTICLE.md
  86. 7
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/ASSET-LICENSE.md
  87. BIN
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/benchmark-results.png
  88. 33
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/benchmark-results.svg
  89. BIN
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/live-stack-comparison.png
  90. 38
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/live-stack-comparison.svg
  91. BIN
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/physical-logical-async.png
  92. 20
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/physical-logical-async.svg
  93. BIN
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/runtime-async-architecture.png
  94. 43
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/runtime-async-architecture.svg
  95. BIN
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/task-materialization.png
  96. 29
      docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/task-materialization.svg
  97. BIN
      docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/anyof_union_openapi.png
  98. BIN
      docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/api_contract_flow.png
  99. BIN
      docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/article-cover-image.jpeg
  100. BIN
      docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/ndjson_screenshot.png

10
Directory.Packages.props

@ -37,9 +37,9 @@
<PackageVersion Include="DistributedLock.Core" Version="1.0.8" />
<PackageVersion Include="DistributedLock.Redis" Version="1.1.0" />
<PackageVersion Include="DeepL.net" Version="1.15.0" />
<PackageVersion Include="itext.bouncy-castle-adapter" Version="9.3.0" />
<PackageVersion Include="itext7" Version="9.3.0" />
<PackageVersion Include="itext7.pdfhtml" Version="6.2.1" />
<PackageVersion Include="HtmlAgilityPack" Version="1.12.3" />
<PackageVersion Include="HtmlRenderer.PdfSharp" Version="1.6.1" />
<PackageVersion Include="PDFsharp" Version="6.2.4" />
<PackageVersion Include="MongoSandbox.Core" Version="2.0.0" />
<PackageVersion Include="MongoSandbox8.runtime.linux-x64" Version="2.0.0" />
<PackageVersion Include="MongoSandbox8.runtime.osx-arm64" Version="2.0.0" />
@ -125,7 +125,7 @@
<PackageVersion Include="Microsoft.IdentityModel.JsonWebTokens" Version="8.19.2" />
<PackageVersion Include="Minio" Version="6.0.5" />
<PackageVersion Include="MongoDB.Driver" Version="3.12.0" />
<PackageVersion Include="NEST" Version="7.17.5" />
<PackageVersion Include="Elastic.Clients.Elasticsearch" Version="8.19.27" />
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
<PackageVersion Include="Nito.AsyncEx.Context" Version="5.1.2" />
<PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.3" />
@ -140,8 +140,6 @@
<PackageVersion Include="OpenIddict.Validation.AspNetCore" Version="7.7.0" />
<PackageVersion Include="OpenIddict.Validation.ServerIntegration" Version="7.7.0" />
<PackageVersion Include="Oracle.EntityFrameworkCore" Version="10.23.26000" />
<PackageVersion Include="Polly" Version="8.6.3" />
<PackageVersion Include="Polly.Extensions.Http" Version="3.0.0" />
<PackageVersion Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0" />
<PackageVersion Include="MySql.EntityFrameworkCore" Version="10.0.9" />
<PackageVersion Include="Quartz" Version="3.15.0" />

22
abp_io/AbpIoLocalization/AbpIoLocalization/Account/Localization/Resources/pt.json

@ -0,0 +1,22 @@
{
"culture": "pt",
"texts": {
"Account": "Conta ABP - Iniciar sessão e registar | ABP.IO",
"Welcome": "Bem-vindo",
"UseOneOfTheFollowingLinksToContinue": "Utilize uma das seguintes ligações para continuar",
"FrameworkHomePage": "Página inicial da framework",
"FrameworkDocumentation": "Documentação da framework",
"OfficialBlog": "Blogue oficial",
"CommercialHomePage": "Página inicial comercial",
"CommercialSupportWebSite": "Site de apoio comercial",
"CommunityWebSite": "Site da comunidade ABP",
"ManageAccount": "A minha conta | ABP.IO",
"ManageYourProfile": "Gerir o seu perfil",
"ReturnToApplication": "Voltar à aplicação",
"IdentityUserNotAvailable:Deleted": "Este endereço de email não está disponível. Motivo: já foi eliminado.",
"SelectYourOrganization": "Selecione a sua organização",
"PleaseSelectOrganization": "Selecione uma organização para continuar",
"Continue": "Continuar",
"CaptchaExplanation": "Calcule a expressão matemática abaixo e introduza a resposta."
}
}

4
common.props

@ -1,8 +1,8 @@
<Project>
<PropertyGroup>
<LangVersion>latest</LangVersion>
<Version>10.7.0</Version>
<LeptonXVersion>5.7.0</LeptonXVersion>
<Version>10.8.0-preview</Version>
<LeptonXVersion>5.8.0-preview</LeptonXVersion>
<NoWarn>$(NoWarn);CS1591;CS0436</NoWarn>
<PackageIconUrl>https://abp.io/assets/abp_nupkg.png</PackageIconUrl>
<PackageProjectUrl>https://abp.io/</PackageProjectUrl>

2
docs/en/Blog-Posts/2024-07-31 v8_3_Preview/post.md

@ -165,7 +165,7 @@ There are exciting articles contributed by the ABP community as always. I will h
* [Create a Generic HTTP Service to Consume a Web API](https://abp.io/community/articles/create-a-generic-http-service-to-consume-a-web-api-yidme2kq) by [Bart Van Hoey](https://github.com/bartvanhoey)
* [Use User-Defined Function Mapping for Global Filter](https://abp.io/community/articles/use-userdefined-function-mapping-for-global-filter-pht26l07) by [Liming Ma](https://github.com/maliming)
* [How to use .NET Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk) by [Berkan Şaşmaz](https://twitter.com/berkansasmazz)
* [How to use Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk) by [Berkan Şaşmaz](https://twitter.com/berkansasmazz)
* [Exciting New Feature in ABP.IO CMS Kit: Marked Item System](https://abp.io/community/articles/exciting-new-feature-in-abp.io-cms-kit-marked-item-system.-2hvpq0me) by [Suhaib Mousa](https://abp.io/community/members/suhaibmousa032@gmail.com)
Thanks to the ABP Community for all the content they have published. You can also [post your ABP-related (text or video) content](https://abp.io/community/posts/create) to the ABP Community.

2
docs/en/Blog-Posts/2024-09-17-My-Impressions-at-DotNext-2024-Conference/post.md

@ -14,7 +14,7 @@ Last week, I had the chance of being a speaker at **DotNext 2024** in Moscow. [J
One of the standout aspects of the conference was its strong technical focus, particularly on deep-dive .NET topics. Talks covered subjects like **low-level optimizations**, architecture, performance, and platform internals.
The conference started with Sergei Benzenko's talk "What's New in .NET 9". There are important topics like ".NET Aspire in Action", "AI-Driven Software Development", "DDD and Strategic Design" and "OAuth 2.0 User-Managed Access in ASP.NET Core with Keycloak".
The conference started with Sergei Benzenko's talk "What's New in .NET 9". There are important topics like "Aspire in Action", "AI-Driven Software Development", "DDD and Strategic Design" and "OAuth 2.0 User-Managed Access in ASP.NET Core with Keycloak".
![DotNext 2024 Speakers](speakers.png)

2
docs/en/Blog-Posts/2024-10-23 v9_0_Preview/POST.md

@ -209,7 +209,7 @@ There are exciting articles contributed by the ABP community as always. I will h
* [Mohammad AlMohammad AlMahmoud](https://abp.io/community/members/Mohammad97Dev) has created **two** new community articles:
* [Implementing Multi-Language Functionality With ABP Framework](https://abp.io/community/articles/implementing-multilanguage-functionality-with-abp-framework-loq7kfx4)
* [Configure Quartz.Net in Abp FrameWork](https://abp.io/community/articles/configure-quartz.net-in-abp-framework-3bveq4y1)
* [.NET Aspire vs ABP Studio: Side by Side](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l) by [Halil İbrahim Kalkan](https://twitter.com/hibrahimkalkan)
* [Aspire vs ABP Studio: Side by Side](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l) by [Halil İbrahim Kalkan](https://twitter.com/hibrahimkalkan)
* [PoC of using GrapesJS for ABPs CMS Kit](https://abp.io/community/articles/poc-of-using-grapesjs-for-abps-cms-kit-1rmv4q41) by [Jack Fistelmann](https://abp.io/community/members/jfistelmann)
* [ABP-Powered Web App with Inertia.js, React, and Vite](https://abp.io/community/articles/abppowered-web-app-with-inertia.js-react-and-vite-j7cccvad) by [Anto Subash](https://antosubash.com/)
* [Multi-Tenancy Support in Angular Apps with ABP.IO](https://abp.io/community/articles/multitenancy-support-in-angular-apps-with-abp.io-lw9l36c5) by [HeadChannel Team](https://headchannel.co.uk/)

2
docs/en/Blog-Posts/2025-06-10-Announcing-ABP-Studio-1.0-Stable-Release/POST.md

@ -87,7 +87,7 @@ We will keep releasing new versions with exciting features based on our roadmap
- **OpenTelemetry Integration:** We'll be integrating OpenTelemetry support directly into the startup templates, making distributed tracing and observability a seamless part of your application from day one.
- **LeptonX Theme Builder**: Allowing users to determine styling, colour palette and easily override their project's theme styles.
- **Monitor dashboards of the tools used in the solution (e.g. Kubernetes, Redis, Grafana, etc...)**
- **Pre-configured .NET Aspire for the Microservice Startup Template**
- **Pre-configured Aspire for the Microservice Startup Template**
- **and more...**
We are incredibly excited about the future of ABP Studio and can't wait to share the next set of features with you. Your comments and suggestions are invaluable to us. If you have any feedback, please drop a comment below.

18
docs/en/Blog-Posts/2025-12-24-Announcing-Aspire-For-Microservice-Template/POST.md

@ -1,8 +1,8 @@
# Announcing .NET Aspire Integration for ABP Microservice Template
# Announcing Aspire Integration for ABP Microservice Template
We are excited to announce the integration of **.NET Aspire** into the ABP microservice solution, available starting with **ABP Studio v2.0.0**. This integration brings a unified development experience for building, running, debugging, and deploying distributed applications. With Aspire, you can now orchestrate your entire microservice ecosystem with a single command, eliminating complex configurations and making local development effortless.
We are excited to announce the integration of **Aspire** into the ABP microservice solution, available starting with **ABP Studio v2.0.0**. This integration brings a unified development experience for building, running, debugging, and deploying distributed applications. With Aspire, you can now orchestrate your entire microservice ecosystem with a single command, eliminating complex configurations and making local development effortless.
## What is .NET Aspire?
## What is Aspire?
[Aspire](https://aspire.dev/get-started/what-is-aspire/) is a cloud-ready stack designed to streamline the development of distributed applications. It provides:
@ -14,7 +14,7 @@ We are excited to announce the integration of **.NET Aspire** into the ABP micro
## How Does It Work with ABP?
When you enable .NET Aspire in an ABP microservice solution, you get a fully integrated development experience where:
When you enable Aspire in an ABP microservice solution, you get a fully integrated development experience where:
- All microservices, gateways, and applications are orchestrated through a single entry point (AppHost).
- Infrastructure containers (databases, Redis, RabbitMQ, Elasticsearch, etc.) are managed as code.
@ -24,8 +24,8 @@ When you enable .NET Aspire in an ABP microservice solution, you get a fully int
When creating a new microservice solution via ABP Studio:
1. In the solution creation wizard, look for the **".NET Aspire Integration"** step.
2. Toggle the option to **enable .NET Aspire**.
1. In the solution creation wizard, look for the **"Aspire Integration"** step.
2. Toggle the option to **enable Aspire**.
3. Complete the wizard—Aspire projects will be generated along with your solution.
![Enable Aspire in ABP Studio](aspire-configuration.png)
@ -38,7 +38,7 @@ When Aspire is enabled, two additional projects are added to your solution:
### AppHost (Orchestrator)
[`AppHost`](https://aspire.dev/get-started/app-host/) is the .NET Aspire orchestrator project that declares all resources (services, databases, containers, applications) and their dependencies in C# code. It provides:
[`AppHost`](https://aspire.dev/get-started/app-host/) is the Aspire orchestrator project that declares all resources (services, databases, containers, applications) and their dependencies in C# code. It provides:
- **Centralized orchestration**: Start your entire microservice ecosystem with a single command.
- **Code-first infrastructure**: Databases, Redis, RabbitMQ, Elasticsearch, and observability tools are defined programmatically.
@ -162,9 +162,9 @@ The database management admin tool varies by database type:
## Get Started Today
Ready to experience the power of .NET Aspire with ABP? Create a new microservice solution in ABP Studio and enable the .NET Aspire integration option. For detailed documentation, visit our [.NET Aspire Integration documentation](https://abp.io/docs/latest/solution-templates/microservice/aspire-integration).
Ready to experience the power of Aspire with ABP? Create a new microservice solution in ABP Studio and enable the Aspire integration option. For detailed documentation, visit our [Aspire Integration documentation](https://abp.io/docs/latest/solution-templates/microservice/aspire-integration).
To learn more about .NET Aspire, visit: [https://aspire.dev](https://aspire.dev/get-started/what-is-aspire/)
To learn more about Aspire, visit: [https://aspire.dev](https://aspire.dev/get-started/what-is-aspire/)
We are excited to bring this integration to you and can't wait to hear your feedback. If you have any questions or suggestions, please drop a comment below.

4
docs/en/Blog-Posts/2026-08-05 v10_7_Preview/POST.md

@ -10,7 +10,7 @@ You can check the [Get Started page](https://abp.io/get-started) to see how to g
By default, ABP Studio uses stable versions to create solutions. Therefore, if you want to create a solution with a preview version, first you need to create a solution and then switch your solution to the preview version from the ABP Studio UI:
![studio-switch-to-preview](studio-switch-to-preview.png)
![studio-switch-to-preview](https://raw.githubusercontent.com/abpframework/abp/refs/heads/dev/docs/en/Blog-Posts/2026-08-05%20v10_7_Preview/studio-switch-to-preview.png)
## Migration Guide
@ -82,7 +82,7 @@ Generated React pages include list, search, sorting, paging, filtering, export,
The generator respects the entity and field configuration you define in ABP Suite, including `ShowOn*`, `IsFilterable`, and `ReadonlyOnEditModal` options. Navigation lookups use server-side search.
![React CRUD page generation demo](react-crud-page.mp4)
![](https://raw.githubusercontent.com/abpframework/abp/refs/heads/dev/docs/en/Blog-Posts/2026-08-05%20v10_7_Preview/react-crud-page.gif)
### ABP Suite Decimal Precision

BIN
docs/en/Blog-Posts/2026-08-05 v10_7_Preview/react-crud-page.gif

Binary file not shown.

After

Width:  |  Height:  |  Size: 444 KiB

4
docs/en/Community-Articles/2024-01-15-Abp-Supports-NET8/Post.md

@ -7,9 +7,9 @@ Here's the summary of .NET 8 features and enhancements:
## What's new in .NET 8
### .NET Aspire
### Aspire
[.NET Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/) is a tool to observe and manage distributed web applications. It's still preview version. You can manage your containers, executables, logs, traces and metrics of your running web application. For more information see this article https://devblogs.microsoft.com/dotnet/introducing-dotnet-aspire-simplifying-cloud-native-development-with-dotnet-8/
[Aspire](https://aspire.dev/) is a tool to observe and manage distributed web applications. It's still preview version. You can manage your containers, executables, logs, traces and metrics of your running web application. For more information see this article https://devblogs.microsoft.com/dotnet/introducing-dotnet-aspire-simplifying-cloud-native-development-with-dotnet-8/
### Serialization

2
docs/en/Community-Articles/2024-03-19-join-abpio-at-modern-net-web-day/post.md

@ -11,7 +11,7 @@ Join us dive into the magic of .NET 8 at the community live stream event, "Moder
Topics that will be covered include:
* *ASP.NET Core*: Crafting Maintainable Microservices
* *Cloud Native development with .NET Aspire*
* *Cloud Native development with Aspire*
* *Developer Productivity with Visual Studio and .NET*
* *GitHub Copilot configuration, extension, tips and tricks*
* *User Experience and Front-End Development*: Delve into responsive design, accessibility, and performance optimization. Discuss modern front-end frameworks (Blazor, React, Angular, etc.) in the .NET ecosystem. Share strategies for creating delightful user interfaces.

2
docs/en/Community-Articles/2024-04-16-welcome-to-abp-dotnet-conf24-a-decade-of-net-innovation/post.md

@ -50,7 +50,7 @@ As we always be careful with topics we choose on our regular **[ABP Community Ta
* 🎙️[Adora Nwodo](https://abp.io/conference/2024/speakers/adora-nwodo), Designing Secure Cloud Native Apps with .NET and Azure
* 🎙️[Nicola Iarocci](https://abp.io/conference/2024/speakers/nicola-iarocci), C# 12 What's new and interesting
* 🎙️[Jimmy Engström](https://abp.io/conference/2024/speakers/jimmy-engstrom), Connecting gadgets to Blazor
* 🎙️[Juergen Gutsch](https://abp.io/conference/2024/speakers/juergen-gutsch), Building cloud native applications with .NET Aspire
* 🎙️[Juergen Gutsch](https://abp.io/conference/2024/speakers/juergen-gutsch), Building cloud native applications with Aspire
* 🎙️[Halil Ibrahim Kalkan](https://abp.io/conference/2024/speakers/halil-ibrahim-kalkan), Designing Modular Monolith for Microservice Architecture
* 🎙️[Shaun Lawrence](https://abp.io/conference/2024/speakers/shaun-lawrance), Building games in .NET MAUI
* 🎙️[Jamie Taylor](https://abp.io/conference/2024/speakers/jamie-taylor), Empathy, Sympathy and Compassion

2
docs/en/Community-Articles/2024-05-16-abp-dotnet-conference-2024-wrap-up/post.md

@ -33,7 +33,7 @@ The success of ABP Dotnet Conference 2024 would not have been possible without t
* 🎙️[Adora Nwodo](https://abp.io/conference/2024/speakers/adora-nwodo), Designing Secure Cloud Native Apps with .NET and Azure
* 🎙️[Nicola Iarocci](https://abp.io/conference/2024/speakers/nicola-iarocci), C# 12 What's new and interesting
* 🎙️[Jimmy Engström](https://abp.io/conference/2024/speakers/jimmy-engstrom), Connecting gadgets to Blazor
* 🎙️[Juergen Gutsch](https://abp.io/conference/2024/speakers/juergen-gutsch), Building cloud native applications with .NET Aspire
* 🎙️[Juergen Gutsch](https://abp.io/conference/2024/speakers/juergen-gutsch), Building cloud native applications with Aspire
* 🎙️[Halil Ibrahim Kalkan](https://abp.io/conference/2024/speakers/halil-ibrahim-kalkan), Designing Modular Monolith for Microservice Architecture
* 🎙️[Shaun Lawrence](https://abp.io/conference/2024/speakers/shaun-lawrance), Building games in .NET MAUI
* 🎙️[Jamie Taylor](https://abp.io/conference/2024/speakers/jamie-taylor), Empathy, Sympathy and Compassion

40
docs/en/Community-Articles/2024-06-27-how-to-use-Aspire-with-ABP-framework/How to use Aspire with ABP framework.md

@ -1,17 +1,17 @@
# How to use .NET Aspire with ABP framework
# How to use Aspire with ABP framework
[.NET Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview) is an opinionated, cloud-ready stack designed for building observable, production-ready, and distributed applications. On the other hand, the [ABP framework](https://docs.abp.io/en/abp/latest) offers a complete, modular and layered software architecture based on Domain Driven Design principles and patterns. This guide explores how to combine .NET Aspire with ABP, enabling developers to create observable, and feature-rich applications.
[Aspire](https://aspire.dev/get-started/what-is-aspire/) is an opinionated, cloud-ready stack designed for building observable, production-ready, and distributed applications. On the other hand, the [ABP framework](https://docs.abp.io/en/abp/latest) offers a complete, modular and layered software architecture based on Domain Driven Design principles and patterns. This guide explores how to combine Aspire with ABP, enabling developers to create observable, and feature-rich applications.
## When to Use .NET Aspire?
## When to Use Aspire?
Using .NET Aspire with the ABP framework can be beneficial in various scenarios where you need to combine the strengths of both technologies. Here are some situations when using .NET Aspire with ABP can be advantageous:
Using Aspire with the ABP framework can be beneficial in various scenarios where you need to combine the strengths of both technologies. Here are some situations when using Aspire with ABP can be advantageous:
- **Enterprise Web Applications:** ABP is well-suited for building enterprise web applications with its opinionated architecture and best practices. When combined with .NET Aspire, you can leverage ABP's features for rapid development of user interfaces, backend services, and business logic while benefiting from .NET Aspire's cloud-native capabilities and observability features.
- **Observability and Monitoring:** .NET Aspire's emphasis on observability, including logging, monitoring, and tracing, can enhance ABP applications by providing deeper insights into system behavior, performance metrics, and diagnostics, which is key for maintaining and optimizing enterprise-grade applications.
- **Enterprise Web Applications:** ABP is well-suited for building enterprise web applications with its opinionated architecture and best practices. When combined with Aspire, you can leverage ABP's features for rapid development of user interfaces, backend services, and business logic while benefiting from Aspire's cloud-native capabilities and observability features.
- **Observability and Monitoring:** Aspire's emphasis on observability, including logging, monitoring, and tracing, can enhance ABP applications by providing deeper insights into system behavior, performance metrics, and diagnostics, which is key for maintaining and optimizing enterprise-grade applications.
## Creating a new ABP Solution
To demonstrate the usage of .NET Aspire with the ABP framework, I've created an ABP solution. If you want to create the same solution from scratch, follow the steps below:
To demonstrate the usage of Aspire with the ABP framework, I've created an ABP solution. If you want to create the same solution from scratch, follow the steps below:
Install the ABP CLI if you haven't installed it before:
@ -27,12 +27,12 @@ abp new AspirationalAbp -u mvc --database-provider ef -dbms PostgreSQL --csf --t
> The startup template selection matters for this article. I chose these options so that the demo solution can cover complex scenarios.
**Disclaimer-I:** This article is based on version `8.0.1` of .NET Aspire and version `8.2.0` of ABP Framework.
**Disclaimer-I:** This article is based on version `8.0.1` of Aspire and version `8.2.0` of ABP Framework.
**Disclaimer-II:** ABP and .NET Aspire may not be fully compatible in some respects. This article aims to explain how these two technologies can be used together in the simplest way possible, even if they are not fully compatible.
## Add .NET Aspire
**Disclaimer-II:** ABP and Aspire may not be fully compatible in some respects. This article aims to explain how these two technologies can be used together in the simplest way possible, even if they are not fully compatible.
## Add Aspire
After creating the solution, run the following commands in the `src` folder of your solution to add .NET Aspire:
After creating the solution, run the following commands in the `src` folder of your solution to add Aspire:
```bash
// Adding AppHost
@ -46,11 +46,11 @@ dotnet sln ../AspirationalAbp.sln add ./AspirationalAbp.ServiceDefaults/Aspirati
These commands add two new projects to the solution:
- **AspirationalAbp.AppHost**: An orchestrator project designed to connect and configure the different projects and services of your app.
- **AspirationalAbp.ServiceDefaults**: A .NET Aspire shared project to manage configurations that are reused across the projects in your solution related to [resilience](https://learn.microsoft.com/en-us/dotnet/core/resilience/http-resilience), [service discovery](https://learn.microsoft.com/en-us/dotnet/aspire/service-discovery/overview), and [telemetry](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/telemetry).
- **AspirationalAbp.ServiceDefaults**: An Aspire shared project to manage configurations that are reused across the projects in your solution related to [resilience](https://learn.microsoft.com/en-us/dotnet/core/resilience/http-resilience), [service discovery](https://aspire.dev/fundamentals/service-discovery/), and [telemetry](https://aspire.dev/fundamentals/telemetry/).
We have added .NET Aspire to our ABP based solution, but we have not registered our projects in the .NET Aspire orchestration. Now, let's enroll our projects, which implement the db migrator, web user interface, API, and auth, in .NET Aspire orchestration.
We have added Aspire to our ABP based solution, but we have not registered our projects in the Aspire orchestration. Now, let's enroll our projects, which implement the db migrator, web user interface, API, and auth, in Aspire orchestration.
## Registering projects to .NET Aspire orchestration
## Registering projects to Aspire orchestration
First of all, we need to add the reference of related projects to the `AspirationalAbp.AppHost` project. For this, add the following `ItemGroups` to the `AspirationalAbp.AppHost/AspirationalAbp.AppHost.csproj` file:
@ -130,11 +130,11 @@ With the code above, the following operations were performed below:
7. Adds the `Web` project, referencing Redis.
8. Builds and runs the application.
Now let's make the projects we added to the app host compatible with .NET Aspire.
Now let's make the projects we added to the app host compatible with Aspire.
## Configuring Projects for Aspire
To make the `AspirationalAbp.DbMigrator`, `AspirationalAbp.AuthServer`, `AspirationalAbp.HttpApi.Host`, and `AspirationalAbp.Web` projects compatible with .NET Aspire, we need to add and configure several packages. For that, we need to add the `Aspire.StackExchange.Redis` package to all these projects and the `Aspire.Npgsql.EntityFrameworkCore.PostgreSQL` package to the `AspirationalAbp.EntityFrameworkCore` project. Additionally, we will add the `AspirationalAbp.ServiceDefaults` reference to host projects except `AspirationalAbp.DbMigrator`. Also, we need to convert [Serilog](https://serilog.net/) events into [OpenTelemetry](https://opentelemetry.io/) `LogRecord`s, for that we will add a `Serilog.Sinks.OpenTelemetry` reference to host projects. Let's begin with configuring `AspirationalAbp.DbMigrator`.
To make the `AspirationalAbp.DbMigrator`, `AspirationalAbp.AuthServer`, `AspirationalAbp.HttpApi.Host`, and `AspirationalAbp.Web` projects compatible with Aspire, we need to add and configure several packages. For that, we need to add the `Aspire.StackExchange.Redis` package to all these projects and the `Aspire.Npgsql.EntityFrameworkCore.PostgreSQL` package to the `AspirationalAbp.EntityFrameworkCore` project. Additionally, we will add the `AspirationalAbp.ServiceDefaults` reference to host projects except `AspirationalAbp.DbMigrator`. Also, we need to convert [Serilog](https://serilog.net/) events into [OpenTelemetry](https://opentelemetry.io/) `LogRecord`s, for that we will add a `Serilog.Sinks.OpenTelemetry` reference to host projects. Let's begin with configuring `AspirationalAbp.DbMigrator`.
### AspirationalAbp.DbMigrator
@ -211,7 +211,7 @@ To use the **OpenTelemetry** sink we have installed the `Serilog.Sinks.OpenTelem
/// .CreateLogger();
```
So far we have made `AspirationalAbp.DbMigrator`, `AspirationalAbp.EntityFrameworkCore`, and `AspirationalAbp.AuthServer` compatible with .NET Aspire. Now let's continue with `AspirationalAbp.HttpApi.Host`.
So far we have made `AspirationalAbp.DbMigrator`, `AspirationalAbp.EntityFrameworkCore`, and `AspirationalAbp.AuthServer` compatible with Aspire. Now let's continue with `AspirationalAbp.HttpApi.Host`.
### AspirationalAbp.HttpApi.Host
@ -253,7 +253,7 @@ To use the **OpenTelemetry** sink we have installed the `Serilog.Sinks.OpenTelem
/// .CreateLogger();
```
Finally, let's make `AspirationalAbp.Web` compatible with .NET Aspire.
Finally, let's make `AspirationalAbp.Web` compatible with Aspire.
### AspirationalAbp.Web
@ -299,8 +299,8 @@ After making all our changes, we can run the `AspirationalAbp.AppHost` project.
## Conclusion
Combining .NET Aspire with the ABP framework creates a powerful setup for building robust, observable, and feature-rich applications. By integrating Aspire's observability and cloud capabilities with ABP's approach of focusing on your business without repeating yourself, you can develop feature-rich, scalable applications with enhanced monitoring and seamless cloud integration. This guide provides a clear path to set up and configure these technologies, ensuring your applications are well-structured, maintainable, and ready for modern cloud environments.
Combining Aspire with the ABP framework creates a powerful setup for building robust, observable, and feature-rich applications. By integrating Aspire's observability and cloud capabilities with ABP's approach of focusing on your business without repeating yourself, you can develop feature-rich, scalable applications with enhanced monitoring and seamless cloud integration. This guide provides a clear path to set up and configure these technologies, ensuring your applications are well-structured, maintainable, and ready for modern cloud environments.
## See Also
* [.NET Aspire vs ABP Studio: Side by Side](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l)
* [Aspire vs ABP Studio: Side by Side](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l)

2
docs/en/Community-Articles/2024-08-01-abpio-platform-83-rc-has-been-published/post.md

@ -162,7 +162,7 @@ There are exciting articles contributed by the ABP community as always. I will h
* [Create a Generic HTTP Service to Consume a Web API](https://abp.io/community/articles/create-a-generic-http-service-to-consume-a-web-api-yidme2kq) by [Bart Van Hoey](https://github.com/bartvanhoey)
* [Use User-Defined Function Mapping for Global Filter](https://abp.io/community/articles/use-userdefined-function-mapping-for-global-filter-pht26l07) by [Liming Ma](https://github.com/maliming)
* [How to use .NET Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk) by [Berkan Şaşmaz](https://twitter.com/berkansasmazz)
* [How to use Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk) by [Berkan Şaşmaz](https://twitter.com/berkansasmazz)
* [Exciting New Feature in ABP.IO CMS Kit: Marked Item System](https://abp.io/community/articles/exciting-new-feature-in-abp.io-cms-kit-marked-item-system.-2hvpq0me) by [Suhaib Mousa](https://abp.io/community/members/suhaibmousa032@gmail.com)
Thanks to the ABP Community for all the content they have published. You can also [post your ABP-related (text or video) content](https://abp.io/community/posts/create) to the ABP Community.

2
docs/en/Community-Articles/2024-08-12-join-abp-at-net-conf-focus-on-ai/post.md

@ -17,7 +17,7 @@ Get ready for deep dives into AI integration, practical examples, and insights f
### Session Highlights
* **Getting Started with AI in .NET** by *Stephen Toub*
* **NET Aspire and Semantic Kernel** by *Steve Sanderson* and *Matthew Bolanos*
* **Aspire and Semantic Kernel** by *Steve Sanderson* and *Matthew Bolanos*
* **Interactive AI with Blazor and .NET** by *Dan Roth*
* **AI Models in .NET: From Local to Cloud** by *Bruno Capuano*
* **RAG with .NET and Azure SQL** by *Davide Mauri*

6
docs/en/Community-Articles/2024-10-01-SignalR-9-New-Features/Post.md

@ -44,7 +44,7 @@ public class MyHub : Hub
### Better Diagnostics and Telemetry
Microsoft focuses mainly on .NET Aspire nowadays. That’s why SignalR now integrates more deeply with the .NET Activity API, which is commonly used for distributed tracing. The enhancement is implemented for better monitoring in [.NET Aspire Dashboard](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash#using-the-dashboard-with-net-aspire-projects). To support this feature:
Microsoft focuses mainly on Aspire nowadays. That’s why SignalR now integrates more deeply with the .NET Activity API, which is commonly used for distributed tracing. The enhancement is implemented for better monitoring in [Aspire Dashboard](https://aspire.dev/dashboard/overview/). To support this feature:
1- Add these packages to your`csproj`:
@ -76,9 +76,9 @@ builder
builder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing.AddOtlpExporter());
```
Finally, you’ll see the **SignalR Hub** events on the [Aspire Dashboard](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/overview):
Finally, you’ll see the **SignalR Hub** events on the [Aspire Dashboard](https://aspire.dev/dashboard/overview/):
![.NET Aspire Activity Dashboard](signalr-activity-dashboard.png)
![Aspire Activity Dashboard](signalr-activity-dashboard.png)

54
docs/en/Community-Articles/2024-10-11-NET-Aspire-vs-ABP-Studio/POST.md

@ -1,18 +1,18 @@
# .NET Aspire vs ABP Studio: Side by Side
# Aspire vs ABP Studio: Side by Side
In this article, I will compare [.NET Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/) by [ABP Studio](https://abp.io/docs/latest/studio) by explaining their similarities and differences.
In this article, I will compare [Aspire](https://aspire.dev/) by [ABP Studio](https://abp.io/docs/latest/studio) by explaining their similarities and differences.
## Introduction
While .NET Aspire and ABP Studio are tools for different purpose with different scope and they have different approaches to solve the problems, many developers still may confuse since they also have some similar functionalities and solves some common problems.
While Aspire and ABP Studio are tools for different purpose with different scope and they have different approaches to solve the problems, many developers still may confuse since they also have some similar functionalities and solves some common problems.
In this article, I will clarify all, and you will have a clear understanding of what are the similarities and differences of them. Let's start by briefly define what are .NET Aspire and ABP Studio.
In this article, I will clarify all, and you will have a clear understanding of what are the similarities and differences of them. Let's start by briefly define what are Aspire and ABP Studio.
### What is .NET Aspire?
### What is Aspire?
**[.NET Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/)** is a **cloud-ready framework** designed to simplify building distributed, observable, and production-ready applications. It provides a set of opinionated tools and NuGet packages tailored for cloud-native concerns like **orchestration**, **service integration** (e.g., Redis, PostgreSQL), and **telemetry**. Aspire focuses on the **local development experience**, making it easier to manage complex, multi-service apps by **abstracting away configuration details**.
**[Aspire](https://aspire.dev/)** is a **cloud-ready framework** designed to simplify building distributed, observable, and production-ready applications. It provides a set of opinionated tools and NuGet packages tailored for cloud-native concerns like **orchestration**, **service integration** (e.g., Redis, PostgreSQL), and **telemetry**. Aspire focuses on the **local development experience**, making it easier to manage complex, multi-service apps by **abstracting away configuration details**.
Here, a screenshot from [.NET Aspire dashboard](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/overview) that is used for application monitoring and inspection:
Here, a screenshot from [Aspire dashboard](https://aspire.dev/dashboard/overview/) that is used for application monitoring and inspection:
![dotnet-aspire-dashboard](dotnet-aspire-dashboard.png)
@ -26,7 +26,7 @@ Here, a screenshot from the ABP Studio [Solution Runner panel](https://abp.io/do
## A Brief Comparison
Before deep diving details, I want to show a **table of features** to compare ABP Studio and .NET Aspire side by side:
Before deep diving details, I want to show a **table of features** to compare ABP Studio and Aspire side by side:
![abp-studio-vs-net-aspire-comparison-table](abp-studio-vs-dotnet-aspire-comparison-table.png)
@ -36,30 +36,30 @@ In the next sections, I will go through each feature and explain differences and
### Integration Packages
ABP Framework has tens of integration packages to 3rd-party libraries and services. .NET Aspire also has some library integrations. But these integrations have different purposes:
ABP Framework has tens of integration packages to 3rd-party libraries and services. Aspire also has some library integrations. But these integrations have different purposes:
* **ABP Framework**'s integrations (like [MongoDB](https://abp.io/docs/latest/framework/data/mongodb), [RabbitMQ](https://abp.io/docs/latest/framework/infrastructure/background-jobs/rabbitmq), [Dapr](https://abp.io/docs/latest/framework/dapr), etc) are integrations for its abstractions and aimed to be **used directly by your application code**. They are complete and sophisticated integrations with the ABP Framework and your codebase.
* **.NET Aspire**'s integrations (like [MongoDB](https://learn.microsoft.com/en-us/dotnet/aspire/database/mongodb-integration), [RabbitMQ](https://learn.microsoft.com/en-us/dotnet/aspire/messaging/rabbitmq-integration), [Dapr](https://learn.microsoft.com/en-us/dotnet/aspire/frameworks/dapr), etc), on the other hand, for simplifying configuration, service discovery, orchestration and monitoring of these tools within .NET Aspire host. Basically, these are mostly for **integrating to .NET Aspire**, not for integrating to your application.
* **Aspire**'s integrations (like [MongoDB](https://aspire.dev/integrations/databases/mongodb/), [RabbitMQ](https://aspire.dev/integrations/messaging/rabbitmq/), [Dapr](https://aspire.dev/integrations/frameworks/dapr/), etc), on the other hand, for simplifying configuration, service discovery, orchestration and monitoring of these tools within Aspire host. Basically, these are mostly for **integrating to Aspire**, not for integrating to your application.
For example, ABP's [MongoDB](https://abp.io/docs/latest/framework/data/mongodb) integration allows you to use MongoDB over [repository services](https://abp.io/docs/latest/framework/architecture/domain-driven-design/repositories), automatically handles database transactions, [audit logs](https://abp.io/docs/latest/framework/infrastructure/audit-logging), [event publishing](https://abp.io/docs/latest/framework/infrastructure/event-bus/distributed) on data saves, dynamic [connection string](https://abp.io/docs/latest/framework/fundamentals/connection-strings) management, [multi-tenancy](https://abp.io/docs/latest/framework/architecture/multi-tenancy) integration and so on.
On the other hand, .NET Aspire's [MongoDB](https://learn.microsoft.com/en-us/dotnet/aspire/database/mongodb-integration) integration basically adds [MongoDB driver library](https://www.nuget.org/packages/MongoDB.Driver/) to your .NET Aspire host application and configures it so you can discover MongoDB server on runtime, use a MongoDB Docker container and see its health status, logs and traces on .NET Aspire dashboard.
On the other hand, Aspire's [MongoDB](https://aspire.dev/integrations/databases/mongodb/) integration basically adds [MongoDB driver library](https://www.nuget.org/packages/MongoDB.Driver/) to your Aspire host application and configures it so you can discover MongoDB server on runtime, use a MongoDB Docker container and see its health status, logs and traces on Aspire dashboard.
### Starter Templates
Both of ABP Studio and .NET Aspire provide **startup solution templates for new applications**. However, there are huge differences between these startup solution templates and their purpose are completely different.
Both of ABP Studio and Aspire provide **startup solution templates for new applications**. However, there are huge differences between these startup solution templates and their purpose are completely different.
* ABP Studio provides **production-ready** and [advanced solution templates](https://abp.io/docs/latest/solution-templates) for **layered**, **modular** or **microservice** solution development. They are well configured for **local development** and deploying to **Kubernetes** and other **production environments**. They provide different **UI and database options**, many optional modules and configuration. For example, you can check the [microservice solution template](https://abp.io/docs/latest/solution-templates/microservice/overview) to see how **sophisticated** it is.
* .NET Aspire's [project templates](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/setup-tooling?tabs=windows&pivots=visual-studio#net-aspire-project-templates)' main purpose is to provide a minimal application structure that is **pre-integrated to .NET Aspire** libraries and configured for **local development** environment.
* Aspire's [project templates](https://aspire.dev/get-started/aspire-sdk-templates/)' main purpose is to provide a minimal application structure that is **pre-integrated to Aspire** libraries and configured for **local development** environment.
So, when you start with .NET Aspire project template, you will need to deal with a lot of work to make your solution production and enterprise ready. On the other hand, ABP Studio's solution templates are ready to launch your system from the first day and they provide you a perfect starting point for your new business idea.
So, when you start with Aspire project template, you will need to deal with a lot of work to make your solution production and enterprise ready. On the other hand, ABP Studio's solution templates are ready to launch your system from the first day and they provide you a perfect starting point for your new business idea.
### Monitoring & Application Running
Monitoring applications and services is an important requirement for building **complex distributed systems**. Both of ABP Studio and .NET Aspire provide **excellent tools** for that purpose.
Monitoring applications and services is an important requirement for building **complex distributed systems**. Both of ABP Studio and Aspire provide **excellent tools** for that purpose.
* ABP Studio's [Solution Runner panel](https://abp.io/docs/latest/studio/running-applications) provides a powerful UI to run and monitor applications and services. You can see all HTTP requests, distributed events, exceptions and detailed application logs, trace and find problems in your system. You can use its fully functional built-in browser to navigate application UIs easily. You can also create multiple profiles to group and configure the applications for different teams.
* .NET Aspire's [dashboard](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/overview) can be used to see the states of the running applications and containers, explore their console output, logs, traces and metrics to understand what is happing in your distributed system.
* Aspire's [dashboard](https://aspire.dev/dashboard/overview/) can be used to see the states of the running applications and containers, explore their console output, logs, traces and metrics to understand what is happing in your distributed system.
Both tools are pretty useful for monitoring. In addition to monitoring, **ABP Studio offers an advanced UI to control the running applications**, build, start and stop individually or by a group of applications.
@ -85,7 +85,7 @@ Here a screenshot that shows how to add new microservices, API gateways or web a
![abp-studio-add-new-microservice](abp-studio-add-new-microservice.png)
.NET Aspire has no such a feature and has no such a plan to provide that kind of architectural solution building experience.
Aspire has no such a feature and has no such a plan to provide that kind of architectural solution building experience.
### Kubernetes Integration
@ -99,11 +99,11 @@ Here, a few tasks you can accomplish using ABP Studio's Kubernetes integration:
* **Monitor** services and applications that are running in your Kubernetes cluster
* **Intercept traffic** of a service and redirect requests to your local machine. In that way, you can develop, test and run individual services or applications in your local computer that is **fully integrated** to other services and applications running in Kubernetes.
ABP Studio's Kubernetes Integration makes microservice development so easy and comfortable. On the other hand, .NET Aspire has no such a Kubernetes integrated development experience.
ABP Studio's Kubernetes Integration makes microservice development so easy and comfortable. On the other hand, Aspire has no such a Kubernetes integrated development experience.
## The ABP Platform
Until now, I directly compared ABP Studio and .NET Aspire features. .NET Aspire is directly built on .NET and ASP.NET Core. However, ABP Studio is not a standalone tool that is built on .NET and ASP.NET Core. It is built on the [ABP Platform](https://abp.io/) (which is built on .NET and ASP.NET Core).
Until now, I directly compared ABP Studio and Aspire features. Aspire is directly built on .NET and ASP.NET Core. However, ABP Studio is not a standalone tool that is built on .NET and ASP.NET Core. It is built on the [ABP Platform](https://abp.io/) (which is built on .NET and ASP.NET Core).
The following diagram shows ABP Platform components at a glance:
@ -111,26 +111,26 @@ The following diagram shows ABP Platform components at a glance:
So, when you use ABP Studio, you also take full power of the [open source ABP Framework](https://github.com/abpframework/abp) and other ABP Platform features.
## ABP and .NET Aspire Integration
## ABP and Aspire Integration
I have a good news to you. It is actually possible and pretty easy to make ABP Platform and .NET Aspire working together.
I have a good news to you. It is actually possible and pretty easy to make ABP Platform and Aspire working together.
You can check [@berkansasmaz](https://abp.io/community/members/berkansasmaz)'s great article: **[How to use .NET Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk)**.
You can check [@berkansasmaz](https://abp.io/community/members/berkansasmaz)'s great article: **[How to use Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk)**.
## Licensing
ABP Studio has a Community Edition which is completely free and available to everyone. It includes many of the features I mentioned here. There is also a commercial edition that is included in [commercial ABP licenses](https://abp.io/pricing). You can [check that blog post](https://abp.io/blog/announcing-abp-studio-general-availability) which clearly explains the license differences and introduces the fundamental ABP Studio features.
On the other hand, .NET Aspire is a free tool developed and published by Microsoft. It has no commercial version.
On the other hand, Aspire is a free tool developed and published by Microsoft. It has no commercial version.
## Conclusion
Both .NET Aspire and ABP Studio serve distinct purposes, catering to different types of development environments. While .NET Aspire excels in simplifying cloud-native application setups and observability, ABP Studio provides a comprehensive framework for modular monoliths and microservice architectures with full-fledged enterprise level production-ready startup solution templates and integrated tools.
Both Aspire and ABP Studio serve distinct purposes, catering to different types of development environments. While Aspire excels in simplifying cloud-native application setups and observability, ABP Studio provides a comprehensive framework for modular monoliths and microservice architectures with full-fledged enterprise level production-ready startup solution templates and integrated tools.
In the previous section, it was mentioned that it is possible to [use them together](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk). You don't have to select one of them. However, in my opinion, when you use ABP Studio, you won't need .NET Aspire since ABP Studio can do everything and much more. If you have budget, I suggest to purchase a commercial ABP Studio [license](https://abp.io/pricing) so you can fully unlock its power.
In the previous section, it was mentioned that it is possible to [use them together](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk). You don't have to select one of them. However, in my opinion, when you use ABP Studio, you won't need Aspire since ABP Studio can do everything and much more. If you have budget, I suggest to purchase a commercial ABP Studio [license](https://abp.io/pricing) so you can fully unlock its power.
## Resources / Further Reading
* [ABP Studio documentation](https://abp.io/docs/latest/studio)
* [.NET Aspire documentation](https://learn.microsoft.com/en-us/dotnet/aspire/)
* [How to use .NET Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk)
* [Aspire documentation](https://aspire.dev/)
* [How to use Aspire with ABP framework](https://abp.io/community/articles/how-to-use-.net-aspire-with-abp-framework-h29km4kk)

2
docs/en/Community-Articles/2024-10-23-abpio-platform-90-rc-has-been-published/post.md

@ -205,7 +205,7 @@ There are exciting articles contributed by the ABP community as always. I will h
* [Mohammad AlMohammad AlMahmoud](https://abp.io/community/members/Mohammad97Dev) has created **two** new community articles:
* [Implementing Multi-Language Functionality With ABP Framework](https://abp.io/community/articles/implementing-multilanguage-functionality-with-abp-framework-loq7kfx4)
* [Configure Quartz.Net in Abp FrameWork](https://abp.io/community/articles/configure-quartz.net-in-abp-framework-3bveq4y1)
* [.NET Aspire vs ABP Studio: Side by Side](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l) by [Halil İbrahim Kalkan](https://twitter.com/hibrahimkalkan)
* [Aspire vs ABP Studio: Side by Side](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l) by [Halil İbrahim Kalkan](https://twitter.com/hibrahimkalkan)
* [PoC of using GrapesJS for ABPs CMS Kit](https://abp.io/community/articles/poc-of-using-grapesjs-for-abps-cms-kit-1rmv4q41) by [Jack Fistelmann](https://abp.io/community/members/jfistelmann)
* [ABP-Powered Web App with Inertia.js, React, and Vite](https://abp.io/community/articles/abppowered-web-app-with-inertia.js-react-and-vite-j7cccvad) by [Anto Subash](https://antosubash.com/)
* [Multi-Tenancy Support in Angular Apps with ABP.IO](https://abp.io/community/articles/multitenancy-support-in-angular-apps-with-abp.io-lw9l36c5) by [HeadChannel Team](https://headchannel.co.uk/)

26
docs/en/Community-Articles/2024-11-05-.NET Aspire 9.0 Features/Post.md

@ -1,27 +1,27 @@
# .NET Aspire 9.0 Features
# Aspire 9.0 Features
.NET Aspire 9.0 is the next major release, supporting both .NET 8 and .NET 9. This version includes new features and improvements.
Aspire 9.0 is the next major release, supporting both .NET 8 and .NET 9. This version includes new features and improvements.
## Upgrade to .NET Aspire
## Upgrade to Aspire
Now, you don't need workloads to develop .NET Aspire applications. In your project, you can add an SDK reference to `Aspire.AppHost.Sdk`.
For more information, you can check out [https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9?tabs=windows#upgrade-to-net-aspire-9](https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9?tabs=windows#upgrade-to-net-aspire-9) which explains upgrading an existing project in details.
Now, you don't need workloads to develop Aspire applications. In your project, you can add an SDK reference to `Aspire.AppHost.Sdk`.
For more information, you can check out [https://aspire.dev/whats-new/aspire-9/#upgrade-to-aspire-9](https://aspire.dev/whats-new/aspire-9/#upgrade-to-aspire-9) which explains upgrading an existing project in details.
## Dashboard
.NET Aspire offers a nice dashboard for developers to observe the performance and behavior of their applications. In this version, there are some enhancements;
Aspire offers a nice dashboard for developers to observe the performance and behavior of their applications. In this version, there are some enhancements;
* **Manage resource lifecycle**: You can stop, start, and restart resources.
* **Mobile and responsive support**: The .NET Aspire dashboard is now mobile-friendly.
* **Mobile and responsive support**: The Aspire dashboard is now mobile-friendly.
* **Sensitive properties**: Properties can be marked as sensitive, automatically masking them in the dashboard UI.
* **Volumes**: Configured container volumes are listed in resource details.
* **Health checks**: .NET Aspire 9 adds support for health checks.
* **Health checks**: Aspire 9 adds support for health checks.
![Resource Lifecycle](./aspire_resource_lifecycle.jpg)
## Telemetry
.NET Aspire 9 comes with many new features to the Telemetry service.
Aspire 9 comes with many new features to the Telemetry service.
* **Improve telemetry filtering**: Telemetry data can now be filtered by attribute values.
* **Combine telemetry from multiple resources**: If a resource has multiple replicas, you can now filter telemetry data to view from all instances.
@ -32,23 +32,23 @@ For more information, you can check out [https://learn.microsoft.com/en-us/dotne
## Orchestration
The .NET App Host is a core component of the .NET runtime that helps launch and execute .NET applications.
.NET Aspire 9 introduces many new features to the app host. Let's take a look;
Aspire 9 introduces many new features to the app host. Let's take a look;
* **Waiting for dependencies**: You can configure a resource to wait for another resource to start before starting.
* **Resource health checks**: The `Waiting for dependencies` feature uses health checks to determine if a resource is ready.
## Integrations
.NET Aspire has integrations with some services and tools that make it easy to get started. New integrations are coming with .NET Aspire 9.
Aspire has integrations with some services and tools that make it easy to get started. New integrations are coming with Aspire 9.
* Redis Insight
* OpenAI (Preview)
* MongoDB
* Azure
For Azure part, it is better to check the official documentation here [https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9-release-candidate-1?tabs=windows&pivots=visual-studio#azure](https://learn.microsoft.com/en-us/dotnet/aspire/whats-new/dotnet-aspire-9-release-candidate-1?tabs=windows&pivots=visual-studio#azure) because it has a very detailed explanation.
For Azure part, it is better to check the official documentation here [https://aspire.dev/whats-new/aspire-9/#important-azure-improvements](https://aspire.dev/whats-new/aspire-9/#important-azure-improvements) because it has a very detailed explanation.
## ABP Studio
.NET Aspire and [ABP Studio](https://abp.io/studio) are tools for different purposes with different scopes, and they have different approaches to solving problems; many developers may still be confused since they also have some similar functionalities and solve some common problems. You can check the comparison of .NET Aspire and ABP Studio in this [article](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l).
Aspire and [ABP Studio](https://abp.io/studio) are tools for different purposes with different scopes, and they have different approaches to solving problems; many developers may still be confused since they also have some similar functionalities and solve some common problems. You can check the comparison of Aspire and ABP Studio in this [article](https://abp.io/community/articles/.net-aspire-vs-abp-studio-side-by-side-t1c73d1l).

6
docs/en/Community-Articles/2025-11-30-NET-Conf-China-2025/POST.md

@ -10,9 +10,9 @@ This year’s conference focused on three main themes: performance improvements,
### Opening Keynote
Scott Hanselman kicked off .NET Conf China 2025 with a video keynote, announcing that .NET 10 is now available on the official website. He framed the release around four pillars—AI, cloud-native, cross-platform, and performance—including integration with the Microsoft Agent Framework for building and orchestrating multi-agent systems in .NET/C#, industry-leading container and Kubernetes support with .NET Aspire simplifying local containerized development, a richer cross-platform desktop ecosystem (.NET MAUI, Avalonia, Uno Platform), and major performance gains such as Native AOT and single-file publishing for faster startup and easier distribution across platforms.
Scott Hanselman kicked off .NET Conf China 2025 with a video keynote, announcing that .NET 10 is now available on the official website. He framed the release around four pillars—AI, cloud-native, cross-platform, and performance—including integration with the Microsoft Agent Framework for building and orchestrating multi-agent systems in .NET/C#, industry-leading container and Kubernetes support with Aspire simplifying local containerized development, a richer cross-platform desktop ecosystem (.NET MAUI, Avalonia, Uno Platform), and major performance gains such as Native AOT and single-file publishing for faster startup and easier distribution across platforms.
He underscored China’s importance as .NET’s second-largest market, with roughly 13% of users, and noted that generative AI usage in China has doubled in 2025. The local community is seeing strong momentum around ML.NET, .NET Aspire, and the C# Dev Kit in VS Code. Reflecting on his Baby Smash game written 20 years ago, which now runs cross-platform on .NET 10, he called on developers to modernize: move existing Web, WinForms, and WPF apps to the cloud, improve performance, ship as a single executable, and weave in AI capabilities.
He underscored China’s importance as .NET’s second-largest market, with roughly 13% of users, and noted that generative AI usage in China has doubled in 2025. The local community is seeing strong momentum around ML.NET, Aspire, and the C# Dev Kit in VS Code. Reflecting on his Baby Smash game written 20 years ago, which now runs cross-platform on .NET 10, he called on developers to modernize: move existing Web, WinForms, and WPF apps to the cloud, improve performance, ship as a single executable, and weave in AI capabilities.
On AI, he emphasized a human-centered stance: AI and agents should augment, not replace, developers. In the future, developers will orchestrate and govern agents, and human judgment will matter more than ever. He closed by thanking the open-source community for its many proposals and pull requests, stressing that .NET is an open-source platform built together by Microsoft and the community, and wishing everyone an inspiring conference and a joyful journey with .NET 10.
@ -28,7 +28,7 @@ The roundtable discussion, titled “Empowering with AI, Breaking Through Cross-
The afternoon featured four breakout sessions, covering a wide range of topics with deep dives into both foundational technologies and real-world project reviews:
- **Frontend and Cross-Platform:** Focused on the progress of Avalonia, Blazor, and WebAssembly, as well as the integrated experience of .NET Aspire in multi-service applications. Speakers shared insights on reusing core logic between desktop and web, shortening cold start times with incremental compilation and resource trimming, and performance profiling and optimization in WASM scenarios.
- **Frontend and Cross-Platform:** Focused on the progress of Avalonia, Blazor, and WebAssembly, as well as the integrated experience of Aspire in multi-service applications. Speakers shared insights on reusing core logic between desktop and web, shortening cold start times with incremental compilation and resource trimming, and performance profiling and optimization in WASM scenarios.
- **AI Agents and Enterprise Adoption:** Discussed multi-agent orchestration, the MCP plugin ecosystem, and enterprise data compliance. From common pitfalls of “demo-level” AI to the “five-step method” for moving from POC to production, the session covered use cases like knowledge retrieval, process automation, intelligent customer service, and developer assistants, emphasizing evaluation metrics, prompt engineering, and monitoring governance.
- **.NET Practices and Engineering:** Focused on the latest capabilities and performance practices of EF Core, the boundaries of NativeAOT, automated testing strategies, and observability implementation. Discussions included database migration strategies, caching and concurrency control for hot paths, end-to-end tracing, and structured logging.
- **Solutions and Case Studies:** From Clean Architecture/DDD to AI-powered business evolution, topics included application modernization, SaaS transformation, and edge-cloud collaboration in AIoT. Speakers broke down modular governance, team collaboration, and release strategies for complex systems, putting “delivering value continuously” at the center stage.

450
docs/en/Community-Articles/2026-07-07-resource-based-api-for-angular/POST.md

@ -0,0 +1,450 @@
# Angular Resource APIs Explained: Generating Signal-Based Service Proxies
Angular's shift toward **Signals** has changed how applications model state and data loading. Instead of manually coordinating subscriptions, loading flags, and error handling, Angular now provides resource APIs that integrate asynchronous data fetching directly into the signal ecosystem.
To embrace this programming model, ABP now offers an **optional Resource API generation mode** for Angular service proxies. When enabled, the proxy generator produces signal-friendly APIs for read operations while preserving the familiar Observable-based experience for the rest of your application.
This article introduces the new Resource API generation mode, explains why it exists, how it works, and when it should be preferred over traditional Observable-based proxies.
---
## Why Resource APIs
For years, Angular applications have relied on observable-based services to communicate with backend APIs. While Observables remain extremely powerful, consuming them inside components often requires additional state management.
A typical read operation usually involves:
- subscribing to an Observable,
- tracking loading state,
- storing the latest value,
- handling errors,
- cleaning up subscriptions when necessary.
As applications adopt Signals for local state, this pattern starts to feel increasingly imperative. The component becomes responsible not only for displaying data, but also for orchestrating the entire request lifecycle.
Angular's Resource APIs address this problem by treating asynchronous data as reactive state. Instead of manually reacting to changes, you describe **what the request depends on**, and Angular automatically keeps the resource synchronized.
For example, if a request depends on an entity ID represented as a `Signal`, changing that signal automatically triggers a new request. The component no longer needs to manually subscribe or invoke refresh logic simply because an input changed.
This approach offers several benefits:
- loading, error, and value state are managed together,
- requests automatically react to signal changes,
- components become more declarative,
- significantly less boilerplate is required.
Resource APIs are therefore an excellent fit for **read-only data retrieval**, where the primary goal is to keep the UI synchronized with backend state.
---
## What Angular Gives Us
Angular provides several APIs for working with asynchronous resources, each targeting a slightly different use case.
### `resource`
The `resource` API is Angular's generic primitive for asynchronous state.
It is designed for loaders that return promise-based results and automatically exposes:
- the current value,
- loading status,
- errors,
- reload capabilities.
This API is ideal when your asynchronous source is not based on RxJS.
### `rxResource`
Most Angular applications—including ABP applications—already communicate with the backend through `HttpClient`, whose APIs return Observables.
The `rxResource` helper bridges these existing Observable streams with Angular's Resource model. Instead of rewriting existing services to use Promises, it simply wraps an Observable-producing function and exposes it as a reactive resource.
Internally, the new ABP proxy generation mode uses this approach. Generated resource methods eventually call the existing `RestService` request pipeline, while exposing the result as an Angular `ResourceRef`. This means existing authentication, interceptors, multi-tenancy, localization, error handling, and other ABP infrastructure continue to work exactly as before.
### `httpResource`
Angular also provides `httpResource`, which is a specialized resource implementation built directly on top of `HttpClient`.
For applications making direct HTTP requests, this can be a convenient option.
However, ABP applications already centralize HTTP communication through `RestService`, which adds framework-specific behavior around every request. Because of that, the generated proxies rely on `rxResource` rather than `httpResource`, allowing them to preserve the entire ABP request pipeline while still providing a signal-based API.
In short:
| API | Intended for |
| --- | --- |
| `resource` | Generic asynchronous loaders returning Promises |
| `rxResource` | Existing RxJS/Observable-based data sources |
| `httpResource` | Direct `HttpClient` requests without additional abstraction |
Since ABP proxies already build on top of `RestService`, `rxResource` is the natural choice for bringing Signal-based data loading to generated client proxies.
---
## Why This Feature Is Opt-In
One of the primary goals of the new Resource API generation mode is to introduce a modern, Signal-friendly API **without disrupting existing applications**.
ABP's generated Angular service proxies have been Observable-based for years, and they continue to serve a wide range of applications effectively. Many projects already rely on RxJS operators, custom Observable pipelines, and existing component patterns. Replacing those generated APIs would introduce unnecessary breaking changes for little benefit.
Instead, Resource API generation is **completely opt-in**.
By passing the `--resource-api` option to the `abp generate-proxy` command, the generator produces additional resource helpers designed for Angular's Signal ecosystem. If you do not enable the option, proxy generation behaves exactly as it always has, producing the familiar Observable-based services.
This gradual approach offers several advantages:
- Existing applications continue working without modification.
- Teams can adopt Signals incrementally instead of performing a large migration.
- New pages can embrace Resource APIs while older features continue using Observables.
- Developers remain free to choose the programming model that best fits each feature.
Another intentional design decision is that **only read operations receive Resource API helpers**.
Resource APIs naturally model asynchronous state that can be refreshed whenever their reactive inputs change. This makes them an excellent fit for `GET` requests, where the goal is to retrieve and synchronize data.
Write operations such as `POST`, `PUT`, `PATCH`, and `DELETE` represent user actions rather than continuously synchronized state. These operations are typically composed with RxJS pipelines, optimistic updates, notifications, or custom error handling, making Observables the more appropriate abstraction.
By limiting Resource APIs to read operations, generated proxies follow Angular's recommended usage patterns while keeping mutation APIs predictable and familiar.
---
## Generator Behavior
Enabling Resource API generation requires only a single additional option:
```bash
abp generate-proxy -t ng --resource-api
```
Without this option, the generator behaves exactly as before, producing standard Observable-based service methods.
For example, a generated service might expose a method like:
```tsx
bookService.getList(input);
```
which returns an `Observable` and can be consumed with RxJS operators or converted into Signals using Angular's interoperability utilities.
When `--resource-api` is enabled, the generator **preserves these existing methods** and additionally generates companion Resource API methods for every `GET` endpoint.
For example:
```tsx
bookService.getList(...); // Observable
bookService.getListResource(...); // ResourceRef
```
These generated resource methods internally use Angular's `rxResource` while continuing to execute requests through ABP's existing `RestService`. As a result, the complete ABP request pipeline—including authentication, interceptors, localization, multi-tenancy, and error handling—remains unchanged.
The generator only creates resource helpers for `GET` endpoints. Mutation methods such as `create`, `update`, and `delete` continue to return Observables exactly as before.
This selective generation keeps the generated API straightforward:
- **Read operations** gain Signal-friendly Resource APIs.
- **Write operations** continue using Observables.
- **Existing Observable methods remain available**, allowing gradual adoption without forcing a migration.
In the next section, we'll examine the shape of the generated Resource API methods and see how they integrate naturally with Angular Signals.
---
## Generated API Shape
The generated Resource API methods closely resemble their Observable counterparts, making them easy to adopt. Rather than introducing an entirely new programming model, they adapt the existing proxy APIs to Angular's Signal ecosystem.
There are, however, a few important differences.
### Signal-Based Inputs
Traditional proxy methods accept plain values:
```tsx
bookService.get(id);
```
The generated Resource API methods instead accept **Signals**.
```tsx
const id = signal('42');
const book = bookService.getResource(id);
```
Because the input is reactive, Angular automatically re-executes the request whenever the signal value changes.
```tsx
id.set('43');
```
No additional method calls, subscriptions, or refresh logic are required—the resource stays synchronized with its dependencies automatically.
### Returning a `ResourceRef`
Observable-based proxy methods return an `Observable<T>`.
Resource methods instead return a `ResourceRef<T>`, which exposes the request state as Signals.
This gives components access to everything they typically need during data loading:
- the current value,
- loading status,
- any request error,
- reload functionality.
A component can consume the resource directly:
```tsx
const book = bookService.getResource(id);
book.value();
book.isLoading();
book.error();
book.reload();
```
Instead of maintaining separate signals for loading, data, and errors, the resource keeps these states together in a single reactive object.
### Reactive Request Construction
Many API endpoints require multiple parameters or request objects.
Rather than asking developers to manually rebuild those objects whenever an input changes, the generated methods construct the request reactively using Angular's `computed()` API.
Suppose a request depends on pagination and a search keyword:
```tsx
const page = signal(1);
const filter = signal('');
```
The generated proxy internally derives the request object from these Signals.
Whenever either value changes, Angular recomputes the request and automatically performs a new HTTP request.
This means developers only manage application state. The generated proxy takes care of determining **when** a request should be refreshed.
---
## Examples
Let's compare a few common scenarios to see how generated Resource APIs look in practice.
### Fetching a Single Entity
A traditional generated proxy might be used like this:
```tsx
bookService.get(id).subscribe(...);
```
With Resource API generation enabled:
```tsx
const id = signal('42');
const book = bookService.getResource(id);
```
Changing the ID automatically reloads the resource.
```tsx
id.set('84');
```
The component simply reads the latest value:
```tsx
book.value();
```
Angular handles the request lifecycle automatically.
### Fetching a List with Query Parameters
List endpoints become even more interesting because they usually depend on multiple reactive inputs.
Consider a search page with pagination.
```tsx
const filter = signal('');
const skipCount = signal(0);
const maxResultCount = signal(10);
```
Using the generated proxy is straightforward:
```tsx
const books = bookService.getListResource({
filter,
skipCount,
maxResultCount,
});
```
Whenever any of these Signals changes, Angular automatically refreshes the resource.
```tsx
filter.set('Angular');
skipCount.set(20);
```
There is no need to manually call `getList()` again or synchronize subscriptions with UI state.
### Behind the Scenes
Although the generated API feels simple to consume, the proxy performs a considerable amount of work internally.
Conceptually, the generated method looks similar to the following:
```tsx
getListResource(input: {
filter: Signal<string>;
skipCount: Signal<number>;
maxResultCount: Signal<number>;
}): ResourceRef<PagedResultDto<BookDto>> {
return this.restService.requestResource({
method: 'GET',
url: '/api/app/books',
params: computed(() => ({
filter: input.filter(),
skipCount: input.skipCount(),
maxResultCount: input.maxResultCount(),
})),
});
}
```
Notice that every request parameter is read inside a `computed()` callback. This establishes Angular's reactive dependency tracking, ensuring that any change to an input Signal automatically triggers a new request.
As a consumer, you never need to think about this implementation detail. You simply update your Signals, and the generated proxy keeps the resource synchronized with your application's state.
---
## Best Practices
As with any new Angular feature, Resource APIs are most effective when used in the scenarios they were designed for. The following recommendations can help you get the most out of generated Resource-based proxies while keeping your codebase clean and maintainable.
### Use Resource APIs for Read Operations
Resource APIs are designed to represent **reactive, read-only state**.
Whenever your UI needs to retrieve data that should stay synchronized with one or more Signals, generated resource methods are an excellent choice.
Typical examples include:
- entity details,
- paginated lists,
- search results,
- dashboard widgets,
- lookup data.
These scenarios naturally benefit from automatic reloading whenever their reactive inputs change.
### Keep Mutations as Observable Methods
Operations that modify server state—such as creating, updating, or deleting data—should continue using the standard Observable-based proxy methods.
Mutation requests often involve additional workflows such as:
- displaying success notifications,
- handling validation errors,
- optimistic UI updates,
- chaining additional requests,
- navigation after completion.
These workflows fit naturally into RxJS pipelines, which is why the generator intentionally keeps write operations unchanged.
### Let Signals Drive Your Requests
One of the biggest advantages of Resource APIs is that you no longer decide **when** to issue a request.
Instead, you describe **what the request depends on**, and Angular takes care of the rest.
Rather than writing code like:
```tsx
filter.valueChanges.subscribe(() => loadBooks());
```
simply update the underlying Signals.
Whenever those Signals change, the generated resource automatically refreshes itself.
This declarative approach removes much of the manual subscription and synchronization logic that traditionally accumulates in Angular components.
### Build Request Objects with `computed()`
When an endpoint accepts multiple parameters, derive the request object using `computed()` instead of constructing it manually.
For example:
```tsx
const request = computed(() => ({
filter: filter(),
skipCount: skipCount(),
maxResultCount: maxResultCount(),
}));
```
This ensures Angular can correctly track every dependency involved in the request.
Likewise, avoid reading Signal values outside of the reactive computation.
Instead of extracting Signal values first:
```tsx
const currentFilter = filter();
const request = computed(() => ({
filter: currentFilter,
}));
```
read them directly inside the `computed()` callback:
```tsx
const request = computed(() => ({
filter: filter(),
}));
```
Doing so allows Angular to react whenever those Signals change.
### Consume the Entire `ResourceRef`
A generated resource provides much more than the retrieved value.
Instead of creating separate Signals for loading and error state, consume the `ResourceRef` directly.
For example:
- `value()` exposes the latest successful result.
- `isLoading()` indicates whether a request is in progress.
- `error()` provides the latest request failure.
- `reload()` manually refreshes the resource when needed.
Keeping these states together makes components easier to understand and reduces state duplication.
### Choose the Right Resource API
Angular offers multiple Resource APIs, each serving a different purpose.
For generated ABP service proxies, the recommended approach is the generated Resource API based on `rxResource`, since it preserves the existing `RestService` pipeline and all of its framework integrations.
If you're writing standalone Angular services that communicate directly with `HttpClient`, `httpResource` may be a better fit.
Choosing the appropriate abstraction helps keep both your generated code and handwritten services consistent with Angular's intended usage patterns.
---
## Conclusion
Angular Signals have introduced a more declarative way to manage application state, and Resource APIs naturally extend that model to asynchronous data loading.
With Resource API generation, ABP brings this programming model directly into generated Angular service proxies. Read operations become reactive, Signal-driven, and significantly easier to consume, while write operations continue using the familiar Observable-based APIs that already work well for mutations.
Most importantly, this evolution is completely opt-in. Existing applications can continue using their current proxies without modification, while new features can gradually adopt Resource APIs wherever they provide the greatest benefit.
Whether you're building a new Signal-first Angular application or incrementally modernizing an existing ABP solution, Resource-based proxy generation offers a straightforward path toward cleaner components, less boilerplate, and a more reactive data-fetching experience.

511
docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/Post.md

@ -0,0 +1,511 @@
If you come from plain ASP.NET Core and open your first ABP solution, the initial reaction is often the same: *why are there so many projects, layers, DTOs, interfaces and base classes just to build a simple feature?* 🤔
That reaction is normal 👌
ABP Framework gives you a lot on day one: modularity, DDD-friendly structure, application services, repositories, auto API controllers, authorization, auditing, multi-tenancy and UI integration patterns.
The upside is speed and consistency on serious business apps.
The downside is that beginners can hit an abstraction wall before they see the payoff.
After reviewing recent discussions, one pattern is clear: most developers do not struggle with C# or ASP.NET Core itself.
They struggle with *where code is supposed to go* in ABP and *which parts are essential versus optional*.
In this post, I'll focus on that gap. If you are new to ABP, here is what actually helps.
## The biggest learning barrier is not syntax! It is responsibility boundaries
The hardest part for most newcomers is not learning one more framework API.
It's understanding the architectural split:
- What belongs in the **Domain** layer?
- What belongs in **Application** services?
- Why do **DTOs** exist if you already have entities?
- When do you need a **repository**?
- Why are there separate projects like `Application.Contracts`, `Domain.Shared` and `EntityFrameworkCore`?
In plain ASP.NET Core apps, many developers put a lot of this logic in controllers, services or even EF Core models.
ABP forces you toward clearer separation.
A practical mental model:
- **Entity / Aggregate Root**: business state and core invariants
- **Domain Service**: domain logic that does not naturally belong to a single entity
- **Repository**: persistence access for aggregates
- **Application Service**: use-case orchestration, authorization, DTO mapping, transaction boundary
- **DTO**: data contract for input/output
- **UI / API layer**: presentation concerns only
> That sounds clean on paper...
> The confusion starts when you build something real 🥴
### A simple example: where should validation go?
Suppose you are creating an `Order`.
- If the rule is "order total must be greater than zero," **that's domain logic**.
- If the rule is "only users with the Orders.Create permission can create an order," **that belongs in the application layer**.
- If the rule is "customer name is required on this page," **that may exist in DTO validation too**.
New ABP developers often ask which layer owns relationships, validation and business rules.
> The honest answer is: different validation lives in different places.
That is the first ABP lesson worth learning👍
![Generated illustration](abp-layers.png)
## Why ABP Feels Heavy at First!
**ABP is opinionated**. It's not trying to be the thinnest possible wrapper over ASP.NET Core.
What beginners usually experience as "**too much structure**" comes from 4 things:
### 1. Project and layer count
A typical ABP solution can include:
- `Domain`
- `Domain.Shared`
- `Application`
- `Application.Contracts`
- `EntityFrameworkCore`
- `HttpApi`
- `HttpApi.Client`
- UI project such as MVC, Razor Pages, Blazor or Angular
- Test projects
For a small feature, that can feel excessive... **For a long-lived business system, it starts to make sense**.
### 2. Generated convenience hides the mechanics
ABP can generate a lot of CRUD plumbing and generic base classes like `CrudAppService` reduce repetitive code.
That's useful, but it can also hide how things connect.
<u>A beginner sees a working page and API without fully understanding:</u>
- how the application service is exposed as an API
- where repository methods are coming from
- how DTO mapping works
- why the UI calls application contracts instead of entities
### 3. DDD terminology raises the entry cost
You do not need to become a DDD master to use ABP well... But ABP definitely assumes some familiarity with:
- entities
- aggregate roots
- repositories
- value objects
- domain services
- bounded contexts and modules
If those ideas are new, ABP can feel harder than it really is.
### 4. UI integration is not always obvious
Newcomers also get stuck on the end-to-end flow:
1. User clicks a button on a Razor Page or Blazor page
2. UI sends data to an application service or HTTP API
3. Application service validates permissions and input
4. Domain and repository code runs
5. DTO comes back to the UI
Once you understand that flow, ABP becomes much more predictable.
## Start with CRUD, but do not stop there
A common question is whether beginners should start with simple CRUD or jump straight into a realistic business module.
My view: **start with CRUD, then quickly move to a business feature with real rules**.
### Why CRUD is the right first step
CRUD teaches the ABP basics with low cognitive load:
- project structure
- entity definition
- DTOs
- repositories
- application services
- permissions
- UI page wiring
- migrations and database updates
This is why the [ABP BookStore tutorial](https://abp.io/docs/latest/tutorials/book-store) is a useful starting point.
### Why CRUD alone is not enough
Pure CRUD can give you a false sense of understanding.
A generated Create / Read / Update / Delete screen does not force you to deal with:
- aggregate boundaries
- child collections
- business invariants
- cross-entity rules
- domain services
- richer authorization scenarios
- multi-tenancy behavior
- auditing decisions
Those are the areas where ABP starts to justify its structure.
### A better learning sequence
Use this progression:
1. Build one very small CRUD module
2. Rebuild part of it manually instead of relying only on generation
3. Build one realistic business module with at least one non-trivial rule
4. Add authorization, validation and a relationship
5. Add tests around the domain or application service
That path keeps the early win while exposing the real architecture.
![Generated illustration](crud-vs-manual.png)
## Generated CRUD vs manual CRUD: learn both
This is one of the most useful mindset shifts for ABP beginners.
**Generated CRUD is for productivity. Manual CRUD is for understanding.**
You need both.
### When generated CRUD helps
ABP Suite and ABP base services can save time when the feature is mostly standard admin functionality:
- back-office reference data
- simple management screens
- low-risk maintenance pages
- conventional DTO/entity flows
If the goal is shipping business software efficiently, generated code is not cheating. It is leverage.
### When manual implementation matters
You should manually implement at least one feature end to end so you understand:
- how `CrudAppService` reduces boilerplate
- what repository methods are doing
- where validation belongs
- how authorization is applied
- how auto API controllers expose application services
A lot of Reddit confusion around ABP comes from learning generated patterns before understanding the underlying manual version.
### A good exercise
Build `Product` management twice:
- First with `CrudAppService`
- Then manually with custom application service methods and domain rules
Compare both implementations. That single exercise teaches more than reading docs for hours.
## Which DDD patterns real ABP teams often simplify
This is where many beginners get relief: **not every ABP project uses full-strength DDD all the time.**
Real teams often simplify the model, especially early on.
### Patterns teams commonly keep
These tend to deliver value quickly in ABP:
- clear application service boundaries
- entities and aggregate roots
- repositories
- DTO separation
- modular structure
- permission-based authorization
### Patterns teams often delay or reduce
These are useful in the right context, but many teams do not force them into every feature:
- dedicated domain services for very simple logic
- value objects for every tiny concept
- specification pattern everywhere
- excessive interface layering where no variation is expected
- over-splitting modules too early
### A practical rule of thumb
Use the simplest thing that preserves clarity.
For example:
- If a rule is trivial and local to one use case, putting it in an application service may be fine.
- If a rule protects business invariants and must hold regardless of caller, move it into the domain model.
- If a concept has behavior and invariants of its own, a value object may help.
- If it is just a shared enum or constant, `Domain.Shared` is often enough.
ABP supports rich DDD patterns, but it does not require ceremony for ceremony's sake.
![Generated illustration](abp-learning-path.png)
## A concrete “ASP.NET Core to ABP” learning path
If I had to design a practical learning path for experienced ASP.NET Core developers, it would look like this.
### Step 1: Know what ABP is adding on top of ASP.NET Core
Before touching templates, be comfortable with:
- dependency injection
- configuration
- middleware basics
- EF Core or MongoDB
- controllers or Razor Pages or Blazor basics
- validation and authorization in ASP.NET Core
> ABP builds on top of these. It does not replace the need to understand them.
### Step 2: Learn the ABP solution structure
Let's see each layer's goal:
- `Domain`: core business model
- `Domain.Shared`: shared enums, constants, localization resources, simple shared types
- `Application.Contracts`: DTOs and service contracts
- `Application`: use cases and orchestration
- `EntityFrameworkCore`: database mappings and repository implementation details
- `HttpApi`: API exposure
- UI project: user interaction
### Step 3: Understand modules and dependencies
ABP's modularity is a major feature, but beginners often treat modules like folders with extra steps.
They are more than that.
A module defines:
- dependency boundaries
- service registration scope
- reusable feature packaging
- initialization points via module lifecycle methods and `[DependsOn]`
At first, use modules as organizational boundaries inside a modular monolith. Do not rush into distributed or microservice-style decomposition.
### Step 4: Build one CRUD feature the ABP way
Create a simple feature such as Books, Products or Categories.
Make sure you understand:
- entity creation
- migration flow
- DTO mapping
- application service methods
- permission checks
- how the UI or API calls the application layer
### Step 5: Rebuild one part manually
Now remove the training wheels for one feature.
Instead of only leaning on base classes, explicitly write:
- a custom application service method
- a custom repository query if needed
- domain validation or invariants
- a tailored DTO instead of generic CRUD shapes
This is where ABP usually clicks.
### Step 6: Build a realistic business module
A good example is `Order Management`, `Leave Requests` or `Inventory Transfer`.
Choose something with:
- one-to-many relationship
- status transitions
- authorization rules
- at least one business invariant
- audit visibility
That reveals why ABP's layered structure exists.
### Step 7: Add built-in ABP concerns on purpose
ABP shines when you use its built-in platform features intentionally:
- authorization
- auditing
- validation
- localization
- multi-tenancy
- settings and permissions
Do not treat these as advanced extras. They are part of the framework's real value.
### Step 8: Learn testing by layer
Even if you do not build a full testing strategy immediately, understand the testing shape:
- domain tests for invariants and business rules
- application tests for use cases and permissions
- integration tests for persistence and module wiring
A lot of ABP's architecture pays off once you start testing behavior in isolation.
## A small example of responsibility split
Here is a deliberately small example to make the layering less abstract.
Suppose you have a leave request system.
**Domain** concerns:
- a leave request cannot be approved after rejection
- end date cannot be before start date
- total leave days must be positive
**Application** concerns:
- only managers can approve requests
- map input DTO to entity operations
- return a DTO shaped for the UI
- coordinate repository access and unit of work
**UI** concerns:
- disable approve button when user lacks permission
- show validation messages
- render status badges and filters
That split is the heart of ABP. Once you start seeing features this way, the framework becomes much easier to navigate.
## When to use ABP and when not to
**ABP is powerful, but <u>it is not automatically the right default</u> for every ASP.NET Core project.**
### When to use ABP
ABP is a strong fit when you are building:
- line-of-business applications
- admin-heavy platforms
- SaaS or multi-tenant systems
- modular monoliths that may grow over time
- systems that need built-in authorization, auditing, localization and consistent conventions
- teams that benefit from standardized architecture
### When NOT to use ABP
ABP may be excessive in the following situations:
- a tiny API with minimal business logic
- a short-lived internal tool where framework structure would dominate the workload
- a team with no interest in layered architecture or DDD-style thinking
- a highly custom architecture where ABP conventions would mostly be bypassed
The main cost of ABP is not performance or syntax 🤜 It is **architectural overhead**.
<u>If the app is too small, that overhead may not pay back.</u>
---
## Common mistakes new ABP developers make
These are the mistakes I see most often in early ABP learning.
### 1. Trying to understand everything before building anything
Do not wait until every project, package and abstraction makes sense. Build one feature first.
### 2. Using generated code without reading it
Generated CRUD is useful, but inspect what it created. Otherwise you will stay dependent on tooling.
### 3. Forcing textbook DDD into every feature
Not every screen needs aggregates, value objects, domain services and custom repositories all at once.
### 4. Putting all business logic in application services
This works for a while, but you eventually lose domain consistency. Protect important invariants closer to the domain model.
### 5. Splitting into too many modules too early
Start with a modular monolith mindset. Extract boundaries when they become meaningful.
### 6. Ignoring built-in ABP features
If you manually rebuild authorization, auditing or tenant-aware behavior without understanding ABP's built-ins, you are fighting the framework.
## The learning path I would actually recommend to a new team
If a team asked me for a practical ABP onboarding sequence, I would keep it simple:
### 📚 Week 1: Basics and orientation
- Review ABP solution structure
- Build the BookStore-style tutorial once
- Identify what each layer is responsible for
### 📚 Week 2: Manual feature implementation
- Build one small module manually
- Avoid too much generation
- Trace one request from UI to application service to repository to database
### 📚 Week 3: Real business rules
- Add relationships
- Add authorization
- Add a workflow or state transition
- Write tests for a few business rules
### 📚 Week 4: Productivity and conventions
- Reintroduce generated tooling where it saves time
- Standardize module patterns
- Decide which DDD patterns the team will use by default and which are optional
That sequence teaches both the architecture and the productivity side of ABP.
---
## Final perspective: learn the intent, not just the template
ABP can feel complicated when approached as a collection of projects and base classes. It gets easier when you see the intent behind the structure:
- protect business rules
- standardize application boundaries
- make common enterprise features reusable
- keep large apps maintainable
If you are new to ABP, do not aim to master every pattern immediately. Aim to answer these four questions clearly for each feature:
- What is the business rule?
- Which layer owns it?
- What data crosses the boundary?
- Which ABP feature already solves part of this problem?
Once those answers become natural, ABP stops feeling heavy and starts feeling productive.
---
## As a Summary
- **The biggest ABP learning barrier is** understanding responsibility boundaries between domain, application services, DTOs, repositories and UI.
- **Start with a small CRUD feature**, but move quickly to a realistic business module with rules, relationships and permissions.
- **Learn both generated and manual CRUD**; one gives productivity, the other gives understanding.
- Real ABP teams often simplify DDD and adopt advanced patterns **only when the complexity justifies them**.
- **The best learning path is ASP.NET Core basics first**, then ABP layers, one manual feature, one real module and built-in features like authorization and auditing.

BIN
docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/abp-layers.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1010 KiB

BIN
docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/abp-learning-path.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.0 MiB

BIN
docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 145 KiB

BIN
docs/en/Community-Articles/2026-08-06-tips-for-developers-new-to-abp-framework/crud-vs-manual.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/12m9D9rhnUDaiDElvNysSXw.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 167 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1479e3iBZ4il0F0tlpUQDYw.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 162 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1EBeje4kIw0tQ4dGrI5i18A.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 284 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1U_z6zDB8GIK2oVVTbKmslg.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 195 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1YCRTIV3eHwgGvEOVlHBDCg.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1Zz-6JQ0gzPq2AvN1_FjbtA.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/1tKQUwPK70eQXvad1eiXoPA.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/Cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.0 MiB

308
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/Post.md

@ -0,0 +1,308 @@
For years, many .NET teams treated core open source libraries as stable background infrastructure: useful, battle-tested, and effectively free forever. That assumption is starting to break.
When widely used projects like IdentityServer, AutoMapper, and MediatR move toward commercial or more restrictive licensing, the discussion is no longer just about one package or one maintainer. It becomes a bigger question about how the .NET ecosystem pays for the software it depends on.
This matters because modern .NET applications are built on layers of third-party dependencies. If one of those layers changes its pricing, support model, or license terms, the impact is not theoretical. It affects procurement, architecture, upgrade strategy, compliance, and long-term maintenance.
## The pattern is no longer isolated
A few years ago, licensing changes in .NET could still be dismissed as exceptions. That is getting harder.
Several important projects now illustrate the same underlying tension: software that became critical infrastructure was often maintained with a funding model better suited to side projects than production-critical systems.
## Duende IdentityServer is the clearest example
The IdentityServer story is probably the most visible case in .NET. What started as a widely adopted open-source identity solution evolved into Duende IdentityServer, which requires paid licenses for production use, while free usage is limited to development, testing, personal projects, or qualifying community scenarios.
More recently, Duende moved again with its v8 generation and introduced a more tiered licensing model, including Lite, Standard, Advanced, and Custom options, plus paid add-ons for additional capabilities. At the same time, support windows are clearly tied to .NET versions, making the product feel even more like managed commercial infrastructure than community software.
> That is not necessarily a bad thing. Identity is security-critical software. It is expensive to maintain, expensive to support, and risky to underfund. But it does mark a major shift in expectations for teams that still think of it primarily as an OSS building block.
## AutoMapper and MediatR point to a broader shift
AutoMapper and MediatR are different kinds of libraries, but their direction matters just as much.
These are not niche components. They are deeply embedded in enterprise codebases, tutorials, templates, and architectural conventions. So when they move toward dual licensing, commercial terms, or more restrictive licensing, the message is clear: **even highly popular and culturally central .NET libraries may no longer fit the old “free and permissive forever” model.**
AutoMapper’s move away from .NET Foundation membership after adopting a non-permissive license is especially notable because it highlights a governance boundary. The ecosystem may celebrate OSS, but institutions such as the .NET Foundation still rely on clear licensing rules. Once a project changes those terms, it often changes its place in the ecosystem too.
## Why maintainers are doing this
The easy reaction is to call commercialization a betrayal. The more honest reaction is to admit that many maintainers have been subsidizing the industry for years.
A project can be free for users and still very expensive for its authors.
Maintaining a popular library often means:
![image-20260816151702299](image-20260816151702299.png)
Once a library becomes critical infrastructure, users expect reliability similar to commercial software. But expectations usually rise faster than funding.
That imbalance creates a predictable outcome: maintainers either burn out, slow down, seek sponsorship, or commercialize.
---
## Open-source popularity does not automatically create sustainability
This is the part many teams still underestimate.
A package can have massive adoption and still be financially fragile. Downloads, GitHub stars, and conference mentions do not pay for maintenance. In fact, popularity often increases the burden without improving sustainability.
From a maintainer’s perspective, commercialization can be a rational correction:
- charge the organizations getting the most value
- fund long-term maintenance
- offer support contracts and SLAs
- justify time spent on roadmap work
- reduce dependence on unpaid labor
### In other words, the move to commercial licensing is often less about greed than about replacing an unrealistic business model.
---
## Why the community reaction is so mixed
Even if the economics make sense, the backlash is real. And frankly, some of it is justified.
The friction usually comes from the gap between legal reality and social expectation.
### Legally, maintainers can often change how future versions are licensed. Socially, users feel that a trusted community dependency has changed the rules after becoming embedded in thousands of systems
---
## What bothers teams most
In practice, teams react to more than cost. They are reacting to uncertainty.
The common concerns are familiar:
- unexpected licensing costs appearing in mature products
- fear of future pricing increases
- procurement delays for something developers previously installed with `dotnet add package`
- license compatibility and compliance reviews
- vendor lock-in around foundational infrastructure
- migration costs if a team decides to leave later
- concern that previously core features move behind paid tiers
This is why the strongest reactions usually happen when the library is infrastructural rather than optional. Authentication, mapping, messaging, and mediator patterns sit close to the core of many architectures. **Replacing them is possible, but rarely cheap.**
---
## Suddenness matters as much as pricing
A reasonable commercial model can still create anger if the transition feels abrupt. Teams generally accept that maintainers need funding. What they do not accept as easily is:
- vague roadmap communication
- surprise license changes
- unclear grandfathering rules
- unclear distinctions between old and new versions
- feature packaging that feels like a trap for existing users
That trust dimension matters. In OSS, the license is not the whole relationship. Predictability is part of the product.
---
## What this signals for the .NET ecosystem
The larger lesson is not simply that some maintainers want to get paid. It is that the .NET ecosystem is maturing into one where critical libraries are increasingly treated like products, not just repositories. That has several consequences.
## 1. Dependency selection is now a governance decision
Choosing a package is no longer only a technical choice.
Press enter or click to view image in full size
![img](1U_z6zDB8GIK2oVVTbKmslg.png)
This does not mean avoiding all commercially backed OSS. It means evaluating dependencies the same way you evaluate databases, cloud services, or authentication providers.
## 2. Foundation membership and community trust will matter more
When a project leaves a permissive governance environment, it sends a signal, even if the software remains technically strong.
Press enter or click to view image in full size
![img](12m9D9rhnUDaiDElvNysSXw.png)
The .NET Foundation’s stance on permissive licensing creates a useful boundary here. It does not solve commercialization, but it helps clarify which projects still fit traditional OSS expectations.
## 3. Forks and alternatives will become more common
When licensing changes upset users, forks appear. That is a normal OSS response.
Press enter or click to view image in full size
![img](1Zz-6JQ0gzPq2AvN1_FjbtA.png)
> A reactive fork may help teams buy time, but it does not automatically become sustainable infrastructure.
In many cases, the fork inherits the same funding problem that triggered the original commercialization.
---
## The practical risk for engineering teams
The biggest mistake teams can make is treating this as community drama instead of delivery risk.
Press enter or click to view image in full size
![img](1EBeje4kIw0tQ4dGrI5i18A.png)
This is especially relevant for organizations with long-lived internal platforms or multi-tenant SaaS products, where one dependency can affect dozens of services.
---
## A realistic example
Imagine a company running an internal platform and several customer-facing .NET applications.
- **The identity layer uses IdentityServer.**
- **Multiple services use MediatR for application-layer orchestration.**
- **Older codebases rely heavily on AutoMapper profiles.**
If all three become cost, licensing, or governance concerns at the same time, the company suddenly has a portfolio-level problem rather than a package-level problem.
Press enter or click to view image in full size
![img](1479e3iBZ4il0F0tlpUQDYw.png)
That is architecture, budgeting, and compliance converging in one decision.
## How teams should respond
> Panic is not useful. Blind trust is not useful either.
A better response is to become more deliberate about dependency management.
---
## Build a dependency review habit
For critical packages, review more than API quality.
Press enter or click to view image in full size
![img](1tKQUwPK70eQXvad1eiXoPA.png)
If a package sits in authentication, authorization, persistence, messaging, or application architecture, the review should be stricter than for a small utility library.
---
## Categorize dependencies by replacement cost
Not every package deserves the same scrutiny.
**A useful model is:**
- low replacement cost: small utilities, isolated helpers
- medium replacement cost: libraries used across one bounded context
- high replacement cost: foundational cross-cutting libraries used everywhere
Commercialization risk matters most in the third category. If replacing the library means touching every service, pipeline, or authentication flow, that risk belongs on the architecture radar early.,
---
## Budget for critical OSS
Many companies are comfortable paying for cloud hosting but still resist paying for the libraries that shape their actual application architecture.
That mindset is becoming outdated.
If a dependency is business-critical, teams should assume one of these will eventually be required:
Press enter or click to view image in full size
![img](1YCRTIV3eHwgGvEOVlHBDCg.png)
> You will pay somehow!
> The only real question is whether you pay proactively or reactively.
---
## When to use commercially backed OSS and when not to ⛔
Commercialization is not automatically a reason to avoid a project.
## ✔ WHEN TO USE IT
**Commercially backed OSS can be a good fit when:**
![image-20260816151255530](image-20260816151255530.png)
Identity infrastructure is the obvious example. A mature, well-supported identity product may be worth paying for if the alternative is building and maintaining security-sensitive code yourself.
---
## ⛔ WHEN NOT TO USE IT
**Be cautious when:**
![be-careful](image-20260816150848261.png)
This is where some teams may rethink packages like object mappers or mediator frameworks. If the dependency is mostly ergonomic and the long-term governance risk is rising, simpler code may be the better tradeoff.
---
## What this means for maintainers, companies, and the community
The ecosystem now needs more honest expectations on all sides.
## * For maintainers
If your library underpins production systems, sustainability needs to be part of the strategy early. Commercialization is easier to accept when it is transparent, gradual, and communicated as part of a long-term model rather than a sudden pivot.
## * For companies
If your business depends on OSS, treating maintainers as an infinite free resource is no longer credible. Critical dependencies should have owners, budgets, and risk reviews.
## * For the .NET community
The community may need to become more selective about what it normalizes as default architecture. If a pattern depends heavily on a few centralized libraries, then a licensing change in one project can ripple widely. Simpler stacks are often more resilient.
---
## A likely next phase for .NET OSS
The next few years will probably bring more segmentation across the .NET ecosystem.
Expect to see more of this:
![image-20260816151051144](image-20260816151051144.png)
That does not mean open source in .NET is weakening. It means the ecosystem is facing the same sustainability pressures seen elsewhere: maintenance is expensive, infrastructure software has real business value, and someone eventually has to fund it.
The healthiest outcome is not pretending commercialization should never happen. It is making sure it happens with predictable governance, fair communication, and realistic expectations from users.
---
## SUMMARY
- Commercialization of key .NET libraries is a sustainability signal, not an isolated incident.
- Teams should evaluate dependencies by license, governance, support policy, and replacement cost.
- Commercial OSS can be the right choice for critical infrastructure, especially where support and security matter.
- The real risk is not paying for software; it is being surprised by cost, lock-in, or migration pressure too late.
- .NET teams should treat dependency strategy as an architectural and business decision, not just a NuGet decision.

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816150848261.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816151051144.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 49 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816151255530.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/en/Community-Articles/2026-08-10-oss-sustainability-in-.net-commercialization-of-key/image-20260816151702299.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

601
docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/Post.md

@ -0,0 +1,601 @@
Most monoliths do not fail because they are monoliths. They fail because they become tangled.
That is exactly why the modular monolith is such a practical architecture for business applications. You keep the operational simplicity of a single deployment, but you organize the codebase around clear business boundaries. With ABP Studio, this approach is not an afterthought. It is built into the way you create and evolve a solution.
In this article, I will walk through how to build a modular monolith with ABP Studio, how ABP modules fit together, where teams usually get the boundaries wrong, and how to structure your solution so it stays maintainable as it grows.
If you are building a line-of-business app and want something more disciplined than a traditional monolith, but less expensive than microservices, this is one of the strongest options in the .NET ecosystem.
## Why a modular monolith fits many real projects
A modular monolith gives you:
- one deployable application
- one main runtime host
- clear module boundaries by business capability
- the option to evolve selected modules later
- less distributed systems overhead than microservices
That trade-off matters in real teams. Most products do not need network boundaries on day one. They need:
- faster delivery
- simpler debugging
- less infrastructure
- a codebase that does not collapse after six months
ABP Framework is designed around modularity. A module in ABP can own its own:
- domain model
- application services
- database integration
- API endpoints
- UI pieces
- tests
That makes ABP a natural fit for modular monolith architecture rather than a framework you have to bend into shape.
## What ABP Studio creates for a modular monolith
When you choose the Modular Monolith option in ABP Studio's New Solution Wizard, ABP creates a solution structure intended for a modern modular application.
At a high level, you typically get:
- `main/` for the main host application
- `modules/` for business modules
- `etc/` for shared infrastructure and configuration assets
This is a useful default because it separates the host from the business capabilities from the start.
A simplified layout looks like this:
```text
src/
main/
MyCompany.MyProduct.Web
MyCompany.MyProduct.HttpApi.Host
modules/
Catalog/
MyCompany.MyProduct.Catalog.Domain
MyCompany.MyProduct.Catalog.Application
MyCompany.MyProduct.Catalog.EntityFrameworkCore
MyCompany.MyProduct.Catalog.HttpApi
MyCompany.MyProduct.Catalog.Web
Ordering/
MyCompany.MyProduct.Ordering.Domain
MyCompany.MyProduct.Ordering.Application
MyCompany.MyProduct.Ordering.EntityFrameworkCore
MyCompany.MyProduct.Ordering.HttpApi
MyCompany.MyProduct.Ordering.Web
etc/
docker/
k8s/
configs/
```
The exact projects depend on your choices, but the important idea is consistent: the host app lives in `main`, and business capabilities live under `modules`.
ABP Studio also lets you choose modules up front or add them later. That is important because most teams do not know their final module map on day one. You can start with a few strong boundaries and evolve from there.
![Generated illustration](inline-1.png)
## Understanding ABP modules in practice
In ABP, modules are first-class building blocks. They are not just folders.
A module typically declares dependencies using attributes such as `DependsOn`, which tells ABP how pieces should be initialized and wired together.
A minimal example looks like this:
```csharp
using Volo.Abp.Modularity;
[DependsOn(
typeof(AbpDddDomainModule)
)]
public class CatalogDomainModule : AbpModule
{
}
```
That may look small, but it is central to the architecture. Dependencies are explicit, and the framework uses those module relationships during startup.
In practical terms, this gives you:
- a consistent module lifecycle
- explicit compile-time references
- less hidden coupling
- clearer ownership boundaries
ABP also distinguishes between framework modules and your application modules.
- Framework modules provide infrastructure features like validation, caching, permission management, and persistence integration.
- Application modules represent your business capabilities like Catalog, Ordering, Billing, or Support.
Structurally, they are similar. The difference is their role in the system.
## A practical module structure that scales
One of the most useful ABP practices is layered modules. Instead of throwing everything into a single project, you separate concerns inside each module.
A common structure is:
- Domain
- Application
- Infrastructure or provider-specific persistence
- HttpApi
- Web or UI
- Tests
For example, a Catalog module may look like this:
### Domain
This is where business rules live:
- entities
- value objects
- domain services
- domain events
- repository interfaces
Keep this layer focused on business behavior, not framework plumbing.
### Application
This layer orchestrates use cases:
- application services
- DTOs
- authorization checks
- transaction boundaries
- coordination across domain objects
This is usually where external callers interact with the module.
### EntityFrameworkCore or MongoDB
This layer handles persistence details:
- DbContext or Mongo collections
- repository implementations
- mappings
- migrations where relevant
ABP supports different providers, and a module can include the provider projects it actually needs.
### HttpApi
This exposes the module over HTTP when needed:
- controllers
- remote service contracts
- serialization-related setup
### Web
If your solution includes server-side or MVC-style UI integration, this is where UI pieces for the module can live.
### Tests
A solid module usually has separate tests for:
- domain logic
- application logic
- persistence integration
For EF Core, in-memory SQLite is a practical option for provider-level tests. For MongoDB, ephemeral test instances are a common approach.
## Step-by-step: creating a modular monolith with ABP Studio
The tooling matters because architecture tends to decay when it is inconvenient. ABP Studio reduces that friction.
A practical setup flow looks like this.
### 1. Create the solution with the Modular Monolith template
In ABP Studio:
- create a new solution
- choose the Modular Monolith template
- select your UI and database preferences
- decide which business modules you want to include initially
This gives you the host app under `main` and a `modules` area for business capabilities.
### 2. Start with business boundaries, not technical layers
Before adding modules, identify your real capabilities. Good early candidates are usually things like:
- Catalog
- Ordering
- Inventory
- Customer Management
- Billing
Bad module boundaries are usually technical buckets like:
- Utilities
- Common Business Logic
- Shared Services
Those become dumping grounds fast.
A simple rule helps: if a module name would make sense to a product owner, it is probably closer to the right boundary.
### 3. Add modules incrementally
You do not need to model the whole enterprise on day one.
Start with two or three meaningful modules. For example:
- Catalog manages products and pricing rules
- Ordering manages carts, orders, and order state
- Identity handles users and permissions via ABP's existing modules
This is enough to validate your architecture without over-designing it.
### 4. Keep each module independently understandable
A developer should be able to open `modules/Catalog` and understand:
- what the module owns
- what it exposes publicly
- what it depends on
- how it is tested
If the module constantly reaches into another module's internals, the boundary is already weak.
### 5. Wire modules through explicit dependencies
ABP's module system encourages declaring dependencies up front.
For example, an application layer may depend on its own domain layer and some framework modules:
```csharp
[DependsOn(
typeof(CatalogDomainModule),
typeof(AbpDddApplicationModule)
)]
public class CatalogApplicationModule : AbpModule
{
}
```
This is much healthier than hidden runtime coupling or random service lookups scattered across the codebase.
![Generated illustration](inline-2.png)
## How modules should communicate
This is where many modular monoliths either stay clean or slowly become a distributed mess inside one process.
In ABP, module communication generally falls into two categories:
- synchronous communication through interfaces or public application services
- asynchronous communication through events
Both are useful. The mistake is using one for everything.
### Option 1: synchronous calls for direct business workflows
Use direct service calls when:
- one module needs an immediate answer
- the workflow is naturally request-response
- the dependency is acceptable and explicit
Example:
- Ordering needs to verify product availability from Catalog before creating an order line.
In that case, a clear application service contract is often the simplest solution.
Benefits:
- easy to trace
- easier to debug
- strong flow control
- fewer hidden side effects
Costs:
- tighter coupling between modules
- dependency direction must be managed carefully
### Option 2: events for decoupled reactions
Use events when:
- a module publishes something that others may react to
- the publisher should not know all consumers
- eventual consistency is acceptable
Example:
- Ordering publishes `OrderPlaced`
- Inventory reserves stock
- Billing starts invoicing
- Notifications sends a confirmation
Benefits:
- lower direct coupling
- easier to add new consumers later
- better long-term separation
Costs:
- debugging is harder
- side effects are less obvious
- too many events can create implicit dependencies
A good default is simple:
- use direct calls for core request-response flows
- use events for reactions and cross-cutting side effects
## An example module interaction design
Imagine a small commerce system with Catalog and Ordering modules.
### Catalog owns
- products
- product pricing
- availability rules
### Ordering owns
- carts
- orders
- order state transitions
A clean interaction might look like this:
1. A user places an order through Ordering.
2. Ordering calls a public Catalog service to validate selected products.
3. Ordering creates the order in its own domain.
4. Ordering publishes an order-created event.
5. Other modules react as needed.
Notice what does not happen:
- Ordering does not directly query Catalog tables.
- Catalog does not modify Ordering aggregates.
- Shared internal entities are not passed around freely.
That discipline matters more than the fact that everything runs in one process.
## Database design in a modular monolith
A modular monolith does not force a single database strategy.
With ABP, you can support:
- a shared database for the whole application
- separate schemas per module
- module-specific databases in some cases
For most teams, the best starting point is a single database with clear ownership boundaries in code.
Why this is usually the right default:
- simpler operations
- easier local development
- straightforward transactions
- less infrastructure overhead
But even with one database, treat data ownership seriously.
That means:
- each module owns its own tables and mappings
- cross-module table access is avoided
- modules interact through services or events, not direct persistence shortcuts
If you later decide to extract a module into a separate service, this discipline will matter far more than whether you started with one database or three.
![Generated illustration](inline-3.png)
## When to use layered modules and when not to overdo them
ABP encourages a layered structure because it scales well, but you should still apply judgment.
### Use layered modules when
- the module has real business complexity
- multiple developers will work on it
- you want clear separation between domain, use cases, and persistence
- the module may grow into a reusable building block
### Do not over-layer when
- the module is tiny and stable
- the behavior is simple CRUD with little business logic
- extra projects would create more ceremony than clarity
There is no prize for turning a 300-line feature into six projects.
A useful practical rule:
- start simple, but not sloppy
- add more structure when the module earns it
ABP makes layered modules easy, but that does not mean every feature deserves the full treatment immediately.
## Testing strategy for a modular monolith
Modular architecture only pays off if modules can be tested with confidence.
A practical testing setup includes:
### Domain tests
Use these for pure business rules:
- invariants
- state transitions
- validation rules
- domain service behavior
These should be fast and framework-light.
### Application tests
Use these for use cases:
- application service behavior
- authorization checks
- DTO mapping expectations
- orchestration across domain objects
### Persistence tests
Use these for provider-specific concerns:
- EF Core mappings
- repository behavior
- query correctness
- migration-related assumptions
In ABP-based solutions, this usually means separate test projects per layer or concern. That keeps failures localized and makes refactoring safer.
## Common mistakes that break modular monoliths
The architecture is solid, but the failure modes are predictable.
### 1. Fake modules with real coupling
This is the most common problem. Teams create module folders, but the code still behaves like one giant application.
Symptoms:
- modules reference each other's internals
- shared entities leak everywhere
- services depend on concrete implementations across modules
- repositories are used across boundaries
If that is happening, you have namespaces, not modules.
### 2. A shared project that becomes a dumping ground
Be very careful with anything named:
- Common
- Shared
- Core
- Utilities
Some shared infrastructure is fine. Shared business logic is often a sign that boundaries are unclear.
Prefer:
- duplicated tiny code over premature shared abstractions
- explicit module contracts over giant common libraries
### 3. Overusing events
Events are powerful, but they can hide the system's real behavior.
If every use case fires multiple events that trigger more events, debugging becomes painful.
Use events deliberately for decoupled reactions, not as a replacement for clear application flows.
### 4. Choosing module boundaries by org chart or UI screens
A screen is not necessarily a module. Neither is a department name.
Choose boundaries based on business capability and ownership of rules and data.
### 5. Ignoring future extraction concerns entirely
You do not need to design for microservices from day one, but you should avoid decisions that make extraction impossible later.
Examples:
- direct table joins across module boundaries
- exposing internal entities everywhere
- no public contracts between modules
ABP's modular style helps here, but only if you actually respect it.
## Modular monolith vs microservices in ABP
ABP supports both styles, which makes the comparison especially relevant.
### Choose a modular monolith when
- your team is small to medium-sized
- you want fast delivery with lower ops cost
- business boundaries exist, but independent deployment is not yet needed
- you want a cleaner architecture than a traditional monolith
### Choose microservices when
- modules must be deployed independently
- scaling characteristics differ sharply by capability
- organizational ownership is strongly separated
- you can absorb the cost of distributed systems complexity
### When NOT to use a modular monolith
Do not use it if you already know that:
- teams need full autonomy over deployment cadence
- strict runtime isolation is required
- independent data ownership must be enforced operationally from the start
For many products, a modular monolith is the better first architecture because it preserves optionality. You can grow into more distribution later instead of paying for it before you need it.
## A practical path for future extraction
One of the best reasons to build a modular monolith with ABP is that the module shape is already compatible with a more distributed future.
That does not mean extraction is free. It never is. But you can make it realistic.
To keep that option open:
- keep public contracts narrow
- avoid direct database coupling across modules
- communicate through application services and events
- keep module-specific logic inside the module
- treat each module as owning its own data and rules
If one day Ordering needs to become its own service, the work becomes an architectural transition instead of a rescue mission.
## Recommended approach for a first real project
If I were starting a new ABP Studio solution today, I would keep it practical.
I would:
- create a modular monolith solution in ABP Studio
- start with 2 to 4 meaningful business modules
- use layered modules only where the complexity justifies it
- default to a single database
- enforce module boundaries in code review
- use direct service calls first, events second
- add tests per module from the beginning
I would avoid:
- designing ten modules before shipping one feature
- building a giant shared library
- using events for every interaction
- leaking persistence details across modules
That balance is usually what keeps the architecture alive after the first few sprints.
## TL;DR
- ABP Studio makes modular monolith architecture practical by separating the host app in `main` and business capabilities in `modules`.
- ABP modules should own their domain, application logic, persistence, APIs, and tests with explicit dependencies.
- Keep module communication intentional: direct calls for request-response flows, events for decoupled reactions.
- Start with a single deployment and usually a single database, but protect boundaries as if extraction may happen later.
- The biggest risk is not the monolith itself; it is weak module boundaries that turn the codebase back into a big ball of mud.

BIN
docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 MiB

BIN
docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/inline-1.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/inline-2.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 957 KiB

BIN
docs/en/Community-Articles/2026-08-13-building-a-modular-monolith-with-abp-studio/inline-3.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 822 KiB

BIN
docs/en/Community-Articles/2026-09-02-abp-studio-vs-aspire-ai-ides-and-crud-generators/ABP-Studio-vs-Alternatives-Cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 MiB

BIN
docs/en/Community-Articles/2026-09-02-abp-studio-vs-aspire-ai-ides-and-crud-generators/ABP-Studio-vs-Alternatives-Inline.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 MiB

163
docs/en/Community-Articles/2026-09-02-abp-studio-vs-aspire-ai-ides-and-crud-generators/Post.md

@ -0,0 +1,163 @@
You already have an IDE. You might already have Aspire. You might already have Cursor. The remaining question is how those tools handle ABP solution structure, modules, run profiles, and generated application code.
Teams compare [ABP Studio](https://abp.io/studio) with three neighbors. This is not an “IDE replacement” debate.
1. .NET Aspire, for describing distributed resources as code and watching them on a dashboard.
2. Generic AI IDEs (Cursor, GitHub Copilot, Claude Code), for repo-wide chat and file edits.
3. CRUD scaffolders, such as `dotnet aspnet-codegenerator` and visual Blazor builders (for example Radzen).
Those tools are good. Keep Visual Studio, Rider, or VS Code. Studio can [open the solution in them](https://abp.io/docs/latest/studio/solution-explorer). This article is about what the ABP workflow brings together in one environment: templates, module graph, Solution Runner (Studio’s tool for starting, stopping, and inspecting applications), the ABP Agent, and [ABP Suite](https://abp.io/suite) (including React).
## TL;DR
Choose ABP Studio when the work is ABP: solution shape, module graph, Solution Runner, AI Agent, and Suite CRUD (including React on modern solutions).
Keep Visual Studio, Rider, or VS Code beside it for refactor, tests, and language services.
Add .NET Aspire when you want resource-as-code and the Aspire dashboard. Studio does not forbid it; microservice templates can wire Aspire in.
Use a generic AI IDE as an extra editor if the team already lives there. Prefer the ABP Agent when the change needs modules, migrations, proxies, or live run telemetry.
Tables in this article follow [official ABP documentation](https://abp.io/docs/latest).
## If the bottleneck is ABP, not the C# file
Studio may be a suitable choice when your team is (or will be) on the ABP Platform and you want one place to:
- Scaffold production templates (including React Modern and Classic MVC / Blazor / Angular).
- Run many services, containers, and UIs from a [Solution Runner](https://abp.io/docs/latest/studio/running-applications) profile (the set of applications and services started together).
- Ask, plan, and implement with AI against modules, packages, migrations, and live telemetry.
- Generate layered CRUD with ABP Suite for MVC, Blazor, Angular, and React.
If you only need a general editor, keep using your IDE. If you only need container orchestration and OpenTelemetry locally, Aspire may already be on the machine. Add Studio when the solution graph and ABP conventions are the bottleneck, not the C# file.
## What actually sits next to Studio
| Capability | ABP Studio + Agent | .NET Aspire | General AI IDEs (Cursor, Copilot, Claude Code, …) | Visual Studio / Rider / VS Code |
|---|---|---|---|---|
| Role | ABP solution lifecycle + AI coding in context | Cloud-native orchestration, service discovery, dashboard | Repo-wide AI edit / chat / agents | General-purpose IDE |
| ABP / DDD structure in context | Solution, modules, packages, run profiles in the [agent system context](https://abp.io/docs/latest/studio/ai-agent) | Unaware of ABP modules | Files and text; no ABP module graph | Solution explorer of projects, not ABP modules |
| ABP-shaped artifacts | Suite generates entity, app service, DTOs, repository, and UI; Agent follows those module conventions | No | Generic C# unless you prompt every ABP convention | Language services only |
| Production ABP templates | Layered, modular, microservice; Modern React or Classic UIs | Minimal host templates for Aspire | None | `dotnet new` / ABP CLI if you add it |
| Run + monitor | [Solution Runner](https://abp.io/docs/latest/studio/running-applications): start/stop apps and containers, HTTP requests, exceptions, logs, events, browse UI | Aspire dashboard: resources, logs, traces, metrics | Shell / terminal processes | Multi-project debug |
| AI that can build, migrate, generate proxies | Agent mode: files, shell, [Studio tools](https://abp.io/docs/latest/studio/ai-agent-built-in-capabilities) (`dotnet_build`, `start_applications`, `generate_csharp_proxies`, `get_exceptions`, …), MCP | Not an ABP coding agent | Shell-wrapped `dotnet` if you teach it | Copilot in the editor (generic) |
| Kubernetes | Studio Kubernetes integration for ABP solutions | Publish / deploy story for Aspire apps | No | No (unless you add tools) |
| Code edit / refactor | Agent writes code; Open with your IDE for deep refactor | Not an editor | Strong | Strongest language tooling |
| Use together? | Yes, open IDE from Studio; optional Aspire integration | Yes with ABP microservice template | Yes as an extra editor | Yes; Studio launches them |
How to read the table: these tools stack. Studio does not replace Rider's refactorings or Aspire's resource model. Its differentiated value is the ABP-aware workflow across solution structure, modules, run profiles, and agent tools.
Kubernetes. Studio’s Kubernetes integration is for developing against a cluster (browse and health using service names from the run profile). It is not Helm, GitOps, or your production deploy pipeline.
## The ABP Agent vs “just ask Cursor”
![Generic AI IDE and ABP Agent: repository context and ABP Studio context](ABP-Studio-vs-Alternatives-Inline.png)
Cursor and Copilot are excellent at finishing a LINQ query or explaining a regex. That is not the argument.
Ask a generic AI IDE: "Add a Product entity, make it multi-tenant, add the EF Core migration, generate the React UI." A generic AI IDE can work effectively when it has sufficient repository context and explicit project conventions. ABP Studio's differentiated value is that solution, module, run-profile, and telemetry context are available through first-class Studio capabilities. For cross-layer ABP changes, this can reduce the amount of context and manual coordination the developer must provide.
[ABP Studio AI Agent](https://abp.io/docs/latest/studio/ai-agent) is not limited to the currently open text buffer. The session can use the solution, modules, packages, runnable apps, run profile, AI scope, and enabled tools. [ABP Suite](https://abp.io/suite) remains the CRUD generator, while the Agent is designed to work with the module graph, add a migration, start the profile, and inspect live exceptions.
Modes:
- Ask, read-only answers. Can search ABP documentation.
- Plan, read-only implementation plans.
- Agent, read/write files, shell, add migrations, run Studio tools, MCP, update plan steps.
The ABP Agent fits changes where module, solution, and runtime context should remain available throughout the work.
That is the difference versus a generic AI IDE:
| What you ask | ABP Agent | Generic AI IDE |
|---|---|---|
| “Add an app service following ABP layering” | Receives solution, module, and ABP documentation context through Studio | Works from the repository context and instructions provided to it |
| “Why did this HTTP call fail?” | `get_requests` / `get_exceptions` / `get_logs` on the running profile | You paste a log or attach a debugger |
| “Generate C# / Angular proxies” | First-class Studio tools | A shell command if the model guesses it |
| “Start the apps, then continue” | `start_applications` / `start_containers` | Terminal + wait |
| Scope | AI scopes limit which modules the agent may touch; `.abpignore` blocks secrets | Works from the repository context and instructions provided to it |
You still review the diff. Agent mode is execution with a permission boundary, not unsupervised production deploys.
The [privacy boundary](https://abp.io/docs/latest/studio/ai-agent) is the session you give it: files, prompts, Studio tool output, attachments, and allowed URLs. Privacy depends on the selected model, configured provider, accessible scope, and enabled tools. [`.abpignore`](https://abp.io/docs/latest/studio/ai-agent-configuration) prevents excluded files from entering the agent context.
## Why Aspire does not replace Studio (they stack)
[Solution Runner](https://abp.io/docs/latest/studio/running-applications) is how you run an ABP modular or microservice tree: profiles per team, folders for apps/gateways/services, C# hosts, CLI tasks (for example Angular), Docker containers, start/stop/build, browse, health, and live HTTP / exception / log / event views.
.NET Aspire is how many .NET teams describe distributed resources as code and watch them on a dashboard (OpenTelemetry, containers, connection strings).
Their responsibilities overlap around local orchestration, but their primary scopes are different. Aspire focuses on distributed resource orchestration, while ABP Studio adds ABP solution templates, module workflows, Suite, and the ABP Agent.
You do not have to pick one. ABP microservice templates can enable Aspire so AppHost starts infrastructure and services; you can still use Studio’s runner and Agent. See [Aspire integration](https://abp.io/docs/latest/solution-templates/microservice/aspire-integration).
Pairing ABP Studio with Aspire works well when ABP solution workflows and distributed resource orchestration are both needed.
## Suite: a CRUD slice, not a pretty grid
[ABP Suite](https://abp.io/docs/latest/suite) generates a CRUD slice of an ABP application from an entity: domain type, repository, application service, migration, UI, tests, navigation properties, multi-tenant flag, localization keys.
| | ABP Suite | `dotnet aspnet-codegenerator` / EF scaffolding | Visual Blazor app builders (for example Radzen) |
|---|---|---|---|
| Output | Entity through application layer + UI + optional tests | Controllers, Razor Pages, Blazor CRUD, or Minimal API endpoints against a DbContext | Blazor UI + data wiring from a database or REST source |
| UI stacks | MVC, Blazor (Blazorise or MudBlazor, detected), Angular, and React (modern solutions) | MVC views, Razor Pages, and Blazor components. No Angular. No React. | Blazor only (Server, WebAssembly, Auto) |
| ABP permissions, tenancy, audit base classes | Options on the entity ([CRUD generation](https://abp.io/docs/latest/suite/generating-crud-page)) | Does not use ABP permission and tenancy conventions | Does not use ABP permission and tenancy conventions |
| Custom code on regenerate | Customizable code [hook points](https://abp.io/docs/latest/suite/customizing-the-generated-code) for MVC, Blazor, and Angular; React pages require extra care when regenerated | Often requires manually preserving custom changes | Varies by product |
| React UI | Yes, template-based CRUD for modern React apps, including search, paging, validation, permissions, localization, and navigation properties. Registers routes and menu | No React generator in the official scaffolding set (`blazor`, `razorpage`, `view`, `controller`, `identity`, `minimalapi`) | Blazor-focused rather than React-based |
Suite supports the official web UI stacks, including React. [ABP Agent](https://abp.io/docs/latest/studio/ai-agent) is an extra path when you want AI to evolve those pages, not a substitute for Suite React output.
Suite is a fit when generated CRUD should follow the application's ABP layers, conventions, and selected UI stack.
## When Studio is the right tool in the stack
Choose ABP Studio when the work is ABP: new solution shape, module graph, run profiles, Kubernetes-connected browse, Agent that can migrate and generate proxies, Suite for CRUD.
Keep your IDE open beside it for refactor, tests, and language services. Studio expects that.
Add Aspire when you want resource-as-code and the Aspire dashboard. Studio does not forbid it.
Use a generic AI IDE as an extra editor if your team already lives there. Prefer Agent for ABP-structured changes so the model is not guessing module boundaries from filenames.
Studio works best when ABP-specific solution workflows complement your existing IDE.
## FAQ
### We already run .NET Aspire (AppHost + dashboard). What does Studio still do that Aspire does not?
Aspire models resources (projects, containers, connection strings, OpenTelemetry) as code. Studio models an ABP solution: modules, package installation, production templates, Suite, Kubernetes browse for ABP services, and an agent that can migrate and generate proxies. Their responsibilities overlap around local orchestration, but their primary scopes are different. You can keep AppHost; microservice templates can integrate Aspire. You do not need to replace Aspire with Studio.
### If the team already uses Cursor or Copilot on the same repo, when is ABP Agent the better tool for a task?
When the task needs ABP structure or a live run, not only a file edit: module/package scope, `generate_csharp_proxies` / `generate_angular_proxies`, `start_applications`, or `get_exceptions` / `get_requests` / `get_logs` against the [Solution Runner](https://abp.io/docs/latest/studio/running-applications) profile. Generic IDEs can work in the same repository when given the relevant context and conventions. Agent provides first-class access to module, run-profile, and Studio tool context for changes that coordinate ABP modules and running services.
### After Suite generates React CRUD, how should we customize the page?
For MVC, Blazor, and Angular, use Suite’s [customizable code](https://abp.io/docs/latest/suite/customizing-the-generated-code) hook points. React pages require extra care when regenerated, so keep additional React UI in files Suite does not generate or evolve it with [ABP Agent](https://abp.io/docs/latest/studio/ai-agent). Suite React generation itself is template-based, not AI.
### Can Agent start the microservice profile, then use real HTTP/exception data in the same session?
Yes, in Agent mode with a run profile: tools include `start_applications` / `start_containers` and then `get_requests`, `get_exceptions`, `get_logs`, `get_events` ([built-in capabilities](https://abp.io/docs/latest/studio/ai-agent-built-in-capabilities)). Ask/Plan cannot mutate or start apps. If nothing is running, those telemetry tools have nothing to read. That is why “AI that sees production-like local traffic” is a Studio and Runner loop, not a chat sidebar.
### Does Studio Kubernetes integration replace Helm, GitOps, or our cluster deploy pipeline?
No. It is for developing against a cluster (browse/health using Kubernetes service names from the run profile, manage connected services). Aspire’s publish story and your CI remain how you ship. Do not treat the Studio K8s panel as the production deployment product.
### Can one developer live in Rider and another in VS Code while sharing the same Studio solution?
Yes. Studio holds solution/run-profile metadata; [Open with](https://abp.io/docs/latest/studio/solution-explorer) launches whatever IDE is installed. Run profiles and Agent sessions are not tied to a single editor vendor. The constraint is ABP Studio itself on the machine, not a mandate to abandon Rider or VS.
## Next step
[Download ABP Studio](https://abp.io/studio) · [AI Agent docs](https://abp.io/docs/latest/studio/ai-agent) · [Generate a CRUD page](https://abp.io/docs/latest/suite/generating-crud-page) · [ABP Framework](https://abp.io/framework)
### Sources
- [ABP Studio overview](https://abp.io/docs/latest/studio)
- [AI Agent](https://abp.io/docs/latest/studio/ai-agent)
- [AI Agent built-in capabilities](https://abp.io/docs/latest/studio/ai-agent-built-in-capabilities)
- [Solution Runner](https://abp.io/docs/latest/studio/running-applications)
- [Solution Explorer / Open with IDE](https://abp.io/docs/latest/studio/solution-explorer)
- [ABP Suite](https://abp.io/docs/latest/suite)
- [Generating a CRUD page](https://abp.io/docs/latest/suite/generating-crud-page)
- [Customizing the generated code](https://abp.io/docs/latest/suite/customizing-the-generated-code)
- [ASP.NET Core `aspnet-codegenerator`](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/tools/dotnet-aspnet-codegenerator)
- [.NET Aspire overview](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview)
- [Radzen Blazor Studio](https://www.radzen.com/blazor-studio/)
- [Microservice Aspire integration](https://abp.io/docs/latest/solution-templates/microservice/aspire-integration)
Product names in this article belong to their owners. Mention is for identification in a technical comparison, not affiliation or endorsement.

BIN
docs/en/Community-Articles/2026-09-02-abp-vs-clean-architecture-templates-and-starter-kits/ABP-vs-Alternatives-Cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.6 MiB

BIN
docs/en/Community-Articles/2026-09-02-abp-vs-clean-architecture-templates-and-starter-kits/ABP-vs-Alternatives-Inline.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 MiB

223
docs/en/Community-Articles/2026-09-02-abp-vs-clean-architecture-templates-and-starter-kits/Post.md

@ -0,0 +1,223 @@
Every serious .NET team hits the same whiteboard sooner or later. Do we build the multi-tenant SaaS from scratch? Grab a starter kit? Adopt a platform?
Search “ABP vs …” and you will land on pages written by kits and tenancy libraries. Fair. Those pages exist because the question is real. They are not comparing two products of the same kind.
You are choosing among four shapes:
1. Build it yourself on ASP.NET Core, often with a tenancy library such as Finbuckle.MultiTenant.
2. A Clean Architecture template (Jason Taylor, Ardalis) that gives you folders, layers, and a sample feature.
3. A starter kit that copies a snapshot of production modules into your repo (fullstackhero, Brick, and similar kits).
4. A maintained application platform. Architecture, infrastructure, modules, and tools that keep moving.
ABP competes across several decision categories rather than against one uniform product set. Some teams compare it with Clean Architecture and DDD references or starter kits because they prefer to own and assemble the application foundation themselves. Others evaluate .NET application and service frameworks such as ServiceStack, model-driven RAD platforms such as DevExpress XAF, or cross-stack SaaS platforms and starter kits. Existing ASP.NET Boilerplate applications are usually a migration and adoption consideration rather than a same-generation alternative. The table below focuses on the architecture and application-foundation decision; these other categories can still enter the same broader technology discussion.
[ABP](https://abp.io) takes the application-platform approach. The rest of this article is about the things teams evaluate later: multi-tenancy, identity, permissions, modularity, UI (including React), and a path from modular monolith (one deployable application organized into independent modules) to microservices.
## TL;DR
Choose ABP when you are shipping a long-lived, multi-tenant, modular .NET product and want a maintained platform: tenancy, identity, modules, official UIs (including React), and Studio / Suite on the same stack.
Choose a Clean Architecture template (Jason Taylor, Ardalis) when the goal is to own every architectural decision from a well-named skeleton.
Choose a starter kit (fullstackhero, Brick, and similar) when you prefer a copy of modules in your repo on day one and you are willing to maintain that snapshot.
Choose Finbuckle (or custom tenant middleware) when tenant resolution is the only additional capability you need on an app you already own. ABP also connects tenancy with application concerns such as identity, permissions, and audit.
Tables in this article follow [official ABP documentation](https://abp.io/docs/latest).
## This is for the long haul
ABP is the recommended choice when you are building a long-lived, multi-tenant, modular .NET product. B2B SaaS. Line of business. A platform several teams will still be extending in a few years.
You want:
- Cross-cutting concerns (auth, tenancy, audit, jobs, localization) already solved and documented.
- Official UI options that match your team: React, Angular, Blazor, MVC, MAUI, or React Native.
- A way to add pre-built modules and, later, split a module into a service without rewriting the application code.
- Tooling (Studio, Suite, CLI) and, if you need it, commercial modules and support, without leaving the same platform.
Yes, ABP is opinionated. The initial learning cost is real: teams need to understand modules, application services, and unit of work conventions before those conventions become productive. Then, when a module needs to become a microservice, the contracts are already there. The conventions become team-wide standards so the next project does not invent a second way to do the same thing.
## Four shapes. One table.
![DIY ASP.NET Core, Clean Architecture, starter kit, and ABP Platform as four different shapes](ABP-vs-Alternatives-Inline.png)
| Capability | ABP Platform | DIY ASP.NET Core | Clean Architecture templates (Jason Taylor, Ardalis) | Starter kits (fullstackhero, Brick, and similar) |
|---|---|---|---|---|
| What you get | Maintained framework + modules + templates + tooling | Empty host and libraries you assemble | Layered/CQRS skeleton + a sample feature | A copy of modules in your repo on day one |
| Multi-tenancy | Native: [single database, database-per-tenant, or hybrid](https://abp.io/docs/latest/framework/architecture/multi-tenancy); identity and authentication/token infrastructure wired for tenants | You design isolation, filters, and cache keys, or add a library such as Finbuckle.MultiTenant | Not included | Often via a tenancy library you still own end-to-end |
| Identity, permissions, audit | Application modules + automatic tenant-data filtering, [audit logging](https://abp.io/docs/latest/framework/infrastructure/audit-logging), permission system | You compose Identity, policies, and audit yourself | Identity sample at most | Bundled in the kit; you maintain the fork |
| Modularity | First-class [module system](https://abp.io/docs/latest/framework/architecture/modularity/basics); install/uninstall packages | You invent module boundaries | Folders and layers, not a product module catalog | Modular folders; upgrades are merge/cherry-pick |
| UI | [React (Modern)](https://abp.io/docs/latest/framework/ui/react), MVC, Blazor, Angular, [React Native](https://abp.io/docs/latest/framework/ui/react-native), [MAUI](https://abp.io/docs/latest/framework/ui/maui) | You pick and integrate | Template-specific (often Angular/React/API) | Kit-specific (often one SPA) |
| Monolith → microservices | Same application contracts; HTTP/C# proxies replace in-process calls | You design the split | You design the split | Extract-a-module if the kit allows it |
| Tooling | [ABP Studio](https://abp.io/studio) (including AI Agent), [ABP Suite](https://abp.io/suite), CLI | `dotnet` CLI and your IDE | Template CLI + IDE | Kit CLI / Aspire host, varies |
| How it evolves | NuGet upgrades for the framework and modules, plus documented migrations | You upgrade every library | You copy the next template over your tree | You merge upstream into source you already customized |
| Support | Open-source core plus commercial extras and vendor support | Your team | Community | Community |
ABP may be a suitable fit when the application needs architecture, infrastructure modules, and development tooling to remain integrated and maintainable as the product grows.
How to read the table: templates teach structure. Starter kits give you a snapshot you own. ABP combines application architecture, infrastructure modules, and development tooling in one platform. Names in the headers are examples of the category, not a review of every repository.
Identity, permissions, and audit. ABP ships these as application modules: permission UI, automatic filtering of tenant data, and audit logging. On plain ASP.NET Core you compose Identity, policies, and audit yourself. A Clean Architecture template usually stops at an Identity sample. A starter kit may bundle them; you then maintain that copy.
How the stack evolves. When a customized starter kit is updated, identity and tenancy code may already contain local changes. Reconciling those changes across the files you now own can add significant maintenance work. That is a different upgrade model from updating framework packages.
ABP uses framework and module packages, together with documented migrations. A Clean Architecture template’s next version is something you copy forward. A kit’s next version is reconciled with the snapshot you already changed.
## Let’s be honest: what are you actually downloading?
### What you build yourself
ASP.NET Core is phenomenal. It is a foundation, not a complete application platform. Building from scratch gives teams maximum control, but also leaves tenant resolution, permission checks, audit logs, job plumbing, and module boundaries to the team.
That work is legitimate if the architecture is unique. For a standard business product, it is infrastructure before the first domain feature.
ABP sits on ASP.NET Core. You keep the Microsoft stack. ABP provides established conventions and modules for teams that prefer those decisions to be part of the platform. See [Why ABP Platform](https://abp.io/docs/latest/others/why-abp-platform).
ABP suits teams that want application infrastructure to remain integrated with the product as it grows.
### Clean Architecture templates
This category includes the templates most often compared with ABP: Jason Taylor’s Clean Architecture template and Ardalis’s Clean Architecture template. They provide a good classroom and a clean slate. Their focus is architectural structure and ownership rather than a built-in application module catalog or ABP-specific tooling.
Choose a Clean Architecture template when architectural ownership and a focused starting point matter most.
ABP is a fit when architectural conventions and application modules need to evolve together.
### Starter kits
A starter kit copies identity, tenancy, auditing, and a few domain modules into your repository. You own every line. That is a real preference for some teams.
Starter kits are another common option in this decision. fullstackhero is a copy-and-own MIT kit (identity, tenancy, React admin, modules in your repo). Other starter kits, such as Brick, can also provide a prebuilt starting point; the exact features, ownership model, and update process depend on the kit. They can provide a fast starting point, but long-term maintenance depends on how each kit handles updates to customized code.
With ABP, framework and module updates are distributed through packages and documented migrations. With a kit, teams have direct ownership of the source, while updates may require reconciling local changes with upstream code. These are different maintenance models.
Choose a starter kit when an existing set of application features and direct source ownership can accelerate your team.
Choose ABP when you want those application concerns, modules, and tooling to evolve as part of a maintained platform. ABP’s open-source core is yours to use; your business code lives in your repo. There is no separate proprietary runtime for that core. Commercial extras (themes, Pro modules, Suite, support) are optional layers on the same platform, not a rewrite.
Package-based framework and module updates may suit teams that prefer them to reconciling changes in an owned source snapshot.
## If you last looked a year ago: React is official
This is easy to miss if you last looked at ABP a year ago.
Official UI options ([ABP UI](https://abp.io/docs/latest/framework/ui)):
- React, in the [Modern template system](https://abp.io/docs/latest/solution-templates/modern-vs-classic) (ABP Studio or `abp new --modern`).
- MVC / Razor Pages, Blazor (WebAssembly, Server, WebApp), and Angular, on Classic templates.
- React Native and MAUI for mobile / hybrid.
[Modern vs Classic](https://abp.io/docs/latest/solution-templates/modern-vs-classic): Classic is not a deprecated track. It is the actively supported family with the broadest UI matrix (MVC, Angular, Blazor, MAUI) and the template-first Studio flow. Modern is the newer architecture-first Studio flow, React (or no UI), and the Admin Console / Low-Code path (metadata-driven screens configured through a designer). Choose Classic when the team’s UI is MVC, Angular, or Blazor. Choose Modern when the web UI is React.
One backend, the UI your team already knows.
## Multi-tenancy without a side project
ABP treats tenancy as infrastructure, not a feature you bolt on:
- Current tenant is resolved per request.
- Entities implementing `IMultiTenant` (ABP’s contract for separating tenant-owned data) are automatically filtered; new records get a `TenantId` identifying the tenant.
- You can use one database for all tenants, one database per tenant, or a hybrid.
That isolation also applies to cache and related concerns so business code stays mostly tenancy-agnostic. Details: [Multi-Tenancy](https://abp.io/docs/latest/framework/architecture/multi-tenancy).
A tenancy library on raw ASP.NET Core, including Finbuckle.MultiTenant, can resolve the tenant. It does not automatically give you permission UI, audit, jobs, Identity/OpenIddict authentication and token wiring for tenants, and module installs on the same model. That is the platform difference. Pages titled “Finbuckle vs ABP vs custom” are answering a library question. This article is answering the application-platform question.
ABP is worth considering when tenancy needs to stay connected to identity, permissions, data filtering, and the rest of the application model.
## Modularity that can become microservices
ABP modules are real packages (domain, application, HTTP API, UI) with documented dependency rules. You can start with a [modular monolith](https://abp.io/architecture/modular-monolith) and later replace in-process calls with HTTP using the same application service contracts and [client proxies](https://abp.io/docs/latest/framework/api-development/dynamic-csharp-clients) (typed clients that call application services over HTTP).
That path is the point. You do not throw away the monolith to “do microservices”; you change the hosting of a module that already had a boundary.
This approach fits teams that want modular boundaries to support both a modular monolith and a later service split.
## ABP Low-Code: admin screens inside the same app
[ABP Low-Code](https://abp.io/docs/latest/low-code) is a module in your ABP application (Team license or higher). You model entities, pages, forms, permissions, and scripts in the Admin Console. The runtime uses that metadata in the same app, with the same identity, audit, and EF Core model. There is no separate low-code database.
Designer, [Studio AI Agent](https://abp.io/docs/latest/studio/ai-agent), and hand-written C# / Script API land on one model.
The documented runtime UI is React. You can still keep MVC, Razor Pages, Angular, or Blazor as the main UI and host the React Low-Code runtime beside it ([non-React integration](https://abp.io/docs/latest/low-code/non-react-ui-integration)).
Docs still label the system Preview (APIs and designer may change before GA). That is a maturity label, not a missing product.
| | ABP Low-Code | External low-code platform | Hand-written CRUD every time |
|---|---|---|---|
| Where it runs | Inside your ABP app | Separate product / runtime | Your repo |
| Data and identity | Same database and ABP authorization | Often a parallel model | Whatever you build |
| Extend with code | C#, Script API, Agent | Platform limits | Always code |
| Screens | Grid, form, calendar, kanban, gallery, dashboard, import/export | Vendor widgets | Custom pages |
| How you enable it | Studio modern wizard (layered, single-layer, modular monolith + EF Core) or [add to an existing EF Core solution](https://abp.io/docs/latest/low-code/add-to-existing-solution) | Vendor onboarding | Always code |
Studio’s *new-solution wizard step* is omitted for microservice architecture and when MongoDB is selected, because runtime-managed tables use EF Core. Layered and modular-monolith EF Core solutions are the documented enablement path today.
Use Low-Code for the admin CRUD and metadata-driven screens. Keep distinctive product UX in normal ABP UI, including Suite-generated React CRUD on modern solutions.
## When this is the right call
Pick ABP when:
- The product will have tenants, roles, audit, and more than one team.
- You want React *or* Blazor *or* Angular *or* MVC on a shared backend.
- You expect to grow from modular monolith to services without a rewrite.
- You want Studio, Suite, and (optionally) Low-Code on the same stack.
A Clean Architecture template is a solid choice when architectural ownership and a focused starting point matter most.
A starter kit is a solid choice when an existing set of application features and direct source ownership can accelerate your team. ABP is a better fit when those application concerns, modules, and tooling should evolve as part of a maintained platform.
ASP.NET Boilerplate is the predecessor, not a same-generation starter kit. If that is the comparison, it is a migration to the current ABP platform, not a fork-and-own kit decision.
DevExpress XAF and similar commercial frameworks follow a model-driven RAD approach built around a vendor UI ecosystem. That approach can reduce application boilerplate and accelerate internal business applications, while also placing the application’s model and much of its UI experience within DevExpress conventions and controls. ABP is an application platform on ASP.NET Core, with an open-source core, modular architecture, and multiple UI options. It gives teams more direct control over the application layers and frontend choices, including MVC, Blazor, Angular, and React, while supporting a modular-monolith-to-microservices path. XAF may be the better fit when the priority is delivering a model-driven business application quickly within the DevExpress ecosystem. ABP may be the better fit when the product needs ASP.NET Core, a more customized frontend experience, multiple client options, or a modular architecture that can evolve toward services.
## FAQ
### Is ABP free or commercial?
ABP Framework has an open-source core. Some themes, modules, generators, Studio capabilities, support, and other commercial offerings require an appropriate commercial license. Exact availability depends on the product and license level.
### If we stop paying for commercial extras, or we leave ABP later, is the app a black box?
No. The application is still ASP.NET Core, your C#, and EF Core (or MongoDB). The [open-source framework](https://abp.io/docs/latest/others/why-abp-platform) stays in the solution as packages you already reference. Leaving ABP means replacing those packages the way you would replace any framework, not extracting code from a closed runtime. Suite output is source in your repo. Commercial modules, themes, and Suite itself are optional layers; dropping them does not delete your domain.
### If we already have a Clean Architecture or starter-kit repo (Jason Taylor, Ardalis, fullstackhero, Brick), can we “just add ABP” like a NuGet?
No. ABP’s module pipeline, interceptors, automatic tenant-data filters (which limit queries to the current tenant), and startup conventions assume it is the host. Teams adopt ABP on a new solution (or plan a migration), they do not drop `Volo.Abp.*` onto an existing CA template and keep the old composition root unchanged. That is the real cost versus a tenancy library you add to code you already own. See [Why ABP Platform](https://abp.io/docs/latest/others/why-abp-platform).
### We already use Finbuckle (or custom tenant middleware). What does ABP tenancy still do that that library does not?
A tenancy library resolves *who the tenant is*. ABP also isolates queries and inserts (`IMultiTenant` data filters), wires Identity and OpenIddict for tenants, and applies the same tenant context to cache and related infrastructure. That covers [single database, database-per-tenant, or hybrid](https://abp.io/docs/latest/framework/architecture/multi-tenancy). Permissions, audit, and jobs then run inside that model instead of each being a separate integration project.
### If we start Modern/React, can the same backend later serve a second UI (public MVC, partner Blazor, mobile)?
Yes. Application services and HTTP APIs are UI-agnostic. [Official UIs](https://abp.io/docs/latest/framework/ui) (React, Angular, Blazor, MVC, React Native, MAUI) are hosts on that backend. You choose Modern vs Classic at solution creation for the primary web app; extra clients consume the same APIs. You do not rewrite domain or application layers to add a second frontend.
### When we split a module into a microservice, do we rewrite application services as controllers?
Not as the default path. Module contracts stay; in-process calls become HTTP (or messaging) via [client proxies](https://abp.io/docs/latest/framework/api-development/dynamic-csharp-clients) against the same application-service interfaces. You change hosting, not the feature’s application API. That is the comparison point versus a starter kit whose “modules” are folders with no proxy story.
### For the same admin entity, should we use Suite-generated React CRUD or Low-Code pages?
[Suite](https://abp.io/docs/latest/suite) writes source into your layers (entity, app service, UI, tests) that you commit and customize, including React on modern solutions. [Low-Code](https://abp.io/docs/latest/low-code) keeps the entity in metadata (designer + runtime APIs/pages) without generating those classes for the standard flow. Use Suite when the screen will grow into product code; use Low-Code when the screen should stay designer-driven. They are not substitutes for each other.
### Can we keep MediatR / vertical-slice handlers for new features inside an ABP solution?
You can reference extra libraries, but ABP’s default application surface is [application services](https://abp.io/docs/latest/framework/architecture/domain-driven-design/application-services) with unit of work, validation, and authorization conventions. Comparison with CA templates is not “MediatR vs nothing”; it is whether the team standardizes on ABP’s application layer or on a handler-per-feature folder as the public API. Mixing both without a rule usually duplicates the same use case in two styles.
## Next step
Create a solution in [ABP Studio](https://abp.io/studio) and pick Modern (React) or Classic (MVC / Blazor / Angular). Then add only the modules you need.
[Create a free ABP solution](https://abp.io/studio) · [Read the framework overview](https://abp.io/framework) · [Why ABP Platform](https://abp.io/docs/latest/others/why-abp-platform)
### Sources
- [ABP UI options](https://abp.io/docs/latest/framework/ui)
- [Modern vs Classic templates](https://abp.io/docs/latest/solution-templates/modern-vs-classic)
- [React UI](https://abp.io/docs/latest/framework/ui/react)
- [Multi-tenancy](https://abp.io/docs/latest/framework/architecture/multi-tenancy)
- [Why ABP Platform](https://abp.io/docs/latest/others/why-abp-platform)
- [Low-Code System](https://abp.io/docs/latest/low-code)
- [Jason Taylor Clean Architecture template](https://github.com/jasontaylordev/CleanArchitecture)
- [Ardalis Clean Architecture template](https://github.com/ardalis/CleanArchitecture)
- [fullstackhero starter kit](https://github.com/fullstackhero/dotnet-starter-kit)
- [Finbuckle.MultiTenant documentation](https://www.finbuckle.com/MultiTenant/Docs)
- [ServiceStack documentation](https://docs.servicestack.net/why-servicestack)
- [DevExpress XAF overview](https://www.devexpress.com/products/net/application_framework/)
Product names in this article belong to their owners. Mention is for identification in a technical comparison, not affiliation or endorsement.

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/Cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 502 KiB

177
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/Post.md

@ -0,0 +1,177 @@
# How to Present Your .NET Project To Your Mother?
**I'm writing this article while camping in the middle of the forest 🌲⛺.** I came here to get away from computers for a while... but apparently, I'm still thinking about software and how we explain it to people. You can see me in the cover image 😄
![image-20260906225734694](image-20260906225734694.png)
Hey there! I'm Alper, giving international conference talks and mostly I don't know the audience demography (knowledge level/position/tech stack etc...). And I need to be very careful how I present my talk. Recently I've been studying on this topic. My audience is mostly developers or IT guys. And when I explain a technical topic to those people, I'm very comfortable 🤠🤠 But, sometimes we need to explain what we do (our project) to our friends, mother or child. In other words; anyone who is not technical. Then things are getting a little bit different and harder 🤯
To have a strong technical knowledge does not automatically make someone a good communicator.
For scientists, engineers, developers and technical leaders, the real challenge is not knowing the subject 👉 **deciding what the audience needs to know and how to make it meaningful for them.**
Empathy is very important in all our life steps. I wrote an article about [empathy in workspace](https://abp.io/community/articles/empathy-in-the-workplace-for-software-companies-wsjjw9we), please read it when you have time because it's also important for this topic. Imagine you are explaining your .NET project to an investor or customer, concepts which you use in your project might be simple for you, but feel that empathy (please) for a moment, **does that guy understand what you mean**? Before starting your presentation collect information about him so that you can adjust your sentences according to him.
> AND TELL HIM ONLY WHAT WORKS FOR HIM.
No need to tell how the algorithm behind this project works! Tell him why it's good for him. From now on, when I tell "him/his" I mean the customer / investor / friend / father / son / non-IT guy.
---
## Don't Focus Too Much on the Details
We are all good software engineers and we want to show the art behind that work 👏 That's absolutely natural feeling 👍
We all want to show people the details how our project work because we are proud of it and that's a bad practise!!
Too much detail will definitely hide your main message!!! You are consuming his energy, focus and time with all those details.
So what happens, your main goal is not being transferred to him 🤔..💭...🥺
![image-20260906212829582](image-20260906212829582.png)
Ok we know the problem, now how will you fix this? SIIMMPLEE: Before mentioning a topic, ask yourself:
> Does he need this info to understand my idea or make his decision?
If not, please save it for yourself and don't mention about that.
Maybe later, if he's very much interested in you can explain him (IF ONLY he asks 😄)
---
## Don't Make It Too Simple Also *-- are you kidding me!*
Well! Don't be angry 😡 at me. In the previous section I said *don't go in details* and now I'm telling **do not explain too simple** 🙃
While we are trying to not make it too complicated or detailed, we shouldn't make it inaccurate or treating the listener as idiot🐑
Keep the science and technical meaning balanced. Let's reduce unnecessary software jargons. Use clear language, examples and familiar concepts when you explain something complex.
**My technique is using analogies**, especially for my projects I often give a car example which is as simple as everybody can easily understand (*even my kid understands it*).
> MAKE IT SIMPLE, but NOT OVER-SIMPLE!
---
## Start With Why It Matters
In Turkey, there are some street sellers... They stop you and say "Can I tell you something?". Actually I know he's a seller and probably he'll redirect me to a barber, cosmetic store or some shops which are upper floors in a passage. And I mostly say "NO!" and I'm walking my way... But imagine if he tells me first which benefit I'll get from what he sells, maybe I'll go to his shop. (*this paragraph is also explaining my topic in a simple way which I explained in the previous section so I'm still using these techniques in this article* 🤫)
![image-20260906212109817](image-20260906212109817.png)
One of the most common mistakes in technical presentations is starting with the technology itself.
> Our project runs the Dijkstra algorithm with the multi-tenant and DDD architecture 🧑‍🔬
The above sentence doesn't mean anything to him. Tell it like this:
> Our project finds the shortest path efficiently, you can have many isolated customers with clean design and long years maintainable way.”
When people understand why your project matters, they'll have a reason to listen the next sections.
So far, so good 💯 You did a good job reading until here 🙏 ᵗʰᵃᶰᵏᵧₒᵤ ... Keep reading please ...👀...👇
---
## Think About What You Want Him to Remember
Your audience will not remember many technical points after your presentation.
**They will remember 1-2 topics.**
Decide what those points are 🎯 then build the presentation around them.
Everything else must support those core messages.
---
## Your Voice Tone Matters Too!
Imagine you did everything 👏 very good until here... but you are talking very monotonous way. Or you are talking quickly. Sorry, that's also not a good talk! **Your emphasis, eye contact, body language, tone of voice are all important.** You can make small jokes to give him a relaxing break to understand your complex technical work.
> COMMUNICATION IS NOT ONLY ABOUT WHAT YOU SAY but also HOW YOU SAY IT 🗣
Watch the📹 [ShadeZahrai -very short- tiktok video](https://www.tiktok.com/@shadezahrai/video/7177549216464571650)
![image-20260906210745253](image-20260906210745253.png)
---
## Use Images to Make Your Subject Clear
Especially when you are presenting on slides, you should show some funny images related to your topic or you can show analogic images that explains the problem.
For example to tell about a risky case which you covered in your project, you can use the below image :)
Yes, people will laugh at first but later they'll listen to you more carefully because you took their attention. (*I created another paradox here, I’m explaining this topic using a funny related image and I know you’re now reading my article more carefully*🤝)
![image-20260906201600152](image-20260906201600152.png)
---
## How to Handle Questions? 😡 Especially Which You Don't Like
![image-20260906202807792](image-20260906202807792.png)
In technical presentations, people can ask aggressive or stupid questions or you may not like their questions 😡
Don't immediately try to defend yourself by giving more and more technical details. Or don't try to show them it's a silly question.
If you don't know, tell it honestly. If that feature doesn't exist, tell that you took note and you'll evaluate it later.
Even if it’s a stupid question, don’t shut him down. **Later, he will remember only that moment and all your efforts you’ve made will be lost.**
---
## Your Goal Is To Be Understandable 🫱🏽‍🫲🏻 Not Showing Everything You Know
Anddd again, we come back to empathy!
> The best technical explainer is not the person who gives the most information.
![image-20260906204302915](image-20260906204302915-1788717035148-1.png)
Okay, you know a lot and you want to show that. But try to be empathetic again. Giving someone all the technical details doesn't mean they will understand your point. **Good communication means sharing what matters in a way people can easily understand.**
> Don't tell people everything you know. Tell them what they need to know and please make sure they understand it.
---
## Explaining Something and Convincing Someone Are Not the Same 🙄
Providing accurate & correct information and persuading someone to take action are different.
But in business life, **technical presentations often need to do both**.
You need to explain how something works and also helping management approve a project.
YOU CAN USE THIS PATH WHEN PRESENTING YOUR PROJECT:
![image-20260906203343446](image-20260906203343446.png)
---
I appreciate you taking the time to read this article 🙏.
I like to share what I learn which is the main reason I wrote this article.
By applying these techniques, we can become better presenters and communicate our ideas more effectively 👌.
When we combine our technical strengths with strong soft skills, I believe we can make a greater impact, inspire others and grow together 🙌💪.
---
Alper Ebicoglu
Software architect since the early 2000s.
Learning, inspiring, sharing, talking...
|||
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| <a href="https://www.linkedin.com/in/ebicoglu/"><img src="https://img.icons8.com/color/32/linkedin.png"/></a> | [linkedin.com/in/ebicoglu](https://www.linkedin.com/in/ebicoglu/) |
| <a href="https://x.com/alperebicoglu"><img src="https://img.icons8.com/color/32/twitterx.png"/></a> | [x.com/alperebicoglu](https://x.com/alperebicoglu) |
| <a href="https://alperonline.medium.com"><img src="https://img.icons8.com/color/32/medium.png"/></a> | [alperonline.medium.com](https://alperonline.medium.com) |
| <a href="https://github.com/ebicoglu"><img src="https://img.icons8.com/color/32/github.png"/></a> | [github.com/ebicoglu](https://github.com/ebicoglu) |

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906201600152.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 368 KiB

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906202807792.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 158 KiB

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906203343446.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 540 KiB

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906204302915-1788717035148-1.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 176 KiB

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906210745253.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 81 KiB

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906212109817.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 104 KiB

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906212829582.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 214 KiB

BIN
docs/en/Community-Articles/2026-09-06-How-to-Present-Your-Project-To-Your-Mother/image-20260906225734694.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.7 MiB

137
docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/Post.md

File diff suppressed because one or more lines are too long

BIN
docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/ai-connection-settings.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 61 KiB

BIN
docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 498 KiB

BIN
docs/en/Community-Articles/2026-09-14-ABP-Studio-AI-Agent-Bring-Your-Own-Key/included-models-catalog.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

406
docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/POST.md

@ -0,0 +1,406 @@
# Vector and Hybrid Search with SQL Server in EF Core 11
> Requires .NET 11 and EF Core 11. Verified against EF Core `11.0.0-rc.1.26425.128`.
A help center has a few thousand articles in SQL Server. Users type what went wrong in their own words — "login keeps timing out" — and the search returns nothing, because the article that answers them is titled "session expires too quickly" and shares no words with the query.
The usual fix is to put a vector database next to the application: pick one, sync the rows into it, keep the two stores consistent, and accept a second system to operate, back up, and secure. That is a lot of infrastructure for one feature, and the articles are already sitting in SQL Server.
SQL Server 2025 added a `vector` type, distance functions, and DiskANN vector indexes. EF Core 10 made the storage side usable from .NET. EF Core 11 adds the remaining query-side building blocks: approximate search over a vector index, full-text search table-valued functions, and translation for .NET 11's new `FullJoin` operator.
This article follows that help center from the first embedding to a working hybrid search, adding each feature at the point where the previous step stops being enough.
## Storing Embeddings Next to the Articles
Add a `SqlVector<float>` property and specify how many dimensions the column holds. The dimension count is mandatory; leaving it out fails model validation.
```csharp
public class Article
{
public int Id { get; set; }
public string Title { get; set; } = null!;
public string Content { get; set; } = null!;
[Column(TypeName = "vector(1536)")]
public SqlVector<float> Embedding { get; set; }
}
```
Generating the embedding happens outside the database. [`Microsoft.Extensions.AI`](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai) provides a provider-agnostic `IEmbeddingGenerator<string, Embedding<float>>`, so which model produces the vector stays a configuration decision:
```csharp
IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator = /* your provider */;
article.Embedding = new SqlVector<float>(
await embeddingGenerator.GenerateVectorAsync(article.Content));
await context.SaveChangesAsync();
```
The user's query goes through the same generator. That is not optional: distances are only meaningful between vectors from the same model, and a different dimension count will not fit the `vector(1536)` column at all.
Keeping the vectors in the same database removes the sync problem between two stores, but the embedding is still derived data with a lifecycle. Regenerate it whenever the source text changes, or the search keeps matching the old wording. Version the model and dimension count, because switching models means backfilling every row. And long articles usually need chunking rather than one vector for the whole `Content`.
```csharp
var query = new SqlVector<float>(
await embeddingGenerator.GenerateVectorAsync(queryText));
```
## Searching by Meaning
With embeddings stored, the first working version of the search is an `OrderBy` on distance:
```csharp
var hits = await context.Articles
.OrderBy(a => EF.Functions.VectorDistance("cosine", a.Embedding, query))
.Select(a => new { a.Id, a.Title })
.Take(5)
.ToListAsync();
```
```sql
SELECT TOP(@p) [a].[Id], [a].[Title]
FROM [Articles] AS [a]
ORDER BY VECTOR_DISTANCE('cosine', [a].[Embedding], @query)
```
This is exact k-nearest-neighbor search. Every row is compared, so it returns the true nearest neighbors for the chosen metric. "login keeps timing out" now finds "session expires too quickly", and the help center ships.
The supported metrics are `cosine`, `euclidean`, and `dot`. Cosine is common for text embeddings, but use whichever the model's documentation recommends, and note whether it expects normalized vectors.
This is also where a lot of applications stop. Exact search stays reasonable up to roughly 50,000 vectors — or any table size, as long as a `WHERE` clause narrows the candidates first — and it is all stable EF Core 10 API.
## When the Scan Becomes the Bottleneck
The help center grows. Every search now computes a distance for every row, and the scan shows up in traces.
Vector indexes exist to avoid that. SQL Server uses [DiskANN](https://www.microsoft.com/en-us/research/publication/diskann-fast-accurate-billion-point-nearest-neighbor-search-on-a-single-node), a graph index built for vectors that do not fit in memory, and a search walks a small part of the graph instead of the whole table.
The trade-off is in the name: **approximate** nearest neighbor search can miss a true neighbor. That is usually acceptable for ranking, where a different item somewhere in the top-k changes nothing a user would notice — but it is worth measuring recall on your own corpus rather than assuming it.
![Exact versus approximate search — conceptual example](images/exact-vs-approximate.png)
Configure the index in the model:
```csharp
modelBuilder.Entity<Article>()
.HasVectorIndex(a => a.Embedding)
.HasMetric("cosine")
.HasType("DiskANN");
```
`HasMetric` is required, and the metric configured here must match the one passed at query time or the index is not used. A vector index also covers exactly one column.
Note that the second argument to `HasVectorIndex` is the index name, not the metric — the [documentation](https://learn.microsoft.com/en-us/ef/core/providers/sql-server/vector-search#vector-indexes) currently passes `"cosine"` there. Written that way the index is called `"cosine"`, no metric is set, and model validation fails.
### Getting the Index Created at All
Deploying that index is harder than it looks. A vector index cannot be created on a table with fewer than 100 non-null vectors, and creating it too early fails with `Msg 42266`.
`UseSeeding` runs after the whole migration batch, so you cannot rely on it to prepare data for a later migration in the same update. Split the work into explicit ordered steps instead: create the table, write at least 100 non-null vectors with a data migration, then create the index in the migration after that.
Three more constraints are worth knowing before you design the deployment. The table must have a clustered primary key — and SQL Server 2025 is stricter than the limitations page reads: error 42217 asks for that key to be *a single 4 byte INT column*. Azure SQL Database, which carries the newer index version, accepted `bigint` and `uniqueidentifier` keys when I tried it, so this one is worth testing on your own target rather than assuming either way. `TRUNCATE TABLE` is blocked while a vector index exists. And vector indexes cannot be deployed through DacPac or BACPAC, because the import creates schema before loading data and therefore hits the 100-row rule — drop the index before exporting and recreate it after the import.
### Querying the Index
```csharp
var hits = await context.Articles
.VectorSearch(a => a.Embedding, query, "cosine")
.OrderBy(r => r.Distance)
.Take(5)
.WithApproximate()
.ToListAsync();
```
```sql
SELECT TOP(@p1) WITH APPROXIMATE [a].[Id], [a].[Content], [a].[Title], [v].[Distance]
FROM VECTOR_SEARCH(
TABLE = [Articles] AS [a],
COLUMN = [Embedding],
SIMILAR_TO = @p,
METRIC = 'cosine'
) AS [v]
ORDER BY [v].[Distance]
```
`VectorSearch()` returns `IQueryable<VectorSearchResult<T>>`, which carries both the entity (`Value`) and the computed `Distance`. `WithApproximate()` must come after `Take()` — it is what turns `TOP(n)` into `TOP(n) WITH APPROXIMATE`. On the latest index version, a `Where()` placed before `Take()` is applied inside the search, so filters narrow the candidate set rather than trimming results afterwards.
The failure mode to guard against is forgetting `WithApproximate()`. On a platform that accepts the generated syntax at all — see the next section — the query still compiles, still runs, and still returns correct results, by scanning every row with the index unused. EF only warns in the log, so turn that warning into an error while developing:
```csharp
options.UseSqlServer(connectionString)
.ConfigureWarnings(w => w.Throw(SqlServerEventId.VectorSearchWithoutApproximateIndexWarning));
```
## Where This Actually Runs
Before committing to that path, check that it runs on your target at all. The new approximate-search APIs — `VectorSearch()`, `WithApproximate()` and the vector index builder — carry `[Experimental("EF9105")]`, so your code does not compile until the diagnostic is acknowledged with `<NoWarn>$(NoWarn);EF9105</NoWarn>`. `VectorDistance()`, `FreeTextTable()`, `ContainsTable()` and the full-text modelling APIs are not marked.
The attribute itself only affects compilation. What decides whether a query runs is the server product, its region, and the version of the vector index.
| Capability | SQL Server 2025 container `17.0.5005.3` | Azure SQL Database |
|---|---|---|
| `vector` column, `SqlVector<float>` | ✅ | ✅ |
| `EF.Functions.VectorDistance()` | ✅ | ✅ |
| `CREATE VECTOR INDEX` from a migration | ✅ | ✅ |
| **`VectorSearch()` + `WithApproximate()`** | ❌ | ✅ |
| Full-text search | ❌ not installed in the image | ✅ |
| `PREVIEW_FEATURES` required for indexes and `VECTOR_SEARCH` | ✅ | ❌ |
The SQL Server 2025 column reports one tested build, the stock `mcr.microsoft.com/mssql/server:2025-latest` image. Full-text search is missing because that image does not ship the component, not because SQL Server 2025 lacks it.
On SQL Server 2025, `CREATE VECTOR INDEX` and `VECTOR_SEARCH` are documented as preview features that need the database scoped configuration turned on first:
```sql
ALTER DATABASE SCOPED CONFIGURATION SET PREVIEW_FEATURES = ON;
```
Azure SQL Database does not require it.
Even with that enabled, the generated query is rejected on the tested `17.0.5005.3` build with `Incorrect syntax near 'APPROXIMATE'`. Dropping `WithApproximate()` gives a more informative failure, `Incorrect syntax near 'TOP_N'`, even though the generated SQL contains no `TOP_N` anywhere.
That build requires `TOP_N` inside the function call, which is the older calling convention:
```sql
SELECT TOP(3) t.Id, s.distance
FROM VECTOR_SEARCH(TABLE = Articles AS t, COLUMN = Embedding, SIMILAR_TO = @qv,
METRIC = 'cosine', TOP_N = 3) AS s
ORDER BY s.distance;
```
That form runs. The server supports approximate search; it speaks the older dialect, and EF generates only the newer one, with no compatibility switch. On Azure SQL Database — and on SQL database in Microsoft Fabric, which also carries the latest index version — the EF query runs unchanged.
The two index versions differ in behaviour, not only in syntax. On the older version the table becomes read-only once the index exists. `ALLOW_STALE_VECTOR_INDEX` lifts that on Azure SQL Database and SQL database in Microsoft Fabric, but that database scoped configuration does not exist on SQL Server 2025, so on the build tested here there is no way back to a writable table. `WHERE` predicates are also applied after retrieval rather than during it, so `TOP_N` has to be widened by hand to survive filtering. The iterative filtering described above belongs to the latest index version.
Two more environment notes. As of September 2026, Azure SQL Database vector search is live in North Europe and UK South only, so check region availability before planning around it. And `SERVERPROPERTY('IsFullTextInstalled')` returns 0 on `mcr.microsoft.com/mssql/server:2025-latest`, so full-text search needs a derived image that installs `mssql-server-fts`.
## The Embeddings Come Back Empty
A bug report arrives: an admin edits an article's title, saves, and the search stops finding it — or a background job that re-reads embeddings gets nothing.
EF Core 11 excludes vector columns from the `SELECT` list by default when materializing entities:
```sql
SELECT TOP(@p) [a].[Id], [a].[Content], [a].[Title]
FROM [Articles] AS [a]
ORDER BY [a].[Id]
```
There is no `[Embedding]`, and the property comes back with a length of zero even though every row has a value.
The reasoning is sound. A 1,536-dimensional float vector is 6 KB per row, and embeddings are written rarely and searched against constantly but almost never read back. In a minimal benchmark, Microsoft measured roughly a 9x throughput improvement locally from not shipping them over the wire, and 22x against a remote Azure SQL database.
Vectors still work in `WHERE` and `ORDER BY`. Reading one requires an explicit projection:
```csharp
var embeddings = await context.Articles
.Select(a => new { a.Id, a.Embedding })
.ToListAsync();
```
So the title edit is safe: saving a tracked entity leaves the stored embedding untouched. That is correct here because the vector is generated from `Content` alone. The sample that ships with this article embeds the title as well, and there the same edit does leave a stale vector behind — which input feeds the embedding decides whether an edit invalidates it. What breaks is code that *reads* `Embedding` from a tracked entity: it gets an empty vector, and ordinary property access returns it without any warning. Check `context.Entry(article).Property(a => a.Embedding).IsLoaded` when it matters, or project the property explicitly.
## Exact Terms Still Fail
The next complaint is different. Users searching for an error number, a plan name, or a specific setting get articles that are thematically close and factually wrong. Vector search finds meaning and misses precision — that is what it is for.
EF Core has translated `EF.Functions.FreeText()` and `EF.Functions.Contains()` for years, but those are predicates: they filter without ranking, which is no help when you need a merged ordering later. EF Core 11 adds the table-valued versions, which return SQL Server's relevance score:
```csharp
var hits = await context.Articles
.FreeTextTable<Article, int>("session expires too quickly", topN: 20)
.Join(context.Articles, fts => fts.Key, a => a.Id, (fts, a) => new { a.Title, fts.Rank })
.OrderByDescending(x => x.Rank)
.ToListAsync();
```
`FullTextSearchResult<TKey>` exposes only `Key` and `Rank`, so the join back to the table is explicit, and both generic type arguments must be supplied explicitly because `TKey` cannot be inferred. `ContainsTable()` has the same shape but takes a search condition (`"nebula OR quasar"`, `NEAR`, prefix terms) instead of free text.
The catalog and index can be configured in the model as of EF Core 11:
```csharp
modelBuilder.HasFullTextCatalog("ftCatalog");
modelBuilder.Entity<Article>()
.HasFullTextIndex(a => new { a.Title, a.Content })
.UseKeyIndex("PK_Articles")
.UseCatalog("ftCatalog");
```
`UseKeyIndex` has to name a unique, single-column, non-nullable index — SQL Server uses it as the full-text key, which is what `FullTextSearchResult<TKey>.Key` returns.
That configuration has a side effect in the table definition rather than the index. `HasFullTextIndex` is built on `HasIndex`, so EF applies its ordinary index key size limit to the string properties involved, and a `Content` property that should map to `nvarchar(max)` comes out as `nvarchar(450)` — truncating the column you most wanted to search. Set the column type explicitly to keep the full length:
```csharp
modelBuilder.Entity<Article>()
.Property(a => a.Content)
.HasColumnType("nvarchar(max)");
```
One more thing that looks like a bug in tests: full-text population is asynchronous. In a 120-row sample it took about 20 seconds to become searchable after `CREATE FULLTEXT INDEX`, so a seed routine that queries immediately gets an empty result. Wait until the indexed row count catches up:
```sql
SELECT OBJECTPROPERTYEX(OBJECT_ID('Articles'), 'TableFulltextItemCount');
```
Give that loop an interval and a timeout, and check `TableFulltextFailCount` as well — rows that fail indexing never arrive, so waiting for the count to reach the table total can hang forever. The catalog-level `FULLTEXTCATALOGPROPERTY('ftCatalog', 'PopulateStatus')` is the more obvious check, but Microsoft has marked that property for removal and advises against polling it in a tight loop.
## Merging the Two Rankings
Now the help center has two searches that each fail differently, and neither one alone is the product. They have to be merged.
The standard merge is Reciprocal Rank Fusion: each document scores `1 / (k + position)` for every list it appears in, where `k` is a smoothing constant, and the scores are summed. With suitable parameters, a document that both retrievers rank moderately well can beat one that a single retriever ranks first.
![Hybrid search with reciprocal rank fusion](images/hybrid-search.png)
Evaluating a fusion needs a corpus where the two retrievers disagree. The one used here has 120 documents, a query text of `nebula quasar`, and an astronomy query vector: 12 documents match on both sides, 24 are semantically on topic but share no query words, 12 are lexical false friends — dessert menu items named *Nebula* and *Quasar*, embedded in a cooking topic — and 72 are unrelated. That corpus, and the console probe that produced every measurement below, are in the sample repository: [maliming/efcore11-vector-hybrid-search](https://github.com/maliming/efcore11-vector-hybrid-search).
Each retriever on its own:
```text
FreeTextTable Deep sky survey 4 (484), 9 (447), 6 (269), 8 (269), 2 (189), …
VectorSearch Observation log 26 (0.0112), 34 (0.0125), 18 (0.0134), 32 (0.0145), …
```
Both lists lead with one group each: full-text with documents the corpus makes match on both sides, vector search with the semantic-only ones. Neither puts a doubly-corroborated document first.
### The Documented Single-Query Shape
The documentation builds the fusion as a single query, joining the two retrievers with .NET 11's `FullJoin` and computing the score in the projection. As observed on `11.0.0-rc.1.26425.128`, that shape has three practical problems. Re-check the first two against GA before building on them.
The first stops the build. The sample compares `vs == null`, but `VectorSearchResult<T>` is a `readonly struct`, so that is `CS0019`. Projecting the vector side to a reference type first — `.Select(r => new { Article = r.Value, r.Distance })` — fixes it.
The second is materialization. Once the fused score is computed in the projection, reading back a result set that contains rows matched on one side only throws `InvalidOperationException: Nullable object must have a value`.
Projecting the same entity and nullable scalars without that score expression works, so it is the fused projection that breaks rather than the full join itself.
The third is the score, and it is wrong in two separate ways.
It inverts the full-text ranking. SQL Server's `RANK` is higher-is-better, so feeding it into `1 / (k + Rank)` gives the *least* relevant keyword matches the highest score. In the measured run, a document with `RANK` 119 scored above one with `RANK` 140.
It also turns vector membership into a flat bonus. Cosine distances sit near zero, so with the documented `k` of 20 the vector term is about `1 / 20 = 0.05` for anything in the vector list, while the entire full-text term spans roughly 0.002 to 0.007 across the ranks in this run. Simply appearing in the vector results is worth seven to twenty-five times more than any difference in keyword relevance.
Neither side uses rank positions, which is what RRF is defined over.
### Fusing on Rank Positions
Fetching the two ranked lists separately and applying RRF in memory avoids all three:
```csharp
const int candidateCount = 20;
const int rrfK = 60; // the constant from the original RRF paper
var lexical = await context.Articles
.FreeTextTable<Article, int>(queryText, topN: candidateCount)
.Join(context.Articles, fts => fts.Key, a => a.Id, (fts, a) => new { a.Id, a.Title, fts.Rank })
.OrderByDescending(x => x.Rank)
.ThenBy(x => x.Id)
.ToListAsync();
var semantic = await context.Articles
.OrderBy(a => EF.Functions.VectorDistance("cosine", a.Embedding, queryVector))
.ThenBy(a => a.Id)
.Select(a => new { a.Id, a.Title })
.Take(candidateCount)
.ToListAsync();
var lexicalPosition = lexical.Select((x, i) => (x.Id, Position: i + 1)).ToDictionary(x => x.Id, x => x.Position);
var semanticPosition = semantic.Select((x, i) => (x.Id, Position: i + 1)).ToDictionary(x => x.Id, x => x.Position);
var titles = lexical.Select(x => (x.Id, x.Title))
.Concat(semantic.Select(x => (x.Id, x.Title)))
.DistinctBy(x => x.Id)
.ToDictionary(x => x.Id, x => x.Title);
var fused = titles.Keys
.Select(id => new
{
Id = id,
Title = titles[id],
LexicalPosition = lexicalPosition.TryGetValue(id, out var l) ? l : (int?)null,
SemanticPosition = semanticPosition.TryGetValue(id, out var s) ? s : (int?)null,
Score = (lexicalPosition.TryGetValue(id, out var lp) ? 1.0 / (rrfK + lp) : 0.0)
+ (semanticPosition.TryGetValue(id, out var sp) ? 1.0 / (rrfK + sp) : 0.0)
})
.OrderByDescending(x => x.Score)
.ThenBy(x => x.Id)
.Take(10)
.ToList();
```
The `ThenBy` calls matter at both levels. Full-text ranks tie often — two documents above share `RANK` 269 — and the positions those lists produce are what the score is built from, so an unstable input order moves the final score. Ties in the score itself are just as common: two pairs below land on exactly `0.01639` and `0.01613`.
The semantic list here comes from `VectorDistance()`, which keeps the whole pipeline on stable API and runs on any SQL Server 2025 instance. On Azure SQL Database in a supported region, swap that one query for the indexed version and nothing else changes:
```csharp
var semantic = await context.Articles
.VectorSearch(a => a.Embedding, queryVector, "cosine")
.OrderBy(r => r.Distance)
.Take(candidateCount)
.WithApproximate()
.Select(r => new { r.Value.Id, r.Value.Title, r.Distance })
.ToListAsync();
// VECTOR_SEARCH accepts a single ascending ordering on the distance, so the tie-break the
// exact query does in SQL has to happen here instead.
semantic = [.. semantic.OrderBy(x => x.Distance).ThenBy(x => x.Id)];
```
That last line is not decoration: `VECTOR_SEARCH` only takes one ordering key, so the approximate path cannot express the tie-break in SQL and has to apply it after the rows come back. Against this corpus both versions produce the same fused ranking, which is what you would hope for at 120 documents — the approximate path earns its keep at a scale where the exact scan hurts, not by changing the answer.
Two round trips instead of one, and the fusion itself is a dictionary lookup over at most `2 * candidateCount` rows:
```text
title lexical# semantic# score
Deep sky survey 8 4 5 0.03101
Deep sky survey 1 7 12 0.02881
Deep sky survey 10 10 9 0.02878
Deep sky survey 5 9 16 0.02765
Deep sky survey 3 8 19 0.02736
Deep sky survey 4 1 - 0.01639
Observation log 26 - 1 0.01639
Deep sky survey 9 2 - 0.01613
Observation log 34 - 2 0.01613
Deep sky survey 6 3 - 0.01587
```
`Deep sky survey 8` is ranked 4th by keywords and 5th by vectors — first by neither — and wins outright because both retrievers agree on it.
That ordering is a parameter choice, not a universal truth. With `rrfK = 60` and `candidateCount = 20`, the worst possible two-list score is `2 / (60 + 20) = 0.025` and the best possible one-list score is `1 / (60 + 1) = 0.0164`, so anything both retrievers return outranks anything only one of them found. For the help center that pushes keyword-only false positives down — but it would push down a correct error number just as hard, if the vector side happened to miss it. When exact identifiers matter, lower `rrfK`, widen the candidate lists, or add an explicit boost for exact matches.
The companion web application in that same repository puts all three strategies on one page. It ships the help center corpus from the opening — 32 articles, a separate set from the 120 documents used for the measurements above:
![The three retrieval strategies side by side in the sample application](images/demo-three-strategies.png)
The opening query behaves as described. Semantic search returns *Session expires too quickly* first — a title that shares no words with the query. Keyword search mixes in *Sign in sheet export template* — a reporting article about attendance sheets — and a billing article about declined cards. The fused list puts four authentication articles on top and drops both false friends below them. *Session expires too quickly*, which only the vector side found, lands at 8: the trade-off from the paragraph above, on this sample corpus.
Clicking a result expands it:
![The expanded article panel, showing that the vector did not come back with the entity](images/demo-article-detail.png)
`Came back with the entity: no` is the earlier section made visible — loading the article never fetched its 1,536 floats, and the values in the panel come from a second query that projects the property explicitly.
## What to Ship
Following that path end to end, the version worth deploying is smaller than the feature list suggests.
Store embeddings in a `vector` column and search with `VectorDistance()`. That API is stable, exact, runs on any SQL Server 2025 instance, and is fast enough for tens of thousands of candidate articles. Add a full-text index when exact terms matter, and fuse the two ranked lists on positions in application code. Both halves are non-experimental, and the fusion works with either vector retriever.
Reach for `VectorSearch()` and a vector index when profiling shows the scan is actually the bottleneck, and only on Azure SQL Database or SQL database in Microsoft Fabric in a region that supports it. Treat that path as preview on both sides.
## Summary
EF Core 11 lets you build semantic, lexical, and hybrid search on SQL Server without a separate vector database. Start with exact search, add full-text search when exact terms matter, and use approximate search only when scale justifies its preview constraints. And remember that vector columns are no longer loaded by default when materializing entities.
## References
- [What's New in EF Core 11](https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-11.0/whatsnew)
- [Vector search in the SQL Server EF Core Provider](https://learn.microsoft.com/en-us/ef/core/providers/sql-server/vector-search)
- [Full-text search in the SQL Server EF Core Provider](https://learn.microsoft.com/en-us/ef/core/providers/sql-server/full-text-search)
- [Vector search and vector indexes in the SQL Database Engine](https://learn.microsoft.com/en-us/sql/sql-server/ai/vectors)
- [`VECTOR_SEARCH` (Transact-SQL)](https://learn.microsoft.com/en-us/sql/t-sql/functions/vector-search-transact-sql)
- [`CREATE VECTOR INDEX` (Transact-SQL)](https://learn.microsoft.com/en-us/sql/t-sql/statements/create-vector-index-transact-sql)
- [Azure SQL Database feature availability by region](https://learn.microsoft.com/en-us/azure/azure-sql/database/region-availability)
- [Microsoft.Extensions.AI](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai)
- [Sample code for this article](https://github.com/maliming/efcore11-vector-hybrid-search) — the web application and the measurement probe
- [Reciprocal Rank Fusion outperforms Condorcet and individual rank learning methods](https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf) — the original RRF paper

BIN
docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

BIN
docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/demo-article-detail.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/demo-three-strategies.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 101 KiB

BIN
docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/exact-vs-approximate.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/en/Community-Articles/2026-09-16-vector-search-and-hybrid-search-in-ef-core-11/images/hybrid-search.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/2-conflict.jpeg

Binary file not shown.

After

Width:  |  Height:  |  Size: 834 KiB

BIN
docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/2-manifest.jpeg

Binary file not shown.

After

Width:  |  Height:  |  Size: 881 KiB

BIN
docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/3-podman.jpeg

Binary file not shown.

After

Width:  |  Height:  |  Size: 608 KiB

BIN
docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/5-checklist.jpeg

Binary file not shown.

After

Width:  |  Height:  |  Size: 451 KiB

79
docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/Post.md

@ -0,0 +1,79 @@
# .NET 11 Container Publishing: Hype, Hands-On Reality, and the DevOps Playbook
Shipping multi-platform, secure containers without maintaining complex `Dockerfile`s is the holy grail for platform engineering. With .NET 11 (Release Candidate 1), Microsoft heavily markets its built-in SDK container publishing as the solution. But marketing claims and CI/CD realities often clash.
After running the .NET 11 RC1 SDK through an isolated sandbox environment—testing everything from cross-compilation to rootless runtimes—here is the unvarnished DevOps breakdown of what actually works, what is overhyped, and how you should adapt your pipelines.
## 1. SDK-Driven Publishing and the Base Image Reality
The SDK natively understands your `.csproj` and generates an OCI-compliant image without a single Dockerfile command. Running a simple publish command works effortlessly:
```bash
dotnet publish /t:PublishContainer -p:ContainerRepository=my-registry.local/myapp -p:ContainerImageTag=1.0.0
```
The process takes roughly 6 to 11 seconds. However, contrary to the belief that the SDK defaults to "microscopic" secure images, the default base image pulled is the standard Debian-based `aspnet:11.0.0-rc.1`, resulting in a ~256MB footprint.
To achieve a minimal attack surface, you must explicitly opt into Ubuntu Chiseled images. In .NET 11, the correct chiseled tag family corresponds to Ubuntu 26.04 (Resolute) rather than Ubuntu 24.04 (Noble). If you rely on auto-inference during the preview/RC phase, the SDK might incorrectly target `noble-chiseled` and fail, so you must explicitly declare it:
```xml
<!-- Add this to your .csproj -->
<ContainerFamily>resolute-chiseled</ContainerFamily>
```
While marketing sometimes hints at sub-50MB footprints, sandbox testing shows a standard minimal API built on `resolute-chiseled` clocks in at **128MB uncompressed**—still an excellent 50% reduction with zero package managers or shells included.
## 2. Multi-Architecture: The Massive Win and the Critical Gotcha
Transitioning to ARM64 (like AWS Graviton) saves money, but configuring QEMU and Docker Buildx in CI pipelines is notoriously slow. .NET 11 handles this beautifully at the compiler level.
By passing `-r linux-arm64`, the SDK cross-compiles the Intermediate Language (IL) natively and constructs the ARM64 container layers on an x64 runner without ever invoking QEMU. This is a massive CI performance win.
**The Pipeline Gotcha:** You cannot rely on the SDK to build a true multi-architecture tag (a single `latest` tag that resolves correctly on both architectures). If you run consecutive publish commands for `linux-x64` and `linux-arm64` pointing to the same registry tag, the second push **completely overwrites** the first manifest.
![conflict](./2-conflict.jpeg)
---
To create a genuine multi-arch manifest list, your CI/CD pipeline still requires a manual step.
![manifest](./2-manifest.jpeg)
---
> **Key insight:** Build and push architecture-specific tags (`latest-amd64`, `latest-arm64`) with the SDK, then use `docker manifest create` or `buildah manifest` at the end of your pipeline to bind them together.
## 3. Daemonless CI/CD: Seamless Podman Integration
If your enterprise strictly enforces rootless, daemonless CI/CD agents, .NET 11 is a game changer. Historically, using Podman required brittle `DOCKER_HOST` socket mapping hacks.
![podman](./3-podman.jpeg)
In testing, completely removing Docker from the `PATH` and installing only Podman resulted in flawless execution. The SDK automatically detects Podman and pushes directly to its local image store. You can finally adopt rootless Podman on RHEL/Ubuntu GitHub Action runners without modifying your `dotnet publish` commands.
## 4. Supply-Chain Security: The Reproducibility Illusion
Software Supply Chain standards like SLSA emphasize reproducible builds—the guarantee that the same source code produces the exact same artifact digest.
While the .NET 11 compiler is perfectly deterministic (producing byte-for-byte identical DLLs on identical source code), the resulting container image digest (SHA256) **will still change** on every build. This occurs because the container packing step embeds the current wall-clock time (`mtime`) into the headers of the `tar` filesystem layers. Until the SDK provides a robust `SOURCE_DATE_EPOCH` injection mechanism, strict bit-for-bit image digest reproducibility requires external tooling.
## The DevOps Adoption Checklist
Before ripping out your `Dockerfile`s for .NET 11, evaluate your pipelines against these verified realities:
1. **Validate OS Dependencies:** No apt-get allowed.
The SDK cannot install OS-level packages (e.g., `ffmpeg`, `wkhtmltopdf`). If your app relies on them, stick to a `Dockerfile`.
2. **Force Chiseled Images:** Update your .csproj.
Add `<ContainerFamily>resolute-chiseled</ContainerFamily>` to halve your image size and eliminate shell-based CVE vectors.
3. **Keep Manifest Commands:** Don't trust the overwrite.
Continue using `docker manifest` in your pipeline to aggregate the lightning-fast, QEMU-free `linux-x64` and `linux-arm64` SDK builds into a single tag.
4. **Switch to Podman Agents:** Zero-config rootless builds.
Upgrade your self-hosted runners to Podman to immediately benefit from rootless container execution without updating build scripts.
![5-checklist](./5-checklist.jpeg)

BIN
docs/en/Community-Articles/2026-09-17-NET-11-Container-Publishing/cover-image.jpeg

Binary file not shown.

After

Width:  |  Height:  |  Size: 773 KiB

BIN
docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/async-validation-pipeline.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/join-family.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

BIN
docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/net-11-in practice-cover.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 412 KiB

512
docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/post.md

@ -0,0 +1,512 @@
Every .NET release ships a long list of changes. Most of them matter to library authors or to people chasing the last few percent of throughput. This article is about four changes in .NET 11 that show up in ordinary application code: a LINQ operator you have probably hand-rolled more than once, validation rules that can finally `await`, cache metrics you no longer have to write yourself, and a way to turn distributed tracing on and off from configuration.
Each section covers the problem, the API, a runnable example with its output, and the caveats I hit while testing. Everything was run on .NET 11 RC1, and the complete sample application is on GitHub: [github.com/ahmetcelik05/dotnet11-features-demo](https://github.com/ahmetcelik05/dotnet11-features-demo).
> **Where .NET 11 stands today.** .NET 11 RC1 shipped on September 8, 2026 with a go-live license. General availability is planned for November 10, 2026, and .NET 11 is a Standard Term Support (STS) release, supported until November 9, 2028. The APIs below are in RC1, but as you will see in the cache metrics section, details can still move before GA.
Short on time? The whole article in one table:
| Feature | What is new in .NET 11 | The catch I found on RC1 |
|---|---|---|
| LINQ joins | `FullJoin`, plus `Join`/`GroupJoin` overloads without a result selector | `GroupJoin` returns `IGrouping`, not a tuple; value-type `default` hides "no match" |
| Async validation | `AsyncValidationAttribute`, `IAsyncValidatableObject`, `Validator.*Async` | Synchronous `Validator` calls on the same model throw |
| Cache metrics | `MemoryCache` publishes an OpenTelemetry meter when `TrackStatistics` is on | The hit/miss tag name is being renamed before GA |
| Tracing rules | `AddTracing` with rules from code or configuration, live reload | Nothing is enabled by default, `Sample` is mandatory, OpenTelemetry is unaffected |
## The sample application
The sample is a small minimal API called `OrdersDemo`. It has no UI; you drive it with `curl` and watch the console. Each endpoint exists to demonstrate one feature, and the features also interact: placing an order runs async validation and then produces a traced activity.
![Sample application architecture](sample-app-architecture.png)
Each feature lives in its own folder under `Features` and registers itself through `Add...` and `Map...Endpoints` extensions, so `Program.cs` is only a composition root.
## 1. LINQ `FullJoin` and selector-less `Join`/`GroupJoin`
### The problem
.NET 10 added `LeftJoin` and `RightJoin`. A full outer join was still missing, so if you needed "everything from both sides, matched where possible" you wrote a left join, a right join, and a `Concat` or `Union`, or a `GroupJoin`/`SelectMany`/`DefaultIfEmpty` combination in each direction. Most of us have a `FullOuterJoin` extension method somewhere in a `Utils` folder, copied from a Stack Overflow answer. It works, right up until a reconciliation report is wrong.
A smaller annoyance: `Join` and `GroupJoin` always required a result selector. In most call sites that selector was `(a, b) => (a, b)`, typed for the hundredth time.
### The API
.NET 11 adds `FullJoin` and selector-less overloads of `Join` and `GroupJoin`. They exist on `Enumerable`, `Queryable`, and `AsyncEnumerable`. The new overloads take an optional `IEqualityComparer<TKey>` as a trailing parameter, and the same optional comparer is available on `LeftJoin` and `RightJoin`.
```csharp
// Full outer join, returning tuples
IEnumerable<(TOuter? Outer, TInner? Inner)> FullJoin<TOuter, TInner, TKey>(
this IEnumerable<TOuter> outer, IEnumerable<TInner> inner,
Func<TOuter, TKey> outerKeySelector, Func<TInner, TKey> innerKeySelector,
IEqualityComparer<TKey>? comparer = null);
// Full outer join with your own projection
IEnumerable<TResult> FullJoin<TOuter, TInner, TKey, TResult>(
this IEnumerable<TOuter> outer, IEnumerable<TInner> inner,
Func<TOuter, TKey> outerKeySelector, Func<TInner, TKey> innerKeySelector,
Func<TOuter?, TInner?, TResult> resultSelector,
IEqualityComparer<TKey>? comparer = null);
```
![Which rows each join returns](join-family.png)
### Example: reconciling two stock systems
The reconciliation endpoint compares stock levels reported by a warehouse and by an ERP system. A SKU can exist in either system or both, and when it exists in both the quantities may disagree. Three pair shapes, four statuses, one full outer join, and pattern matching on the tuple expresses all of it directly:
```csharp
internal sealed class ReconciliationService : IReconciliationService
{
public IReadOnlyList<ReconciliationRow> Reconcile(IEnumerable<WarehouseStock> warehouse, IEnumerable<ErpStock> erp)
{
var pairs = warehouse.FullJoin(
erp,
w => w.Sku,
e => e.Sku,
StringComparer.OrdinalIgnoreCase);
return [.. pairs.Select(ToRow)];
}
private static ReconciliationRow ToRow((WarehouseStock? Warehouse, ErpStock? Erp) pair) => pair switch
{
(null, { } erp) => new ReconciliationRow(erp.Sku, ReconciliationStatus.MissingInWarehouse, null, erp.Quantity),
({ } warehouse, null) => new ReconciliationRow(warehouse.Sku, ReconciliationStatus.MissingInErp, warehouse.Quantity, null),
({ } warehouse, { } erp) when warehouse.Quantity != erp.Quantity
=> new ReconciliationRow(warehouse.Sku, ReconciliationStatus.QuantityMismatch, warehouse.Quantity, erp.Quantity),
({ } warehouse, { } erp) => new ReconciliationRow(warehouse.Sku, ReconciliationStatus.Ok, warehouse.Quantity, erp.Quantity),
(null, null) => throw new UnreachableException("FullJoin never yields an empty pair."),
};
}
```
Calling `GET /reconciliation` with three warehouse rows (`LAPTOP-15`, `mouse-01`, `CHAIR-ERG`) and three ERP rows (`LAPTOP-15`, `MOUSE-01`, `DESK-STD`) returns four rows:
```json
[
{ "sku": "LAPTOP-15", "status": "Ok", "warehouseQuantity": 5, "erpQuantity": 5 },
{ "sku": "mouse-01", "status": "QuantityMismatch", "warehouseQuantity": 0, "erpQuantity": 3 },
{ "sku": "CHAIR-ERG", "status": "MissingInErp", "warehouseQuantity": 7, "erpQuantity": null },
{ "sku": "DESK-STD", "status": "MissingInWarehouse", "warehouseQuantity": null, "erpQuantity": 2 }
]
```
Note the second row: `mouse-01` and `MOUSE-01` matched only because of the `StringComparer.OrdinalIgnoreCase` argument. Without it they would be two separate "missing" rows, which is exactly what happens in real life when two systems disagree on casing and nobody passes a comparer.
### What the tests showed about the semantics
The documentation describes the join operators but not their ordering or null behaviour, so I wrote tests against RC1 to pin down what you can observe today.
Output order follows the outer sequence, with unmatched inner elements appended at the end: for `outer = [1, 2, 3]` and `inner = [3, 4, 2]`, `FullJoin` yields `(1, 0), (2, 2), (3, 3), (0, 4)`. Treat that as an implementation detail, not a guarantee. Null keys never match each other; a `null` key on either side produces an unmatched row, the same way `NULL = NULL` is false in SQL.
Look at that `(1, 0)` again. It means "outer 1 had no partner", but `0` is also a perfectly valid inner value, and nothing in the tuple tells you which. When the element type is a struct, use nullable elements or the `resultSelector` overload so you can tell the two apart.
One more surprise: the selector-less `GroupJoin` does not return tuples. The "What's new" page calls the new overloads "tuple-returning", which is true for `Join`, but `GroupJoin` returns `IEnumerable<IGrouping<TOuter, TInner>>` with the outer element as the `Key` and the matching inner elements as the group.
```csharp
var grouped = customers
.GroupJoin(orders, c => c.Id, o => o.CustomerId)
.Select(group => (group.Key.Name, Count: group.Count()));
```
### When to use it
Use `FullJoin` whenever you need a reconciliation, a diff, or a "who did not show up on the other list" report over two in-memory sequences. Keep the memory profile in mind: the inner sequence is fully materialised into a lookup, so put the smaller sequence on the inner side. Against a database, EF Core 11 translates `Queryable.FullJoin` to `FULL JOIN` on SQL Server. EF Core 11 is still in preview at the time of writing, so check the provider you use before relying on it.
That covers combining data that is already in memory. The next feature is about the data on its way in: the order request that arrives at `POST /orders` and has to be checked against systems you can only reach asynchronously.
## 2. Asynchronous validation with DataAnnotations
### The problem
`ValidationAttribute.IsValid` is synchronous. Rules that need I/O, such as "is this e-mail registered", "does this VAT number exist in the tax registry", or "is there enough stock", either blocked a thread with `.GetAwaiter().GetResult()` or moved out of the validation layer entirely. Once they move, their error messages no longer flow through `ValidationResult` and `ValidationProblemDetails`, and every consumer of the model has to remember to call them. You know the result: `[Required]` failures arrive as a tidy 400 with a field name, "customer not found" arrives as a 500 from the service layer, and the front-end team asks why.
### The API
.NET 11 adds an async path to `System.ComponentModel.DataAnnotations` with three pieces:
- `AsyncValidationAttribute`, an abstract base class with `IsValidAsync(object?, ValidationContext, CancellationToken)` returning `Task<ValidationResult?>`.
- `IAsyncValidatableObject`, with `ValidateAsync(ValidationContext, CancellationToken)` returning `IAsyncEnumerable<ValidationResult>`.
- Async counterparts on `Validator`: `ValidateObjectAsync`, `TryValidateObjectAsync`, `ValidatePropertyAsync`, `TryValidatePropertyAsync`, `ValidateValueAsync`, and `TryValidateValueAsync`.
![The async validation pipeline](async-validation-pipeline.png)
One design point matters before you write your first rule: the synchronous members are still required. `IsValid(object?, ValidationContext)` is abstract on `AsyncValidationAttribute`, and `IAsyncValidatableObject` inherits `IValidatableObject.Validate`. The framework samples throw from both so that accidental synchronous validation fails loudly instead of silently skipping the rule, and that is the approach I take below.
### Example: an async attribute and an async object rule
The order request in the sample uses both mechanisms. The attribute checks that the customer exists in a directory:
```csharp
[AttributeUsage(AttributeTargets.Property)]
public sealed class RegisteredCustomerAttribute : AsyncValidationAttribute
{
protected override ValidationResult? IsValid(object? value, ValidationContext validationContext) =>
throw new InvalidOperationException(
$"{nameof(RegisteredCustomerAttribute)} only supports asynchronous validation. Use Validator.ValidateObjectAsync.");
protected override async Task<ValidationResult?> IsValidAsync(
object? value, ValidationContext validationContext, CancellationToken cancellationToken)
{
if (value is not string email || string.IsNullOrWhiteSpace(email))
{
return ValidationResult.Success; // [Required] owns the empty-value case
}
var directory = validationContext.GetRequiredService<ICustomerDirectory>();
return await directory.ExistsAsync(email, cancellationToken)
? ValidationResult.Success
: new ValidationResult($"'{email}' is not a registered customer.", [validationContext.MemberName!]);
}
}
```
The model itself checks stock for every line, a rule that spans properties:
```csharp
public sealed class CreateOrderRequest : IAsyncValidatableObject
{
[Required, EmailAddress, RegisteredCustomer]
public string CustomerEmail { get; init; } = string.Empty;
[MinLength(1)]
public IReadOnlyList<OrderLine> Lines { get; init; } = [];
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext) =>
throw new InvalidOperationException($"Validate {nameof(CreateOrderRequest)} with {nameof(ValidateAsync)}.");
public async IAsyncEnumerable<ValidationResult> ValidateAsync(
ValidationContext validationContext,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
var inventory = validationContext.GetRequiredService<IInventoryService>();
foreach (var line in Lines)
{
var available = await inventory.GetAvailableQuantityAsync(line.Sku, cancellationToken);
if (available < line.Quantity)
{
yield return new ValidationResult(
$"Only {available} unit(s) of '{line.Sku}' are in stock.", [nameof(Lines)]);
}
}
}
}
```
Both rules resolve their dependencies from the `ValidationContext`, which means the context has to be created with a service provider. Minimal APIs do that for you; when you call `Validator` yourself, pass one in:
```csharp
var context = new ValidationContext(request, serviceProvider, items: null);
var results = new List<ValidationResult>();
var isValid = await Validator.TryValidateObjectAsync(
request, context, results, validateAllProperties: true, cancellationToken);
```
### Running it through a minimal API
`builder.Services.AddValidation()` has been available since .NET 10; it makes minimal API endpoints validate their parameters before the handler runs. What is new in .NET 11 is that the same call now runs the async rules as well, concurrently where possible. Posting an unknown customer:
```bash
curl -X POST http://localhost:5028/orders -H "Content-Type: application/json" \
-d '{"customerEmail":"nobody@example.com","lines":[{"sku":"MOUSE-01","quantity":2}]}'
```
```json
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": { "CustomerEmail": ["'nobody@example.com' is not a registered customer."] }
}
```
Only the attribute error is reported. That is by design: object-level validation runs after all property rules pass, so the stock check never executed. Post the same order with a registered customer and you get the object-level message instead:
```json
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": { "Lines": ["Only 0 unit(s) of 'MOUSE-01' are in stock."] }
}
```
### How the pipeline behaves
From reading `Validator` and confirming with tests, the async path works like this:
1. `[Required]` is evaluated first for each property and short-circuits that property on failure.
2. Synchronous attributes on a property run next. Async attributes run only if all synchronous ones pass, and they run concurrently.
3. Type-level attributes follow, then `IAsyncValidatableObject.ValidateAsync`.
4. Pass `null` for the results collection and validation stops at the first failure; pass a collection and it keeps going and collects everything.
5. The cancellation token flows into every async rule.
### The migration trap
So what happens when an older code path calls the synchronous `Validator.TryValidateObject` on a model that now carries an async attribute? Does it quietly skip the rule? No. It has no special handling for async attributes at all: it calls your synchronous `IsValid`, and if you followed the framework guidance, that throws:
```
System.InvalidOperationException: RegisteredCustomerAttribute only supports asynchronous validation. Use Validator.ValidateObjectAsync.
```
On purpose, and rightly so. But it makes adding an async attribute a breaking change for every caller that still validates synchronously, so find those callers before you decorate a shared model. Minimal APIs and Blazor forms use the async path in .NET 11; MVC controllers are not listed in the RC1 notes and the public design notes defer them to follow-up work, so treat MVC as a synchronous caller until the docs say otherwise.
Validation decides whether a request gets in. The next two features are about seeing what the application does once it is in, starting with the cache that every request touches.
## 3. Built-in OpenTelemetry metrics for `MemoryCache`
### The problem
`IMemoryCache` has had `GetCurrentStatistics()` for a while, but turning it into metrics meant polling it and publishing your own `Meter`. Every team wrote a slightly different decorator, and none of them agreed on instrument names. The decorator then quietly stopped being registered after a refactor, and the "cache hit ratio" panel on the dashboard showed a flat line for three weeks before anyone noticed.
### The API
Do you need an extra package or an adapter for this? No. In .NET 11, `MemoryCache` publishes a meter named `Microsoft.Extensions.Caching.Memory.MemoryCache` as soon as you opt in with `TrackStatistics = true`. The new `MemoryCacheOptions.Name` becomes a `dotnet.cache.name` tag so that multiple caches can share a process, and a new constructor overload accepts an `IMeterFactory` for per-instance meters. `MemoryCacheStatistics` gained `TotalEvictions` to back the new eviction counter.
RC1 publishes these four instruments, captured with a `MeterListener` in the test suite:
| Instrument | Type | Unit | Tags |
|---|---|---|---|
| `dotnet.cache.requests` | ObservableCounter | `{request}` | `dotnet.cache.request.type` = `hit` / `miss` |
| `dotnet.cache.evictions` | ObservableCounter | `{eviction}` | |
| `dotnet.cache.entries` | ObservableUpDownCounter | `{entry}` | |
| `dotnet.cache.estimated_size` | ObservableGauge | `By` | |
### Example: a read-through product catalog
In most applications the opt-in is a one-liner: `services.AddMemoryCache(options => options.TrackStatistics = true)`. In the demo the cache is configured through an `IConfigureOptions<MemoryCacheOptions>` instead, so that the demo-specific settings live next to the feature:
```csharp
public void Configure(MemoryCacheOptions options)
{
options.TrackStatistics = true; // opt-in: without this no instruments are published
options.Name = CacheName; // becomes the dotnet.cache.name tag
options.SizeLimit = productCache.Value.SizeLimit;
options.CompactionPercentage = productCache.Value.CompactionPercentage;
}
```
```csharp
internal sealed class CachedProductCatalog(IMemoryCache cache, IProductStore store) : IProductCatalog
{
public Task<Product?> GetAsync(string sku, CancellationToken cancellationToken) =>
cache.GetOrCreateAsync(sku, entry =>
{
entry.SetSize(1); // required when MemoryCacheOptions.SizeLimit is set
entry.SetSlidingExpiration(TimeSpan.FromMinutes(5));
return store.FindAsync(sku, cancellationToken);
});
}
```
To export the meter, add it to your OpenTelemetry metrics pipeline:
```csharp
services.AddOpenTelemetry()
.WithMetrics(metrics => metrics
.AddMeter("Microsoft.Extensions.Caching.Memory.MemoryCache")
.AddConsoleExporter());
```
After five requests for `LAPTOP-15` and one each for three other SKUs, the console exporter prints:
```
Metric Name: dotnet.cache.requests, Description: Total cache requests., Unit: {request}, Metric Type: LongSum
(...) dotnet.cache.name: products dotnet.cache.request.type: hit Value: 4
(...) dotnet.cache.name: products dotnet.cache.request.type: miss Value: 4
Metric Name: dotnet.cache.evictions, Description: Total cache evictions., Unit: {eviction}, Metric Type: LongSum
(...) dotnet.cache.name: products Value: 1
Metric Name: dotnet.cache.entries, Description: Current number of cache entries., Unit: {entry}, Metric Type: LongSumNonMonotonic
(...) dotnet.cache.name: products Value: 2
Metric Name: dotnet.cache.estimated_size, Description: Estimated size of the cache., Unit: By, Metric Type: LongGauge
(...) dotnet.cache.name: products Value: 2
```
Four misses (one per SKU), four hits, and one eviction because the size limit is three. The hit ratio is `hit / (hit + miss)`, which you can compute in any backend that supports the tag.
A detail that cost me a few minutes (and a brief, unfair suspicion of the runtime): with the default `CompactionPercentage` of 5 %, a three-entry cache never evicts anything; it just refuses the fourth entry. The demo uses 50 % so the counter moves; real caches are large enough that the default is fine.
### Caveats
- **The tag name is changing.** RC1 emits `dotnet.cache.request.type` and unit `By`; the `release/11.0` branch already has `dotnet.cache.request.result` and unit `1`, because `SizeLimit` is an application-defined number, not bytes. Re-check any dashboard or alert that references the tag at GA.
- **`TrackStatistics` is not free.** It adds interlocked increments on every hit and miss. That is cheap, but measure it on a hot cache before enabling it everywhere.
- **All four instruments are observable.** The hot path only increments the counters it already kept for `GetCurrentStatistics()`; values are read when a collector asks. `MeterListener` users therefore have to call `RecordObservableInstruments()`. The same release moved the HTTP `open_connections` and `active_requests` metrics to observable instruments, so this applies to more than the cache.
Metrics tell you how often the cache is hit. They do not tell you what a single slow order did along the way. For that you need traces, and the last feature is about deciding which traces you actually want, without a redeploy.
## 4. Declarative `Activity` tracing rules
### The problem
`ActivitySource.StartActivity` returns `null` unless some `ActivityListener` has said it is interested in that source. Deciding which sources are interesting has always happened in code: either an `ActivityListener` with a `ShouldListenTo` callback, or OpenTelemetry's `AddSource`. Changing the decision meant a redeploy. If you have ever watched a noisy health-check span flood a trace backend because nobody could turn it off in production, you know the feeling. Logging solved the equivalent problem years ago with `Logging:LogLevel` in `appsettings.json`, and metrics got `MetricsBuilder.EnableMetrics` in .NET 8. Tracing had nothing.
### The API
`Microsoft.Extensions.Diagnostics` in .NET 11 adds a tracing builder with the same shape as the metrics one:
```csharp
services.AddTracing(tracing =>
{
tracing.AddListener("console", listener => { /* ActivityListenerBuilder */ });
tracing.EnableTracing(sourceName: "OrdersDemo.Orders");
tracing.DisableTracing(sourceName: "OrdersDemo.Orders", operationName: "HealthCheck");
tracing.AddConfiguration(configuration.GetSection("Tracing"));
});
```
- `AddListener(name, configure)` registers a named `ActivityListener`. The `ActivityListenerBuilder` exposes `Sample`, `SampleUsingParentId`, `ActivityStarted`, `ActivityStopped`, and `ExceptionRecorder`.
- `EnableTracing` / `DisableTracing` add a `TracingRule`. `sourceName` is an exact name, a prefix, or a pattern with a single `*`; `operationName` and `listenerName` are exact matches; `null` matches everything.
- `AddConfiguration` reads rules from an `IConfiguration` section and re-applies them when the configuration reloads.
- The same release adds `ActivitySourceFactory` for creating sources through DI and unseals `ActivitySource`.
![How rules, listeners and sources fit together](tracing-rules.png)
The configuration shape mirrors logging. This is the sample's `appsettings.json`:
```json
{
"Tracing": {
"EnabledTracing": {
"OrdersDemo.Orders": {
"Default": true,
"HealthCheck": false
}
}
}
}
```
`EnabledTracing` applies to all listeners; `EnabledGlobalTracing` and `EnabledLocalTracing` target only sources created with `new ActivitySource(...)` or through `ActivitySourceFactory`, respectively; any other key under `Tracing` is a listener name with its own nested block. Inside a source, `Default` is the source-level rule, every other key is an operation name, and a bare boolean (`"OrdersDemo.*": true`) is shorthand for `Default`.
### Example: a console listener driven by configuration
In the demo there is one named listener, registered with `AddListener`, and the rules come from `AddConfiguration` alone, no code-based rules. The listener itself:
```csharp
internal static class ConsoleActivityListener
{
public const string Name = "console";
public static void Configure(ActivityListenerBuilder listener)
{
// The rules API makes no sampling decision for you: without Sample, StartActivity returns null.
listener.Sample = static (ref _) => ActivitySamplingResult.AllDataAndRecorded;
listener.ActivityStopped = Print;
}
private static void Print(Activity activity)
{
// Activity.Tags only yields string-valued tags; TagObjects includes numbers such as order.lines.
var tags = string.Join(' ', activity.TagObjects.Select(tag => $"{tag.Key}={tag.Value}"));
Console.WriteLine($"[trace] {activity.Source.Name}/{activity.OperationName} {activity.Duration.TotalMilliseconds:F1} ms {tags}");
}
}
```
`OrderService` creates its source through `ActivitySourceFactory` and starts two activities, `PlaceOrder` and `HealthCheck`:
```csharp
private readonly ActivitySource _activitySource =
activitySourceFactory.Create(new ActivitySourceOptions("OrdersDemo.Orders"));
// in PlaceOrderAsync
using var activity = _activitySource.StartActivity("PlaceOrder"); // enabled by rule
// in CheckHealthAsync
using var activity = _activitySource.StartActivity("HealthCheck"); // disabled by rule
```
Place an order and call the health endpoint. Only the order shows up:
```
[trace] OrdersDemo.Orders/PlaceOrder 10.2 ms order.customer=ada@example.com order.lines=1 order.id=ORD-6067
```
Now change `"HealthCheck": false` to `true` in `appsettings.json` while the app is running. The configuration reloads, the listener refreshes its filters, and the next two health calls print:
```
[trace] OrdersDemo.Orders/HealthCheck 16.0 ms
[trace] OrdersDemo.Orders/HealthCheck 6.6 ms
```
Set it back to `false` and the lines stop. No restart, no redeploy.
### What I learned by running it
The documentation for this feature is currently one paragraph and a five-line snippet, so most of the following comes from the source and from tests:
- **Nothing is enabled by default.** `AddTracing()` without rules enables no source.
- **You must set `Sample`.** A listener without a sampling callback never records anything, and `StartActivity` returns `null` for its sources. The snippet in the release notes omits this, which is why my first attempt produced no output at all.
- **Listeners activate when the host starts.** Rules are wired up during `IHost.StartAsync` (or when `ActivitySourceFactory` is first resolved). Building the service provider is not enough, which matters for tests and for tools that never start a host.
- **Rules cover sources created with `new ActivitySource(...)` too.** Those are "global" scope; factory-created sources are "local". A rule for `Legacy.*` picks up activities from a plain `new ActivitySource("Legacy.Billing")`.
- **Rules resolve like CSS selectors.** The most specific one wins: a listener name beats none, a longer source pattern beats a shorter one, an operation name beats none. Between equally specific rules the last one registered wins; avoid overlapping rules rather than relying on that.
### Rules and OpenTelemetry
The question everyone asks first: does `AddTracing` replace OpenTelemetry's `AddSource`? No. OpenTelemetry registers its own `ActivityListener`, and the rules only govern listeners registered through `AddTracing`. I confirmed this with an OpenTelemetry `TracerProvider` and a rule that disables `HealthCheck`: OpenTelemetry still received `HealthCheck`, and the rule-driven listener did not.
There is one interaction worth knowing about. ASP.NET Core's hosting layer creates a request activity even when no listener samples it, so that parent is unrecorded, and OpenTelemetry's default `ParentBased(AlwaysOn)` sampler follows the parent and drops the child spans. Sampling decisions are combined across listeners with the most permissive winning, so in my first run the rule-driven listener's `AllDataAndRecorded` decision is what got `PlaceOrder` exported, while `HealthCheck` looked as if the rule had suppressed it in OpenTelemetry too. It had not; the sampler had. The demo uses `SetSampler(new AlwaysOnSampler())` to keep the two mechanisms independent; in production, ASP.NET Core instrumentation samples the parent properly.
So where does this API fit? Use it for listeners you own: a console or file listener for local debugging, an in-process collector, a diagnostic listener you want operators to toggle in a running service. Keep your OpenTelemetry pipeline as it is.
Four features down. Here is how to run the application and the tests behind them yourself.
## Running the sample
The repository pins the SDK in `global.json` (`11.0.100-rc.1.26425.128`); the README shows how to install RC1 into a private folder without making it your machine's default SDK. Then, from the repository root:
```bash
dotnet test
dotnet run --project src/OrdersDemo # listens on http://localhost:5028 (from launchSettings.json)
```
The test project uses xUnit v3 on Microsoft.Testing.Platform, and the run I used for this article looked like this:
```
OrdersDemo.Tests.dll (net11.0|x64) passed [+28/x0/?0] (1s 461ms)
Test run summary: Passed!
failed: 0
skipped: 0
duration: 1s 896ms
```
Every observed behaviour listed in the feature sections above is backed by a test with a matching name.
## Preview and RC caveats
- **RC1 is go-live, not GA.** Names and units can still change; the cache tag rename (`request.type` → `request.result`, unit `By` → `1`) is already merged for release/11.0.
- **Async validation in MVC controllers** is not covered by the RC1 documentation; assume synchronous validation there.
- **Tracing rules have minimal documentation.** The behaviours above were verified against RC1 source and tests, not a specification; re-verify against the GA docs. EF Core 11's `FullJoin` translation is likewise still in preview.
## Adoption checklist
1. Target `net11.0`, pin the SDK in `global.json` with `rollForward: latestFeature`.
2. Replace hand-written full outer joins with `FullJoin`; test null keys and decide how value types represent "no match".
3. Convert `(a, b) => (a, b)` selectors to the selector-less `Join`/`GroupJoin` overloads; remember `GroupJoin` returns `IGrouping`.
4. Move I/O-bound rules to `AsyncValidationAttribute` or `IAsyncValidatableObject`; decide whether the synchronous members throw or fall back.
5. Find every synchronous caller of those models (`Validator.*`, MVC model binding, custom pipelines) and switch it, or keep async attributes off shared models.
6. Call `AddValidation()` in minimal API projects and pass `HttpContext.RequestAborted` through.
7. Enable `TrackStatistics`, set `MemoryCacheOptions.Name`, add the meter to OpenTelemetry, build a hit-ratio panel; re-check the tag name at GA.
8. If you use `MeterListener`, call `RecordObservableInstruments()` on your collection interval.
9. Move custom `ActivityListener` code to `AddTracing` with a named listener and a `Tracing` section; always set `Sample`; leave OpenTelemetry's `AddSource` alone.
10. Prefer `ActivitySourceFactory` over static `ActivitySource` fields in new code.
## Closing thoughts
None of these four features will headline the .NET 11 launch keynote, and that is exactly why they are worth knowing: they are the changes you will use on a Tuesday afternoon, not the ones you will benchmark. Good luck with the upgrade, keep the tests from this article close, and treat every "it obviously works like this" moment with a little suspicion until GA. Hit a surprise I did not cover? The sample repository is the place to open an issue.
## References
- [What's new in .NET 11](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/overview)
- [What's new in .NET libraries for .NET 11](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/libraries) (LINQ joins, async validation, cache metrics, tracing configuration)
- [What's new in ASP.NET Core for .NET 11](https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-11) (async validation in minimal APIs and Blazor)
- [.NET diagnostics overview](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/) and [Collect a distributed trace](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing-collection-walkthroughs)
- [Announcing .NET 11 Release Candidate 1](https://devblogs.microsoft.com/dotnet/dotnet-11-rc-1/)
- [dotnet/runtime #100317: Tracing configuration API proposal](https://github.com/dotnet/runtime/issues/100317) and [PR #129380](https://github.com/dotnet/runtime/pull/129380)
- [dotnet/runtime #124140: Metrics for MemoryCache API proposal](https://github.com/dotnet/runtime/issues/124140) and [PR #133151: tag and unit fix](https://github.com/dotnet/runtime/pull/133151)
- [Async validation design notes (dotnet/aspnetcore)](https://gist.github.com/halter73/f4d0974da579fb78d17bd2e6d9f78173) (MVC support deferred)
- [What's new in EF Core 11](https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-11.0/whatsnew) (FullJoin translation)

BIN
docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/sample-app-architecture.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 62 KiB

BIN
docs/en/Community-Articles/2026-09-17-net11-in-practice-fulljoin-async-validation-cache-metrics-tracing-rules/tracing-rules.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 73 KiB

516
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/ARTICLE.md

@ -0,0 +1,516 @@
# .NET 11 Runtime Async: Cleaner Stack Traces and Faster Async Paths
## Introduction
Asynchronous code is everywhere in a modern .NET application.
An HTTP endpoint awaits an application service. The application service awaits a repository. The repository awaits a database call. Logging, authorization, retries, serialization, and network operations add more asynchronous layers around the same request.
The C# code can still look simple:
```csharp
public async Task<OrderDto> GetAsync(Guid id)
{
Order order = await _orderRepository.GetAsync(id);
return ObjectMapper.Map<Order, OrderDto>(order);
}
```
However, the implementation below `async` and `await` has not been simple. In .NET 10 and earlier versions, the C# compiler normally turns each async method into a generated state machine. This design works well, but it can add infrastructure frames to live call stacks, create intermediate task-related objects, and make production profiling more difficult.
.NET 11 starts changing that foundation with **Runtime Async V2**.
The source code and the async programming model do not change. The important change happens below the source code: more of the async transformation moves from the C# compiler into the runtime and the JIT compiler. This gives .NET more information at the moment it optimizes the method.
For developers, the main results are:
- Cleaner live async stack traces.
- Better stepping and debugging through async code.
- Opportunities to remove intermediate `Task` objects and allocations.
- Smaller generated IL for eligible async methods.
- Better optimization of common async paths.
- A new lower-overhead foundation for async profiling.
This article explains what changed, where you can observe the difference, how to measure it, and what you should consider before enabling the preview feature in a real application.
## The main change: async lowering moves closer to the runtime
Consider this small method:
```csharp
static async Task<int> ReadLengthAsync(
Stream stream,
CancellationToken cancellationToken)
{
var buffer = new byte[4096];
int bytesRead = await stream.ReadAsync(buffer, cancellationToken);
return bytesRead;
}
```
With the classic model, the C# compiler creates a state-machine type. It usually contains:
- A state number.
- An async method builder.
- Fields for parameters and local values that must survive an incomplete `await`.
- Awaiter fields.
- A generated `MoveNext()` method.
`MoveNext()` runs the method until an awaited operation is incomplete. It saves the required state and registers itself as the continuation. Later, it runs again and continues from the saved state.
Runtime and JIT optimizations have made this model much cheaper over many .NET releases. Still, by the time the JIT receives the method, the compiler has already expanded a small source method into a more complex state machine.
![Classic compiler lowering compared with .NET 11 Runtime Async](assets/runtime-async-architecture.png)
With Runtime Async, the compiler emits smaller, suspension-aware IL and marks the method as async in metadata. The runtime and JIT then manage more of the transformation. They can use runtime information to decide:
- Which values are really alive at a suspension point.
- How continuation state should be stored.
- Whether an intermediate `Task` must be materialized.
- Whether a direct async call can use a more efficient calling path.
- How the method should be optimized after it becomes hot.
The programming model remains the same. `await`, cancellation, exceptions, synchronous completion, and `ConfigureAwait` keep their existing meaning. Microsoft states that behavioral compatibility is an explicit goal; an observable semantic difference should be treated as a bug.
### Enabling Runtime Async in a .NET 11 project
Application code must currently opt in:
```xml
<PropertyGroup>
<TargetFramework>net11.0</TargetFramework>
<Features>$(Features);runtime-async=on</Features>
</PropertyGroup>
```
No new C# syntax is required. You do not need `LangVersion=preview` or `EnablePreviewFeatures` for this switch in a `net11.0` project.
The .NET 11 runtime libraries are already compiled with Runtime Async enabled. Your own application and library methods use the new lowering only when you enable the feature during compilation.
## Cleaner live async stack traces
The clearest developer-experience improvement is visible in a **live stack trace**.
This means the stack shown by:
- The debugger Call Stack window.
- `new StackTrace()` while the code is running.
- A profiler that inspects live execution stacks.
- Diagnostic code that captures the current stack.
### Runnable example
The complete project is included in `samples/AsyncStackTraceDemo`. Its important part is:
```csharp
using System.Diagnostics;
await OuterAsync();
static async Task OuterAsync()
{
await Task.CompletedTask;
await MiddleAsync();
}
static async Task MiddleAsync()
{
await Task.CompletedTask;
await InnerAsync();
}
static async Task InnerAsync()
{
await Task.CompletedTask;
Console.WriteLine(new StackTrace(fNeedFileInfo: true));
}
```
The included script builds three variants:
1. .NET 10 with compiler-generated async lowering.
2. .NET 11 with compiler-generated async lowering.
3. .NET 11 with Runtime Async enabled.
On PowerShell:
```powershell
./scripts/run-samples.ps1
```
On Bash:
```bash
chmod +x ./scripts/run-samples.sh
./scripts/run-samples.sh
```
### Observed output
The .NET 10 and .NET 11 classic builds both produced 13 live frames. The output included repeated infrastructure frames similar to:
```text
InnerAsync()
AsyncMethodBuilderCore.Start(...)
InnerAsync()
MiddleAsync()
AsyncMethodBuilderCore.Start(...)
MiddleAsync()
OuterAsync()
AsyncMethodBuilderCore.Start(...)
OuterAsync()
Main()
AsyncMethodBuilderCore.Start(...)
Main()
Main(string[] args)
```
The Runtime Async build produced 5 frames:
```text
InnerAsync()
MiddleAsync()
OuterAsync()
Main()
Main(string[] args)
```
![Live stack trace comparison: 13 classic frames and 5 Runtime Async frames](assets/live-stack-comparison.png)
The exact generated method names can differ between source layout, SDK builds, and Debug or Release configuration. The useful result is the shape of the stack: Runtime Async shows the application call chain directly and removes the repeated async builder infrastructure from this example.
### Important: this is a live-stack improvement
Do not describe this feature as a general fix for `exception.StackTrace`.
Exception stack traces from code such as the following were already cleaned up by the existing async infrastructure:
```csharp
try
{
await ProcessAsync();
}
catch (Exception exception)
{
Console.WriteLine(exception.StackTrace);
}
```
The .NET 11 improvement is most visible while inspecting **live execution**, not after catching an exception.
## Where the performance opportunities come from
Runtime Async does not make every async operation faster and it does not remove every allocation. It gives the runtime new opportunities that were difficult to see after the compiler had already created a state machine.
### 1. Fewer intermediate Task objects
Consider a common layered call chain:
```csharp
static async Task<int> A() => await B();
static async Task<int> B() => await C();
static async Task<int> C()
{
await Task.Yield();
return 42;
}
```
In the classic model, every method has its own transformed state and task-like result. When the pattern is a direct call followed by a direct `await`, Runtime Async can sometimes use a special async calling path and link continuation state instead.
If the chain completes synchronously, the result can flow through internal calls as a value. If it suspends, the runtime can link continuation records without requiring a separate intermediate `Task<int>` at every eligible edge.
![How Runtime Async can avoid some intermediate Task objects](assets/task-materialization.png)
The optimization is not possible when the `Task` is observable as an object. For example:
```csharp
Task<int> task = GetValueAsync();
pendingTasks.Add(task);
task.ContinueWith(LogCompletion);
return task;
```
Here, the program stores and manually observes the task. The runtime must preserve that behavior and materialize the object.
### 2. Smaller generated IL and binaries
The classic transformation creates an entry method, a generated type, state fields, a builder, and `MoveNext()` for each async method.
Runtime Async leaves a smaller method body for the runtime to transform. In a deliberately async-heavy size test published by Microsoft, ten small async methods produced these assembly sizes:
| Lowering | Assembly size |
|---|---:|
| Compiler-generated | 10,752 bytes |
| Runtime Async | 5,632 bytes |
This is not a promise that a complete application will become 48% smaller. The test was intentionally dominated by small async methods. The useful conclusion is that Runtime Async can reduce the per-method IL and metadata cost.
### 3. Better exception flow through deep async chains
Classic async state machines normally contain generated exception handling so that an unhandled exception can be stored in the returned task.
In a deep chain, an exception can be:
1. Caught by generated code in the inner method.
2. Stored in its task.
3. Read and thrown again by the caller's awaiter.
4. Caught by the caller's generated code.
5. Stored in another task.
Runtime Async can move through continuation records that have no real user exception handler and fault the observable root task more directly. This can reduce repeated throw, catch, and task-fault work in deep pass-through chains.
This optimization does not make exceptions a normal or recommended control-flow mechanism. It only makes the runtime-generated path less expensive where possible.
### 4. Skipping unnecessary ExecutionContext work
`ExecutionContext` carries ambient state across async boundaries. `AsyncLocal<T>` values are a common example. Tracing and request-correlation systems can also use ambient state.
.NET 11 can detect when a continuation has no context state to restore and skip an unnecessary capture-and-restore cycle. `Task`, `Task<T>`, `ValueTask`, and `ValueTask<T>` paths can benefit.
The effect is workload-dependent. A high-throughput library path with little ambient state may benefit more than an ASP.NET Core request path that uses `Activity`, tracing, and several `AsyncLocal<T>` values.
### 5. JIT improvements for async paths
.NET 11 also improves several details around Runtime Async:
- Runtime Async methods participate in tiered compilation, so hot methods can receive Tier 1 optimizations.
- The JIT recognizes common factories such as `Task.CompletedTask`, `Task.FromResult`, and `ValueTask.FromResult`.
- Suspension points can be tail-merged to reduce generated code size.
- Some continuation objects can be cached and reused.
- Direct tail-await paths can avoid unnecessary layers.
- Runtime Async supports ReadyToRun and NativeAOT scenarios.
- ReadyToRun compilation can inline eligible await-less Runtime Async calls.
These are implementation improvements. Application code should continue to choose `Task` or `ValueTask` based on API semantics and measured needs, not because Runtime Async exists.
## A reproducible benchmark
The package includes `benchmarks/AsyncPathBenchmarks`. It compares classic and Runtime Async lowering inside the same .NET 11 process. This isolates the lowering strategy better than comparing a .NET 10 process with a .NET 11 process, where many other runtime changes would also affect the result.
The benchmark uses a compiler-recognized `RuntimeAsyncMethodGenerationAttribute` to force classic lowering for selected methods. This attribute is experimental and is **not a public .NET API**. Use it only for controlled experiments like this one.
Run it with:
```bash
dotnet run \
--project benchmarks/AsyncPathBenchmarks/AsyncPathBenchmarks.csproj \
-c Release \
--filter "*"
```
The included job performs 3 warm-up iterations and 10 measurement iterations. For serious performance work, increase the iteration count and run on a quiet, dedicated machine.
### Results from the included run
Test environment:
- Ubuntu 24.04.3 LTS.
- Intel Xeon Platinum 8573C, with 9 logical cores available to the container.
- .NET SDK `11.0.100-rc.1.26425.128`.
- .NET runtime `11.0.0-rc.1.26425.128`.
- BenchmarkDotNet `0.16.0-preview.1`.
- Release configuration and Workstation GC.
| Method | Mean | Ratio | Allocated |
|---|---:|---:|---:|
| ClassicCompleted | 84.99 ns | 1.00 | 144 B |
| RuntimeCompleted | 15.83 ns | 0.20 | 0 B |
| ClassicYielding | 678.15 ns | 1.00 | 248 B |
| RuntimeYielding | 314.50 ns | 0.46 | 168 B |
![Benchmark results from the included .NET 11 RC1 run](assets/benchmark-results.png)
These values are **not a general performance claim**. The benchmark ran in a shared container, could not raise process priority, and the `ClassicCompleted` measurements had high variance. The full BenchmarkDotNet report is included in `results/benchmark-results.md`.
The results demonstrate how to measure the feature and show clear allocation differences in this small pattern. They do not tell us how much faster an ABP application, API endpoint, or database operation will become.
Microsoft's own benchmark of the same two-layer pattern also showed lower time and allocation for Runtime Async, but with different absolute numbers. That difference is exactly why you should run the benchmark on your hardware and then measure a realistic application workload.
### Benchmark hygiene
Runtime Async is a compile-time feature. When switching the feature on and off in the same project, force a rebuild. Otherwise, an incremental build can leave an assembly from the previous configuration in the output directory.
The included scripts use `--no-incremental` for this reason.
For a fair application benchmark:
- Use Release builds.
- Pin the SDK and runtime versions.
- Record OS, CPU, GC mode, and application configuration.
- Warm up tiered compilation before recording steady-state throughput.
- Measure latency percentiles, CPU, and allocations—not only requests per second.
- Run several independent processes or test rounds.
- Compare the same commit with only the Runtime Async switch changed.
- Test with your real third-party libraries and normal observability configuration.
## Where should the difference be visible?
Runtime Async has the best opportunity in code with many small async layers:
```text
HTTP endpoint
→ application service
→ authorization helper
→ retry or policy layer
→ repository
→ database or network operation
```
Possible observable effects include:
- Fewer managed allocations per request.
- Lower GC pressure at high request rates.
- Better throughput on async-heavy CPU paths.
- Smaller application or library assemblies.
- Cleaner debugger and profiler stacks.
The difference may be difficult to see when:
- Most request time is spent waiting for a slow database or remote API.
- The async call chain is shallow.
- Tasks are stored or otherwise observed as objects.
- Much of the hot path is in older third-party assemblies compiled with classic lowering.
- Tracing, logging, or `AsyncLocal<T>` usage requires ambient context flow.
- The application is limited by database capacity, locks, serialization, or network bandwidth.
A 100-millisecond database query can easily hide a small runtime improvement in end-to-end request latency. The same improvement may still appear in allocation rate, CPU use, or maximum throughput under load.
## Investigating async behavior in production
Production async problems usually appear as one of these symptoms:
- High latency but low CPU usage.
- Thread-pool queue growth.
- Unexpected allocation or GC pressure.
- Time spent in continuations or framework infrastructure.
- A request that starts on one thread and continues on another.
The last case is especially important. When an async method suspends, its physical thread stack unwinds. The continuation can later resume on a different thread.
![Physical thread stacks compared with a logical async call chain](assets/physical-logical-async.png)
A normal sampling profiler can see the code currently running on Thread 27, but the earlier physical stack from Thread 12 is gone. An async-aware profiler needs runtime events to rebuild the logical chain.
### Start with counters
Use counters to decide whether you need a more detailed trace:
```bash
dotnet tool install --global dotnet-counters
dotnet-counters monitor --process-id <PID>
```
Watch the signals that match the symptom, such as:
- CPU usage.
- Allocation rate and GC activity.
- Thread-pool thread count.
- Thread-pool queue length.
- Exception rate.
Counters are good for detecting a problem, but they normally do not show the full logical async call chain.
### Collect a short trace
Install `dotnet-trace`:
```bash
dotnet tool install --global dotnet-trace
```
Collect a short runtime and sampled-thread trace:
```bash
dotnet-trace collect \
--process-id <PID> \
--duration 00:00:00:30 \
--profile dotnet-common,dotnet-sampled-thread-time \
--output async-investigation.nettrace
```
The exact providers should follow the question you are investigating. More events create more data and more overhead. Start narrow, record for a limited time, and reproduce one known problem window.
Open the trace in a compatible tool such as Visual Studio's performance tools or PerfView. Tool support matters: a runtime can emit new events before every analysis tool presents them in a useful async view.
### What is new for profiling in .NET 11?
Traditional Task Parallel Library events can be very verbose in async-heavy applications. .NET 11 adds a new buffered async-profiler event pipeline. Its design uses:
- Per-thread buffers.
- Compact timestamp and instruction-pointer encoding.
- Batched event flushing.
- A small wrapper frame that helps connect CPU samples to a logical async continuation.
In the runtime pull request's synthetic measurements, the new stream produced much less trace data and low overhead at realistic event rates. Treat those values as design measurements, not as a guarantee for your service. The event format is internal and can change, and analysis tools must understand it before you receive the full benefit.
Follow these production rules:
- Measure trace overhead on a staging environment first.
- Keep collection windows short.
- Avoid collecting unnecessary providers.
- Check for dropped events and increase buffers only when needed.
- Run the tool with the required process permissions.
- Protect traces because they can contain application names, paths, exception messages, and business information.
### Keep distributed tracing in the picture
Runtime stacks and CPU traces answer questions about execution cost. `Activity` and OpenTelemetry traces answer a different question: where did the request spend wall-clock time across services, databases, and external calls?
For a production investigation, use both views when possible:
- Distributed trace: request latency and service boundaries.
- Runtime trace: CPU, GC, contention, threads, and managed call stacks.
- Application logs: business context and failure details.
Together, they are more useful than any one source alone.
## Preview limitations and production readiness
Runtime Async currently supports async methods returning:
| Return type or feature | .NET 11 Runtime Async status |
|---|---|
| `Task` | Supported |
| `Task<T>` | Supported |
| `ValueTask` | Supported |
| `ValueTask<T>` | Supported |
| `async void` | Uses classic compiler transformation |
| Async iterators / `IAsyncEnumerable<T>` | Uses classic compiler transformation |
| Custom task-like types and custom builders | Use classic compiler transformation |
Runtime Async is compatible with existing assemblies. New code can await libraries compiled with the classic model, and classic code can call Runtime Async methods. However, the largest optimization opportunities appear when more of a direct async call chain uses Runtime Async.
The important readiness facts are:
- .NET 11 is RC1 at the time of writing, not the final release.
- Runtime Async remains preview and opt-in for application code.
- Microsoft describes the .NET 11 performance goal as broad parity with .NET 10, not a universal speedup.
- Important paths are already equal or faster, but known slower cases still exist.
- Tooling support for new profiling data can arrive at different times.
- Performance results can change between RC1, the final release, and servicing updates.
For production, do not enable the feature only because a microbenchmark is faster. Test compatibility, performance, diagnostics, startup, publishing, and rollback in the same deployment model you use for the real application.
## Conclusion
Runtime Async is one of the most important runtime changes in .NET 11, even though it does not add new C# syntax.
It moves more async implementation work into the runtime and JIT, where .NET has better information for optimization. The most immediate improvement is easier debugging through cleaner live stacks. The longer-term opportunity is reducing the hidden cost of composing many small async methods.
The feature is also a good reminder about performance work: architecture creates an opportunity, but measurement tells us whether that opportunity matters in our application.
Keep writing clear async code. Use `Task` and `ValueTask` according to their API trade-offs. Then benchmark the application, inspect its traces, and let evidence decide when Runtime Async is ready for your production workload.
## References
- [What's new in .NET 11](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/overview)
- [What's new in the .NET 11 runtime](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/runtime)
- [Performance Improvements in .NET 11 — Stephen Toub](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-11/)
- [High-performance EventSource runtime async profiler — dotnet/runtime PR #127238](https://github.com/dotnet/runtime/pull/127238)
- [dotnet-trace documentation](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace)
- [dotnet-counters documentation](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters)
- [dotnet-monitor documentation](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-monitor)

7
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/ASSET-LICENSE.md

@ -0,0 +1,7 @@
# Visual asset license
All diagrams and charts in this folder were created specifically for this article package. They are licensed under the Creative Commons Attribution 4.0 International license (CC BY 4.0), with attribution to Mansur Besleney.
License text: https://creativecommons.org/licenses/by/4.0/
The benchmark chart uses measurements produced by the runnable benchmark included in this package. It does not reproduce a third-party image.

BIN
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/benchmark-results.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

33
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/benchmark-results.svg

@ -0,0 +1,33 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="980" viewBox="0 0 1600 980" role="img" aria-labelledby="title desc">
<title id="title">Runtime Async benchmark results from the included sample</title>
<desc id="desc">On .NET 11 RC1, the included two-layer benchmark measured classic and Runtime Async completed paths at 84.99 and 15.83 nanoseconds, and yielding paths at 678.15 and 314.50 nanoseconds. Allocations were 144 versus 0 bytes and 248 versus 168 bytes.</desc>
<defs><style>
.bg{fill:#f7f9fc}.panel{fill:#fff;stroke:#d9e1ec;stroke-width:2}.title{font:700 35px Arial,sans-serif;fill:#172033}.sub{font:400 20px Arial,sans-serif;fill:#5d6a7f}.head{font:700 25px Arial,sans-serif;fill:#172033}.axis{stroke:#aeb9c8;stroke-width:2}.classic{fill:#e97451}.runtime{fill:#3487d5}.label{font:400 19px Arial,sans-serif;fill:#334158}.value{font:700 19px Arial,sans-serif;fill:#172033}.legend{font:700 20px Arial,sans-serif;fill:#243248}.foot{font:400 18px Arial,sans-serif;fill:#637188}
</style></defs>
<rect class="bg" width="1600" height="980"/>
<text class="title" x="800" y="58" text-anchor="middle">Included microbenchmark: time and managed allocation</text>
<text class="sub" x="800" y="96" text-anchor="middle">.NET 11 RC1 · Release · two async layers · shared Linux test host</text>
<rect class="classic" x="590" y="120" width="24" height="24" rx="4"/><text class="legend" x="625" y="140">Classic</text><rect class="runtime" x="790" y="120" width="24" height="24" rx="4"/><text class="legend" x="825" y="140">Runtime Async</text>
<rect class="panel" x="70" y="180" width="700" height="330" rx="18"/><text class="head" x="110" y="225">Synchronously completed path — mean time</text><text class="sub" x="110" y="258">Lower is better · scale: 0–100 ns</text>
<text class="label" x="110" y="325">Classic</text><rect class="classic" x="250" y="294" width="424" height="44" rx="7"/><text class="value" x="690" y="323">84.99 ns</text>
<text class="label" x="110" y="398">Runtime</text><rect class="runtime" x="250" y="367" width="79" height="44" rx="7"/><text class="value" x="345" y="396">15.83 ns</text>
<line class="axis" x1="250" y1="445" x2="700" y2="445"/><text class="sub" x="250" y="475">0</text><text class="sub" x="700" y="475" text-anchor="end">100 ns</text>
<rect class="panel" x="830" y="180" width="700" height="330" rx="18"/><text class="head" x="870" y="225">Synchronously completed path — allocation</text><text class="sub" x="870" y="258">Lower is better · scale: 0–160 B</text>
<text class="label" x="870" y="325">Classic</text><rect class="classic" x="1010" y="294" width="405" height="44" rx="7"/><text class="value" x="1430" y="323">144 B</text>
<text class="label" x="870" y="398">Runtime</text><rect class="runtime" x="1010" y="367" width="4" height="44" rx="2"/><text class="value" x="1030" y="396">0 B</text>
<line class="axis" x1="1010" y1="445" x2="1460" y2="445"/><text class="sub" x="1010" y="475">0</text><text class="sub" x="1460" y="475" text-anchor="end">160 B</text>
<rect class="panel" x="70" y="550" width="700" height="330" rx="18"/><text class="head" x="110" y="595">Path with Task.Yield — mean time</text><text class="sub" x="110" y="628">Lower is better · scale: 0–750 ns</text>
<text class="label" x="110" y="695">Classic</text><rect class="classic" x="250" y="664" width="407" height="44" rx="7"/><text class="value" x="673" y="693">678.15 ns</text>
<text class="label" x="110" y="768">Runtime</text><rect class="runtime" x="250" y="737" width="189" height="44" rx="7"/><text class="value" x="455" y="766">314.50 ns</text>
<line class="axis" x1="250" y1="815" x2="700" y2="815"/><text class="sub" x="250" y="845">0</text><text class="sub" x="700" y="845" text-anchor="end">750 ns</text>
<rect class="panel" x="830" y="550" width="700" height="330" rx="18"/><text class="head" x="870" y="595">Path with Task.Yield — allocation</text><text class="sub" x="870" y="628">Lower is better · scale: 0–280 B</text>
<text class="label" x="870" y="695">Classic</text><rect class="classic" x="1010" y="664" width="399" height="44" rx="7"/><text class="value" x="1425" y="693">248 B</text>
<text class="label" x="870" y="768">Runtime</text><rect class="runtime" x="1010" y="737" width="270" height="44" rx="7"/><text class="value" x="1296" y="766">168 B</text>
<line class="axis" x1="1010" y1="815" x2="1460" y2="815"/><text class="sub" x="1010" y="845">0</text><text class="sub" x="1460" y="845" text-anchor="end">280 B</text>
<text class="foot" x="800" y="925" text-anchor="middle">Microbenchmark results vary by hardware and runtime build. Re-run the included project on your target environment.</text>
<text class="foot" x="800" y="952" text-anchor="middle">The classic and Runtime Async methods ran in the same .NET 11 process to isolate the lowering strategy.</text>
</svg>

After

Width:  |  Height:  |  Size: 4.8 KiB

BIN
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/live-stack-comparison.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

38
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/live-stack-comparison.svg

@ -0,0 +1,38 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="980" viewBox="0 0 1600 980" role="img" aria-labelledby="title desc">
<title id="title">Live stack trace comparison</title>
<desc id="desc">Classic lowering displays 13 live stack frames including async infrastructure. Runtime Async displays 5 application frames for the same program.</desc>
<defs><style>
.bg{fill:#f7f9fc}.box{fill:#fff;stroke:#d7dfeb;stroke-width:2}.title{font:700 35px Arial,sans-serif;fill:#172033}.sub{font:400 21px Arial,sans-serif;fill:#5b687d}.head{font:700 26px Arial,sans-serif;fill:#172033}.code{font:400 18px Consolas,'Liberation Mono',monospace;fill:#243248}.plumb{font:400 18px Consolas,'Liberation Mono',monospace;fill:#b14a3b}.appbg{fill:#eaf5ff}.plumbbg{fill:#fff0ed}.pillA{fill:#e97451}.pillB{fill:#3487d5}.pill{font:700 18px Arial,sans-serif;fill:#fff}.note{font:700 21px Arial,sans-serif;fill:#22643d}
</style></defs>
<rect class="bg" width="1600" height="980"/>
<text class="title" x="800" y="58" text-anchor="middle">The same code, a much cleaner live stack</text>
<text class="sub" x="800" y="96" text-anchor="middle">Measured with .NET 11 RC1 and new StackTrace(fNeedFileInfo: true)</text>
<rect class="box" x="60" y="135" width="720" height="760" rx="18"/>
<rect class="box" x="820" y="135" width="720" height="760" rx="18"/>
<text class="head" x="100" y="185">Classic lowering</text><rect class="pillA" x="620" y="155" width="115" height="42" rx="21"/><text class="pill" x="677" y="183" text-anchor="middle">13 frames</text>
<text class="head" x="860" y="185">Runtime Async</text><rect class="pillB" x="1380" y="155" width="115" height="42" rx="21"/><text class="pill" x="1437" y="183" text-anchor="middle">5 frames</text>
<rect class="appbg" x="90" y="222" width="660" height="38" rx="6"/><text class="code" x="108" y="248">InnerAsync() : line 24</text>
<rect class="plumbbg" x="90" y="270" width="660" height="38" rx="6"/><text class="plumb" x="108" y="296">AsyncMethodBuilderCore.Start(...)</text>
<rect class="plumbbg" x="90" y="318" width="660" height="38" rx="6"/><text class="plumb" x="108" y="344">InnerAsync() infrastructure entry</text>
<rect class="appbg" x="90" y="366" width="660" height="38" rx="6"/><text class="code" x="108" y="392">MiddleAsync() : line 18</text>
<rect class="plumbbg" x="90" y="414" width="660" height="38" rx="6"/><text class="plumb" x="108" y="440">AsyncMethodBuilderCore.Start(...)</text>
<rect class="plumbbg" x="90" y="462" width="660" height="38" rx="6"/><text class="plumb" x="108" y="488">MiddleAsync() infrastructure entry</text>
<rect class="appbg" x="90" y="510" width="660" height="38" rx="6"/><text class="code" x="108" y="536">OuterAsync() : line 12</text>
<rect class="plumbbg" x="90" y="558" width="660" height="38" rx="6"/><text class="plumb" x="108" y="584">AsyncMethodBuilderCore.Start(...)</text>
<rect class="plumbbg" x="90" y="606" width="660" height="38" rx="6"/><text class="plumb" x="108" y="632">OuterAsync() infrastructure entry</text>
<rect class="appbg" x="90" y="654" width="660" height="38" rx="6"/><text class="code" x="108" y="680">Main() : line 7</text>
<rect class="plumbbg" x="90" y="702" width="660" height="38" rx="6"/><text class="plumb" x="108" y="728">AsyncMethodBuilderCore.Start(...)</text>
<rect class="plumbbg" x="90" y="750" width="660" height="38" rx="6"/><text class="plumb" x="108" y="776">Main() infrastructure entry</text>
<rect class="appbg" x="90" y="798" width="660" height="38" rx="6"/><text class="code" x="108" y="824">Main(string[] args)</text>
<rect class="appbg" x="850" y="222" width="660" height="68" rx="8"/><text class="code" x="878" y="263">InnerAsync() : line 24</text>
<rect class="appbg" x="850" y="310" width="660" height="68" rx="8"/><text class="code" x="878" y="351">MiddleAsync() : line 18</text>
<rect class="appbg" x="850" y="398" width="660" height="68" rx="8"/><text class="code" x="878" y="439">OuterAsync() : line 12</text>
<rect class="appbg" x="850" y="486" width="660" height="68" rx="8"/><text class="code" x="878" y="527">Main() : line 7</text>
<rect class="appbg" x="850" y="574" width="660" height="68" rx="8"/><text class="code" x="878" y="615">Main(string[] args)</text>
<text class="note" x="1180" y="727" text-anchor="middle">The application call chain is visible directly.</text>
<text class="sub" x="1180" y="768" text-anchor="middle">Useful in debugger call stacks, live diagnostic</text>
<text class="sub" x="1180" y="801" text-anchor="middle">logging, and supported profiling tools.</text>
<text class="sub" x="800" y="942" text-anchor="middle">This comparison is about live stacks. Caught exception stack traces were already cleaned up by the existing async infrastructure.</text>
</svg>

After

Width:  |  Height:  |  Size: 4.7 KiB

BIN
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/physical-logical-async.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

20
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/physical-logical-async.svg

@ -0,0 +1,20 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
<title id="title">Physical threads and the logical async call chain</title>
<desc id="desc">An async operation starts on thread 12, suspends for I/O, and resumes on thread 27. The logical request chain crosses both physical stacks, which is why async-aware profiling is needed.</desc>
<defs><style>
.bg{fill:#f7f9fc}.title{font:700 35px Arial,sans-serif;fill:#172033}.sub{font:400 21px Arial,sans-serif;fill:#5d6a7f}.lane{stroke:#b7c1d0;stroke-width:3}.thread{font:700 24px Arial,sans-serif;fill:#243248}.block{fill:#eaf5ff;stroke:#3487d5;stroke-width:3}.io{fill:#fff8df;stroke:#d7a928;stroke-width:3}.resume{fill:#eaf8ef;stroke:#35a663;stroke-width:3}.txt{font:700 20px Arial,sans-serif;fill:#243248}.small{font:400 18px Arial,sans-serif;fill:#44536a}.logical{stroke:#8a55c5;stroke-width:6;stroke-dasharray:12 9;fill:none;marker-end:url(#p)}.event{stroke:#8290a6;stroke-width:3;fill:none;marker-end:url(#a)}.legend{fill:#fff;stroke:#d9e1ec;stroke-width:2}
</style><marker id="a" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 z" fill="#8290a6"/></marker><marker id="p" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 z" fill="#8a55c5"/></marker></defs>
<rect class="bg" width="1600" height="900"/>
<text class="title" x="800" y="58" text-anchor="middle">A logical async operation can cross physical threads</text>
<text class="sub" x="800" y="96" text-anchor="middle">A normal CPU stack sees the current thread; an async-aware profiler reconstructs the request story.</text>
<text class="thread" x="80" y="210">Thread 12</text><line class="lane" x1="230" y1="202" x2="1510" y2="202"/>
<text class="thread" x="80" y="430">I/O</text><line class="lane" x1="230" y1="422" x2="1510" y2="422"/>
<text class="thread" x="80" y="650">Thread 27</text><line class="lane" x1="230" y1="642" x2="1510" y2="642"/>
<rect class="block" x="290" y="155" width="360" height="94" rx="14"/><text class="txt" x="470" y="193" text-anchor="middle">Request → service → repository</text><text class="small" x="470" y="225" text-anchor="middle">Physical stack exists on Thread 12</text>
<path class="event" d="M650 202 C720 202 720 422 800 422"/>
<rect class="io" x="800" y="375" width="310" height="94" rx="14"/><text class="txt" x="955" y="413" text-anchor="middle">Socket or database wait</text><text class="small" x="955" y="445" text-anchor="middle">Thread 12 is free to do other work</text>
<path class="event" d="M1110 422 C1190 422 1190 642 1260 642"/>
<rect class="resume" x="1210" y="595" width="300" height="94" rx="14"/><text class="txt" x="1360" y="633" text-anchor="middle">Continuation resumes</text><text class="small" x="1360" y="665" text-anchor="middle">Physical stack is now on Thread 27</text>
<path class="logical" d="M310 285 C560 340 760 535 1250 555"/>
<rect class="legend" x="330" y="730" width="940" height="110" rx="16"/><line class="logical" x1="380" y1="775" x2="540" y2="775"/><text class="txt" x="575" y="783">Logical async call chain</text><text class="small" x="575" y="816">It connects work that no longer shares one physical thread stack.</text>
</svg>

After

Width:  |  Height:  |  Size: 3.2 KiB

BIN
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/runtime-async-architecture.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

43
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/runtime-async-architecture.svg

@ -0,0 +1,43 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
<title id="title">Classic async lowering compared with .NET 11 Runtime Async</title>
<desc id="desc">The classic model creates a compiler-generated state machine before the runtime sees the method. Runtime Async emits compact async-aware IL and lets the runtime and JIT perform the lowering.</desc>
<defs>
<style>
.bg{fill:#f7f9fc}.panel{fill:#fff;stroke:#d9e1ec;stroke-width:2}.head{font:700 34px Arial,sans-serif;fill:#172033}.sub{font:400 22px Arial,sans-serif;fill:#58657a}.label{font:700 25px Arial,sans-serif;fill:#172033}.body{font:400 21px Arial,sans-serif;fill:#334158}.classic{fill:#fff2e8;stroke:#ee8a3b;stroke-width:3}.runtime{fill:#eaf5ff;stroke:#3487d5;stroke-width:3}.good{fill:#eaf8ef;stroke:#35a663;stroke-width:3}.arrow{stroke:#8290a6;stroke-width:4;fill:none;marker-end:url(#arrow)}.badge{font:700 18px Arial,sans-serif;fill:#fff}.foot{font:400 19px Arial,sans-serif;fill:#66748a}
</style>
<marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 z" fill="#8290a6"/></marker>
</defs>
<rect class="bg" width="1600" height="900"/>
<text class="head" x="800" y="62" text-anchor="middle">Who lowers an async method?</text>
<text class="sub" x="800" y="100" text-anchor="middle">The C# syntax stays the same; the implementation responsibility moves.</text>
<rect class="panel" x="70" y="140" width="700" height="680" rx="22"/>
<rect class="classic" x="120" y="180" width="600" height="80" rx="16"/>
<text class="label" x="420" y="229" text-anchor="middle">.NET 10-style compiler lowering</text>
<rect class="classic" x="185" y="315" width="470" height="76" rx="14"/>
<text class="body" x="420" y="361" text-anchor="middle">C# async method</text>
<path class="arrow" d="M420 392 L420 440"/>
<rect class="classic" x="185" y="450" width="470" height="126" rx="14"/>
<text class="label" x="420" y="493" text-anchor="middle">C# compiler</text>
<text class="body" x="420" y="533" text-anchor="middle">Performs the full transformation</text>
<path class="arrow" d="M420 578 L420 626"/>
<rect class="classic" x="130" y="636" width="580" height="118" rx="14"/>
<text class="body" x="420" y="678" text-anchor="middle">Generated type + MoveNext()</text>
<text class="body" x="420" y="715" text-anchor="middle">builder + saved fields + Task boundary</text>
<rect class="panel" x="830" y="140" width="700" height="680" rx="22"/>
<rect class="runtime" x="880" y="180" width="600" height="80" rx="16"/>
<text class="label" x="1180" y="229" text-anchor="middle">.NET 11 Runtime Async</text>
<rect class="runtime" x="945" y="315" width="470" height="76" rx="14"/>
<text class="body" x="1180" y="361" text-anchor="middle">The same C# async method</text>
<path class="arrow" d="M1180 392 L1180 440"/>
<rect class="runtime" x="945" y="450" width="470" height="126" rx="14"/>
<text class="label" x="1180" y="493" text-anchor="middle">C# compiler</text>
<text class="body" x="1180" y="533" text-anchor="middle">Emits compact async-aware IL</text>
<path class="arrow" d="M1180 578 L1180 626"/>
<rect class="good" x="890" y="636" width="580" height="118" rx="14"/>
<text class="body" x="1180" y="678" text-anchor="middle">Runtime + JIT manage suspension</text>
<text class="body" x="1180" y="715" text-anchor="middle">and materialize Tasks only when needed</text>
<text class="foot" x="800" y="864" text-anchor="middle">Runtime Async is an implementation change—not a new async/await programming model.</text>
</svg>

After

Width:  |  Height:  |  Size: 3.6 KiB

BIN
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/task-materialization.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

29
docs/en/Community-Articles/2026-09-21-DotNET-11-Runtime-Async-Cleaner-Stack-Traces-and-Faster-Async-Paths/assets/task-materialization.svg

@ -0,0 +1,29 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="880" viewBox="0 0 1600 880" role="img" aria-labelledby="title desc">
<title id="title">Intermediate Task materialization</title>
<desc id="desc">Classic lowering has observable task-like boundaries at each async layer. Runtime Async can link continuations and create a Task only at an observable boundary, when semantics allow it.</desc>
<defs><style>
.bg{fill:#f7f9fc}.panel{fill:#fff;stroke:#d9e1ec;stroke-width:2}.title{font:700 35px Arial,sans-serif;fill:#172033}.sub{font:400 21px Arial,sans-serif;fill:#5d6a7f}.head{font:700 27px Arial,sans-serif;fill:#172033}.method{fill:#eaf5ff;stroke:#3487d5;stroke-width:3}.task{fill:#fff0ed;stroke:#e97451;stroke-width:3}.cont{fill:#eaf8ef;stroke:#35a663;stroke-width:3}.txt{font:700 22px Arial,sans-serif;fill:#243248}.small{font:400 19px Arial,sans-serif;fill:#425169}.arrow{stroke:#8290a6;stroke-width:4;fill:none;marker-end:url(#a)}.dash{stroke:#35a663;stroke-width:4;stroke-dasharray:10 8;fill:none;marker-end:url(#g)}.note{fill:#fff8df;stroke:#d7a928;stroke-width:2}
</style><marker id="a" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 z" fill="#8290a6"/></marker><marker id="g" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"><path d="M0,0 L12,6 L0,12 z" fill="#35a663"/></marker></defs>
<rect class="bg" width="1600" height="880"/>
<text class="title" x="800" y="58" text-anchor="middle">Runtime Async can avoid some intermediate Task objects</text>
<text class="sub" x="800" y="96" text-anchor="middle">Example: A() directly awaits B(), and B() directly awaits C().</text>
<rect class="panel" x="60" y="140" width="720" height="620" rx="20"/><text class="head" x="420" y="190" text-anchor="middle">Classic lowering</text>
<rect class="method" x="115" y="240" width="180" height="75" rx="14"/><text class="txt" x="205" y="286" text-anchor="middle">A()</text>
<rect class="task" x="430" y="240" width="230" height="75" rx="14"/><text class="txt" x="545" y="286" text-anchor="middle">Task A</text><path class="arrow" d="M300 277 L420 277"/>
<rect class="method" x="115" y="370" width="180" height="75" rx="14"/><text class="txt" x="205" y="416" text-anchor="middle">B()</text>
<rect class="task" x="430" y="370" width="230" height="75" rx="14"/><text class="txt" x="545" y="416" text-anchor="middle">Task B</text><path class="arrow" d="M300 407 L420 407"/>
<rect class="method" x="115" y="500" width="180" height="75" rx="14"/><text class="txt" x="205" y="546" text-anchor="middle">C()</text>
<rect class="task" x="430" y="500" width="230" height="75" rx="14"/><text class="txt" x="545" y="546" text-anchor="middle">Task C</text><path class="arrow" d="M300 537 L420 537"/>
<path class="arrow" d="M205 320 L205 360"/><path class="arrow" d="M205 450 L205 490"/>
<text class="small" x="420" y="650" text-anchor="middle">Each layer has its own transformed state and task-like result.</text>
<rect class="panel" x="820" y="140" width="720" height="620" rx="20"/><text class="head" x="1180" y="190" text-anchor="middle">Runtime Async, when the boundary is not observed</text>
<rect class="method" x="875" y="240" width="180" height="75" rx="14"/><text class="txt" x="965" y="286" text-anchor="middle">A()</text>
<rect class="method" x="875" y="370" width="180" height="75" rx="14"/><text class="txt" x="965" y="416" text-anchor="middle">B()</text>
<rect class="method" x="875" y="500" width="180" height="75" rx="14"/><text class="txt" x="965" y="546" text-anchor="middle">C()</text>
<path class="dash" d="M965 320 L965 360"/><path class="dash" d="M965 450 L965 490"/>
<rect class="cont" x="1160" y="330" width="285" height="155" rx="16"/><text class="txt" x="1302" y="383" text-anchor="middle">Linked continuation</text><text class="small" x="1302" y="420" text-anchor="middle">No intermediate Task</text><text class="small" x="1302" y="450" text-anchor="middle">is required here</text>
<rect class="task" x="1160" y="535" width="285" height="75" rx="14"/><text class="txt" x="1302" y="581" text-anchor="middle">Observable root Task</text><path class="arrow" d="M1302 490 L1302 525"/>
<rect class="note" x="865" y="650" width="630" height="70" rx="12"/><text class="small" x="1180" y="680" text-anchor="middle">If code stores, inspects, or manually continues a Task,</text><text class="small" x="1180" y="707" text-anchor="middle">the Task remains observable and must still exist.</text>
<text class="sub" x="800" y="830" text-anchor="middle">This is an optimization opportunity, not a promise that every asynchronous operation becomes allocation-free.</text>
</svg>

After

Width:  |  Height:  |  Size: 4.6 KiB

BIN
docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/anyof_union_openapi.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.8 KiB

BIN
docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/api_contract_flow.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 154 KiB

BIN
docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/article-cover-image.jpeg

Binary file not shown.

After

Width:  |  Height:  |  Size: 129 KiB

BIN
docs/en/Community-Articles/2026-09-21-system-text-json-in-net11-naming-policies-union-types-ndjson-streaming/ndjson_screenshot.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Some files were not shown because too many files changed in this diff

Loading…
Cancel
Save