mirror of https://github.com/abpframework/abp.git
Mark Cilia Vincenti
9 months ago
committed by
GitHub
GitHub
419 changed files with 7865 additions and 2582 deletions
@ -0,0 +1,89 @@ |
|||
# ABP.IO Platform 10.0 Final Has Been Released! |
|||
|
|||
We are glad to announce that [ABP](https://abp.io/) 10.0 stable version has been released today. |
|||
|
|||
## What's New With Version 10.0? |
|||
|
|||
All the new features were explained in detail in the [10.0 RC Announcement Post](https://abp.io/community/announcements/announcing-abp-10-0-release-candidate-86lrnyox), so there is no need to review them again. You can check it out for more details. |
|||
|
|||
## Getting Started with 10.0 |
|||
|
|||
### How to Upgrade an Existing Solution |
|||
|
|||
You can upgrade your existing solutions with either ABP Studio or ABP CLI. In the following sections, both approaches are explained: |
|||
|
|||
### Upgrading via ABP Studio |
|||
|
|||
If you are already using the ABP Studio, you can upgrade it to the latest version. ABP Studio periodically checks for updates in the background, and when a new version of ABP Studio is available, you will be notified through a modal. Then, you can update it by confirming the opened modal. See [the documentation](https://abp.io/docs/latest/studio/installation#upgrading) for more info. |
|||
|
|||
After upgrading the ABP Studio, then you can open your solution in the application, and simply click the **Upgrade ABP Packages** action button to instantly upgrade your solution: |
|||
|
|||
 |
|||
|
|||
### Upgrading via ABP CLI |
|||
|
|||
Alternatively, you can upgrade your existing solution via ABP CLI. First, you need to install the ABP CLI or upgrade it to the latest version. |
|||
|
|||
If you haven't installed it yet, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
Or to update the existing CLI, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool update -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
After installing/updating the ABP CLI, you can use the [`update` command](https://abp.io/docs/latest/CLI#update) to update all the ABP related NuGet and NPM packages in your solution as follows: |
|||
|
|||
```bash |
|||
abp update |
|||
``` |
|||
|
|||
You can run this command in the root folder of your solution to update all ABP related packages. |
|||
|
|||
## Migration Guides |
|||
|
|||
There are a few breaking changes in this version that may affect your application. Please read the migration guide carefully, if you are upgrading from v9.x: [ABP Version 10.0 Migration Guide](https://abp.io/docs/10.0/release-info/migration-guides/abp-10-0) |
|||
|
|||
## Community News |
|||
|
|||
### New ABP Community Articles |
|||
|
|||
As always, exciting articles have been contributed by the ABP community. I will highlight some of them here: |
|||
|
|||
* [Alper Ebiçoğlu](https://abp.io/community/members/alper) |
|||
* [Optimize your .NET app for production Part 1](https://abp.io/community/articles/optimize-your-dotnet-app-for-production-for-any-.net-app-wa24j28e) |
|||
* [Optimize your .NET app for production Part 2](https://abp.io/community/articles/optimize-your-dotnet-app-for-production-for-any-.net-app-2-78xgncpi) |
|||
* [Return Code vs Exceptions: Which One is Better?](https://abp.io/community/articles/return-code-vs-exceptions-which-one-is-better-1rwcu9yi) |
|||
* [Sumeyye Kurtulus](https://abp.io/community/members/sumeyye.kurtulus) |
|||
* [Building Scalable Angular Apps with Reusable UI Components](https://abp.io/community/articles/building-scalable-angular-apps-with-reusable-ui-components-b9npiff3) |
|||
* [Angular Library Linking Made Easy: Paths, Workspaces and Symlinks](https://abp.io/community/articles/angular-library-linking-made-easy-paths-workspaces-and-5z2ate6e) |
|||
* [erdem çaygör](https://abp.io/community/members/erdem.caygor) |
|||
* [Building Dynamic Forms in Angular for Enterprise](https://abp.io/community/articles/building-dynamic-forms-in-angular-for-enterprise-6r3ewpxt) |
|||
* [From Server to Browser: Angular TransferState Explained](https://abp.io/community/articles/from-server-to-browser-angular-transferstate-explained-m99zf8oh) |
|||
* [Mansur Besleney](https://abp.io/community/members/mansur.besleney) |
|||
* [Top 10 Exception Handling Mistakes in .NET](https://abp.io/community/articles/top-10-exception-handling-mistakes-in-net-jhm8wzvg) |
|||
* [Berkan Şaşmaz](https://abp.io/community/members/berkansasmaz) |
|||
* [How to Dynamically Set the Connection String in EF Core](https://abp.io/community/articles/how-to-dynamically-set-the-connection-string-in-ef-core-30k87fpj) |
|||
* [Oğuzhan Ağır](https://abp.io/community/members/oguzhan.agir) |
|||
* [The ASP.NET Core Dependency Injection System](https://abp.io/community/articles/the-asp.net-core-dependency-injection-system-3vbsdhq8) |
|||
* [Selman Koç](https://abp.io/community/members/selmankoc) |
|||
* [5 Things Keep in Mind When Deploying Clustered Environment](https://abp.io/community/articles/5-things-keep-in-mind-when-deploying-clustered-environment-i9byusnv) |
|||
* [Muhammet Ali ÖZKAYA](https://abp.io/community/members/m.aliozkaya) |
|||
* [Repository Pattern in ASP.NET Core](https://abp.io/community/articles/repository-pattern-in-asp.net-core-2dudlg3j) |
|||
* [Armağan Ünlü](https://abp.io/community/members/armagan) |
|||
* [UI/UX Trends That Will Shape 2026](https://abp.io/community/articles/UI-UX-Trends-That-Will-Shape-2026-bx4c2kow) |
|||
* [Salih](https://abp.io/community/members/salih) |
|||
* [What is That Domain Service in DDD for .NET Developers?](https://abp.io/community/articles/what-is-that-domain-service-in-ddd-for-.net-developers-uqnpwjja) |
|||
* [Building an API Key Management System with ABP Framework](https://abp.io/community/articles/building-an-api-key-management-system-with-abp-framework-28gn4efw) |
|||
* [Fahri Gedik](https://abp.io/community/members/fahrigedik) |
|||
* [Signal-Based Forms in Angular](https://abp.io/community/articles/signal-based-forms-in-angular-21-9qentsqs) |
|||
|
|||
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. |
|||
|
|||
## About the Next Version |
|||
|
|||
The next feature version will be 10.1. You can follow the [release planning here](https://github.com/abpframework/abp/milestones). Please [submit an issue](https://github.com/abpframework/abp/issues/new) if you have any problems with this version. |
|||
|
After Width: | Height: | Size: 127 KiB |
|
After Width: | Height: | Size: 16 KiB |
@ -0,0 +1,25 @@ |
|||
**ABP Black Friday Deals are Almost Here\!** |
|||
|
|||
The season of huge savings is back\! We are happy to announce **ABP Black Friday Campaign**, packed with exclusive deals that you simply won't want to miss. Whether you are ready to start building with ABP or looking to expand your existing license, this is your chance to maximize your savings\! |
|||
|
|||
**Campaign Dates: Mark Your Calendar** |
|||
|
|||
Black Friday campaign is live for one week only\! Our deals run from: **November 24th \- December 1st.** |
|||
|
|||
Don't miss this limited-time opportunity to **save up to $3,000** and take your software development to the next level. |
|||
|
|||
**What's Included in the ABP Black Friday Campaign?** |
|||
|
|||
Here’s why this campaign is the best time to buy or upgrade: |
|||
|
|||
* Open to Everyone: This campaign is available for both new and existing customers. |
|||
* Stack Your Savings: You can combine this Black Friday offer with our multi-year discounts for the greatest possible value. |
|||
* Flexible Upgrades: Planning to upgrade to a higher package? Now is the perfect time to make that move at a lower cost. |
|||
* More Developer Seats? No Problem\! Additional developer seats are also eligible under this campaign, allowing you to grow your team effortlessly and affordably. |
|||
|
|||
**Save Money Now\!** |
|||
|
|||
This campaign is your best opportunity all year to unlock advanced features, scale your team, or upgrade your plan while **saving up to $3,000.** Secure your savings before the campaign ends on December 1st\! |
|||
|
|||
[**Visit Pricing Page to Explore Offers\!**](https://abp.io/pricing) |
|||
|
|||
@ -0,0 +1,158 @@ |
|||
# My First Look and Experience with Google AntiGravity |
|||
|
|||
## Is Google AntiGravity Going to Replace Your Main Code Editor? |
|||
|
|||
Today, I tried the new code-editor AntiGravity by Google. *"It's beyond a code-editor*" by Google 🙄 |
|||
When I first launch it, I see the UI is almost same as Cursor. They're both based on Visual Studio Code. |
|||
That's why it was not hard to find what I'm looking for. |
|||
|
|||
First of all, the main difference as I see from the Cursor is; when I type a prompt in the agent section **AntiGravity first creates a Task List** (like a road-map) and whenever it finishes a task, it checks the corresponding task. Actually Cursor has a similar functionality but AntiGravity took it one step further. |
|||
|
|||
Second thing which was good to me; AntiGravity uses [Nano Banana 🍌](https://gemini.google/tr/overview/image-generation/). This is Google's AI image generation model... Why it's important because when you create an app, you don't need to search for graphics, deal with image licenses. **AntiGravity generates images automatically and no license is required!** |
|||
|
|||
Third exciting feature for me; **AntiGravity is integrated with Google Chrome and can communicate with the running website**. When I first run my web project, it installed a browser extension which can see and interact with my website. It can see the results, click somewhere else on the page, scroll, fill up the forms, amazing 😵 |
|||
|
|||
Another feature I loved is that **you can enter a new prompt even while AntiGravity is still generating a response** 🧐. It instantly prioritizes the latest input and adjusts the ongoing process if needed. But in Cursor, if you add a prompt before the cursor finishes, it simply queues it and runs it later 😔. |
|||
|
|||
And lastly, **AntiGravity is working very good with Gemini 3**. |
|||
|
|||
Well, everything was not so perfect 😥 When I tried AntiGravity, couple of times it stucked AI generation and Agent stopped. I faced errors like this 👇 |
|||
|
|||
 |
|||
|
|||
|
|||
|
|||
## Debugging .NET Projects via AntiGravity |
|||
|
|||
⚠ There's a crucial development issue with AntiGravity (and also for Cursor, Windsurf etc...) 🤕 you **cannot debug your .NET application with AntiGravity 🥺.** *This is Microsoft's policy!* Microsoft doesn't allow debugging for 3rd party IDEs and shows the below error... That's why I cannot say it's a downside of AntiGravity. You need to use Microsft's original VS Code, Visual Studio or Rider for debugging. But wait a while there's a workaround for this, I'll let you know in the next section. |
|||
|
|||
|
|||
|
|||
 |
|||
|
|||
### What does this error mean? |
|||
|
|||
AntiGravity, Cursor, Windsurf etc... are using Visual Studio Code and the C# extension for VS Code includes the Microsoft .NET Core Debugger "*vsdbg*". |
|||
VS Code is open-source but "*vsdbg*" is not open-source! It's working only with Visual Studio Code, Visual Studio and Visual Studio for Mac. This is clearly stated at [Microsoft's this link](https://github.com/dotnet/vscode-csharp/blob/main/docs/debugger/Microsoft-.NET-Core-Debugger-licensing-and-Microsoft-Visual-Studio-Code.md). |
|||
|
|||
### Ok! How to resolve debugging issue with AntiGravity? and Cursor and Windsurf... |
|||
|
|||
There's a free C# debugger extension for Visual Studio Code based IDEs that supports AntiGravity, Cursor and Windsurf. The extension name is **C#**. |
|||
You can download this free C# debugger extension at 👉 [open-vsx.org/extension/muhammad-sammy/csharp/](https://open-vsx.org/extension/muhammad-sammy/csharp/). |
|||
For AntiGravity open Extension window (*Ctrl + Shift + X*) and search for `C#`, there you'll see this extension. |
|||
|
|||
 |
|||
|
|||
After installing, I restarted AntiGravity and now I can see the red circle which allows me to add breakpoint on C# code. |
|||
|
|||
 |
|||
|
|||
### Another Extension For Debugging .NET Apps on VS Code |
|||
|
|||
Recently I heard about DotRush extension from the folks. As they say DotRush works slightly faster and support Razor pages (.cshtml files). |
|||
Here's the link for DotRush https://github.com/JaneySprings/DotRush |
|||
|
|||
### Finding Website Running Port |
|||
|
|||
When you run the web project via C# debugger extension, normally it's not using the `launch.json` therefore the website port is not the one when you start from Visual Studio / Rider... So what's my website's port which I just run now? Normally for ASP.NET Core **the default port is 5000**. You can try navigating to http://localhost:5000/. |
|||
Alternatively you can write the below code in `Program.cs` which prints the full address of your website in the logs. |
|||
If you do the steps which I showed you, you can debug your C# application via AntiGravity and other VS Code derivatives. |
|||
|
|||
 |
|||
|
|||
## How Much is AntiGravity? 💲 |
|||
|
|||
Currently there's only individual plan is available for personal accounts and that's free 👏! The contents of Team and Enterprise plans and prices are not announced yet. But **Gemini 3 is not free**! I used it with my company's Google Workspace account which we normally pay for Gemini. |
|||
|
|||
 |
|||
|
|||
## More About AntiGravity |
|||
|
|||
There have been many AI assisted IDEs like [Windsurf](https://windsurf.com/), [Cursor](https://cursor.com/), [Zed](https://zed.dev/), [Replit](https://replit.com/) and [Fleet](https://www.jetbrains.com/fleet/). But this time it's different, this is backed by Google. |
|||
As you see from the below image AntiGravity, uses a standard grid layout as others based on VS Code editor. |
|||
It's very similar to Cursor, Visual Studio, Rider. |
|||
|
|||
 |
|||
|
|||
## Supported LLMs 🧠 |
|||
|
|||
Antigravity offers the below models which supports reasoning: Gemini 3 Pro, Claude Sonnet 4.5, GPT-OSS |
|||
|
|||
 |
|||
|
|||
Antigravity uses other models for supportive tasks in the background: |
|||
|
|||
- **Nano banana**: This is used to generate images. |
|||
- **Gemini 2.5 Pro UI Checkpoint**: It's for the browser subagent to trigger browser action such as clicking, scrolling, or filling in input. |
|||
- **Gemini 2.5 Flash**: For checkpointing and context summarization, this is used. |
|||
- **Gemini 2.5 Flash Lite**: And when it's need to make a semantic search in your code-base, this is used. |
|||
|
|||
## AntiGravity Can See Your Website |
|||
|
|||
This makes a big difference from traditional IDEs. AntiGravity's browser agent is taking screenshots of your pages when it needs to check. This is achieved by a Chrome Extension as a tool to the agent, and you can also prompt the agent to take a screenshot of a page. It can iterate on website designs and implementations, it can perform UI Testing, it can monitor dashboards, it can automate routine tasks like rerunning CI. |
|||
This is the link for the extension 👉 [chromewebstore.google.com/detail/antigravity-browser-exten/eeijfnjmjelapkebgockoeaadonbchdd](https://chromewebstore.google.com/detail/antigravity-browser-exten/eeijfnjmjelapkebgockoeaadonbchdd). AntiGravity will install this extension automatically on the first run. |
|||
|
|||
 |
|||
|
|||
 |
|||
|
|||
## MCP Integration |
|||
|
|||
### When Do We Need MCP in a Code Editor? |
|||
|
|||
Simply if we want to connect to a 3rd party service to complete our task we need MCP. So AntiGravity can connect to your DB and write proper SQL queries or it can pull in recent build logs from Netlify or Heroku. Also you can ask AntiGravity to to connect GitHub for finding the best authentication pattern. |
|||
|
|||
### AntiGravity Supports These MCP Servers |
|||
|
|||
Airweave, AlloyDB for PostgreSQL, Atlassian, BigQuery, Cloud SQL for PostgreSQL, Cloud SQL for MySQL, Cloud SQL for SQL Server, Dart, Dataplex, Figma Dev Mode MCP, Firebase, GitHub, Harness, Heroku, Linear, Locofy, Looker, MCP Toolbox for Databases, MongoDB, Neon, Netlify, Notion, PayPal, Perplexity Ask, Pinecone, Prisma, Redis, Sequential Thinking, SonarQube, Spanner, Stripe and Supabase. |
|||
|
|||
 |
|||
|
|||
## Agent Settings ⚙️ |
|||
|
|||
The major settings of Agent are: |
|||
|
|||
- **Agent Auto Fix Lints**: I enabled this setting because I want the Agent automatically fixes its own mistakes for invalid syntax, bad formatting, unused variables, unreachable code or following coding standards... It makes extra tool calls that's why little bit expensive 🥴. |
|||
- **Auto Execution**: Sometimes Agent tries to build application or writing test code and running it, in these cases it executes command. I choose "Turbo" 🤜 With this option, Agent always runs the terminal command and controls my browser. |
|||
- **Review Policy**: How much control you are giving to agent 🙎. I choose "Always Proceed" 👌 because I mostly trust AI 😀. The Agent will never ask for review. |
|||
|
|||
 |
|||
|
|||
## Differences Between Cursor and AntiGravity |
|||
|
|||
While Cursor was the champion of AI code editors, **Antigravity brings a different philosophy**. |
|||
|
|||
### 1. "Agent-First 🤖" vs "You-First 🤠" |
|||
|
|||
- **Cursor:** It acts like an assistant; it predicts your next move, auto-completes your thoughts, and helps you refactor while you type. You are still the driver; Cursor just drives the car at 200 km/h. |
|||
- **Antigravity:** Antigravity is built to let you manage coding tasks. It is "Agent-First." You don't just type code; you assign tasks to autonomous agents (e.g., "Fix the bug in the login flow and verify it in the browser"). It behaves more like a junior developer that you supervise. |
|||
|
|||
### 2. The Interface |
|||
|
|||
- **Cursor:** Looks and feels exactly like **VS Code**. If you know VS Code, you know Cursor. |
|||
|
|||
- **Antigravity:** Introduces 2 major layouts: |
|||
- **Editor View:** Similar to a standard IDE |
|||
- **Manager View:** A dashboard where you see multiple "Agents" working in parallel. You can watch them plan, execute, and test tasks asynchronously. |
|||
|
|||
### 3. Verification & Trust |
|||
|
|||
- **Cursor:** You verify by reading the code diffs it suggests. |
|||
- **Antigravity:** Introduces **Artifacts**... Since the agents work autonomously, they generate proof-of-work documents, screenshots of the app running, browser logs and execution plans. So you can verify what they did without necessarily reading every line of code immediately. |
|||
|
|||
### 4. Capabilities |
|||
|
|||
- **Cursor:** Best-in-class **Autocomplete** ("Tab" feature) and **Composer** (multi-file editing). It excels at "Vibe Coding". It's getting into a flow state where the AI writes the boilerplate and you direct the logic. |
|||
- **Antigravity:** Is good at **Autonomous Execution**. It has a built-in browser and terminal that the *Agent* controls. The Agent can write code, run the server, open the browser, see the error, and fix it 😎 |
|||
|
|||
### 5. AI Models (Brains 🧠) |
|||
|
|||
- **Cursor:** Model Agnostic. You can switch between **Claude 3.5 Sonnet** *-mostly the community uses this-*, GPT-4o, and others. |
|||
- **Antigravity:** Built deeply around **Gemini 3 Pro**. It leverages Gemini's massive context window (1M+ tokens) to understand huge mono repos without needing as much "RAG" as Cursor. |
|||
|
|||
|
|||
|
|||
## Try It Yourself Now 🤝 |
|||
|
|||
If you are ready to experience the new AI code editor by Google, download and use 👇 |
|||
[**Launch Google AntiGravity**](https://antigravity.google/) |
|||
|
After Width: | Height: | Size: 70 KiB |
|
After Width: | Height: | Size: 183 KiB |
|
After Width: | Height: | Size: 62 KiB |
|
After Width: | Height: | Size: 1.1 MiB |
|
After Width: | Height: | Size: 90 KiB |
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 102 KiB |
|
After Width: | Height: | Size: 293 KiB |
|
After Width: | Height: | Size: 76 KiB |
|
After Width: | Height: | Size: 46 KiB |
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 275 KiB |
|
After Width: | Height: | Size: 49 KiB |
|
After Width: | Height: | Size: 154 KiB |
|
After Width: | Height: | Size: 5.4 KiB |
|
After Width: | Height: | Size: 6.3 KiB |
|
After Width: | Height: | Size: 6.0 KiB |
|
After Width: | Height: | Size: 4.8 KiB |
|
After Width: | Height: | Size: 7.2 KiB |
|
After Width: | Height: | Size: 3.1 KiB |
|
After Width: | Height: | Size: 6.6 KiB |
@ -0,0 +1,414 @@ |
|||
# Building Production-Ready LLM Applications with .NET: A Practical Guide |
|||
|
|||
Large Language Models (LLMs) have evolved rapidly, and integrating them into production .NET applications requires staying current with the latest approaches. In this article, I'll share practical tips and patterns I've learned while building LLM-powered systems, covering everything from API changes in GPT-5 to implementing efficient RAG (Retrieval Augmented Generation) architectures. |
|||
|
|||
Whether you're building a chatbot, a knowledge base assistant, or integrating AI into your enterprise applications, these production-tested insights will help you avoid common pitfalls and build more reliable systems. |
|||
|
|||
## The Temperature Paradigm Shift: GPT-5 Changes Everything |
|||
|
|||
If you've been working with GPT-4 or earlier models, you're familiar with the `temperature` and `top_p` parameters for controlling response randomness. **Here's the critical update**: GPT-5 no longer supports these parameters! |
|||
|
|||
### The Old Way (GPT-4) |
|||
```csharp |
|||
var chatRequest = new ChatOptions |
|||
{ |
|||
Temperature = 0.7, // ✅ Worked with GPT-4 |
|||
TopP = 0.9 // ✅ Worked with GPT-4 |
|||
}; |
|||
``` |
|||
|
|||
### The New Way (GPT-5) |
|||
```csharp |
|||
var chatRequest = new ChatOptions |
|||
{ |
|||
RawRepresentationFactory = (client => new ChatCompletionOptions() |
|||
{ |
|||
#pragma warning disable OPENAI001 |
|||
ReasoningEffortLevel = "minimal", |
|||
#pragma warning restore OPENAI001 |
|||
}) |
|||
}; |
|||
``` |
|||
|
|||
**Why the change?** GPT-5 incorporates an internal reasoning and verification process. Instead of controlling randomness, you now specify how much computational effort the model should invest in reasoning through the problem. |
|||
|
|||
 |
|||
|
|||
### Choosing the Right Reasoning Level |
|||
|
|||
- **Low**: Quick responses for simple queries (e.g., "What's the capital of France?") |
|||
- **Medium**: Balanced approach for most use cases |
|||
- **High**: Complex reasoning tasks (e.g., code generation, multi-step problem solving) |
|||
|
|||
> **Pro Tip**: Reasoning tokens are included in your API costs. Use "High" only when necessary to optimize your budget. |
|||
|
|||
## System Prompts: The "Lost in the Middle" Problem |
|||
|
|||
Here's a critical insight that can save you hours of debugging: **Important rules must be repeated at the END of your prompt!** |
|||
|
|||
### ❌ What Doesn't Work |
|||
``` |
|||
You are a helpful assistant. |
|||
RULE: Never share passwords or sensitive information. |
|||
|
|||
[User Input] |
|||
``` |
|||
|
|||
### ✅ What Actually Works |
|||
``` |
|||
You are a helpful assistant. |
|||
RULE: Never share passwords or sensitive information. |
|||
|
|||
[User Input] |
|||
|
|||
⚠️ REMINDER: Apply the rules above strictly, ESPECIALLY regarding passwords. |
|||
``` |
|||
|
|||
**Why?** LLMs suffer from the "Lost in the Middle" phenomenon—they pay more attention to the beginning and end of the context window. Critical instructions buried in the middle are often ignored. |
|||
|
|||
## RAG Architecture: The Parent-Child Pattern |
|||
|
|||
Retrieval Augmented Generation (RAG) is essential for grounding LLM responses in your own data. The most effective pattern I've found is the **Parent-Child approach**. |
|||
|
|||
 |
|||
|
|||
### How It Works |
|||
|
|||
1. **Split documents into hierarchies**: |
|||
- **Parent chunks**: Large sections (1000-2000 tokens) for context |
|||
- **Child chunks**: Small segments (200-500 tokens) for precise retrieval |
|||
|
|||
2. **Store both in vector database** with references |
|||
|
|||
3. **Query flow**: |
|||
- Search using child chunks (higher precision) |
|||
- Return parent chunks to LLM (richer context) |
|||
|
|||
### The Overlap Strategy |
|||
|
|||
Always use overlapping chunks to prevent information loss at boundaries! |
|||
|
|||
``` |
|||
Chunk 1: Token 0-500 |
|||
Chunk 2: Token 400-900 ← 100 token overlap |
|||
Chunk 3: Token 800-1300 ← 100 token overlap |
|||
``` |
|||
|
|||
**Standard recommendation**: 10-20% overlap (for 500 tokens, use 50-100 token overlap) |
|||
|
|||
### Implementation with Semantic Kernel |
|||
|
|||
```csharp |
|||
using Microsoft.SemanticKernel.Text; |
|||
|
|||
var chunks = TextChunker.SplitPlainTextParagraphs( |
|||
documentText, |
|||
maxTokensPerParagraph: 500, |
|||
overlapTokens: 50 |
|||
); |
|||
|
|||
foreach (var chunk in chunks) |
|||
{ |
|||
var embedding = await embeddingService.GenerateEmbeddingAsync(chunk); |
|||
await vectorDb.StoreAsync(chunk, embedding); |
|||
} |
|||
``` |
|||
|
|||
## PostgreSQL + pgvector: The Pragmatic Choice |
|||
|
|||
For .NET developers, choosing a vector database can be overwhelming. After evaluating multiple options, **PostgreSQL with pgvector** is the most practical choice for most scenarios. |
|||
|
|||
 |
|||
|
|||
### Why pgvector? |
|||
|
|||
✅ **Use existing SQL knowledge** - No new query language to learn |
|||
✅ **EF Core integration** - Works with your existing data access layer |
|||
✅ **JOIN with metadata** - Combine vector search with traditional queries |
|||
✅ **WHERE clause filtering** - Filter by tenant, user, date, etc. |
|||
✅ **ACID compliance** - Transaction support for data consistency |
|||
✅ **No separate infrastructure** - One database for everything |
|||
|
|||
### Setting Up pgvector with EF Core |
|||
|
|||
First, install the NuGet package: |
|||
|
|||
```bash |
|||
dotnet add package Pgvector.EntityFrameworkCore |
|||
``` |
|||
|
|||
Define your entity: |
|||
|
|||
```csharp |
|||
using Pgvector; |
|||
using Pgvector.EntityFrameworkCore; |
|||
|
|||
public class DocumentChunk |
|||
{ |
|||
public Guid Id { get; set; } |
|||
public string Content { get; set; } |
|||
public Vector Embedding { get; set; } // 👈 pgvector type |
|||
public Guid ParentChunkId { get; set; } |
|||
public DateTime CreatedAt { get; set; } |
|||
} |
|||
``` |
|||
|
|||
Configure in DbContext: |
|||
|
|||
```csharp |
|||
protected override void OnModelCreating(ModelBuilder builder) |
|||
{ |
|||
builder.HasPostgresExtension("vector"); |
|||
|
|||
builder.Entity<DocumentChunk>() |
|||
.Property(e => e.Embedding) |
|||
.HasColumnType("vector(1536)"); // 👈 OpenAI embedding dimension |
|||
|
|||
builder.Entity<DocumentChunk>() |
|||
.HasIndex(e => e.Embedding) |
|||
.HasMethod("hnsw") // 👈 Fast approximate search |
|||
.HasOperators("vector_cosine_ops"); |
|||
} |
|||
``` |
|||
|
|||
### Performing Vector Search |
|||
|
|||
```csharp |
|||
using Pgvector.EntityFrameworkCore; |
|||
|
|||
public async Task<List<DocumentChunk>> SearchAsync(string query) |
|||
{ |
|||
// 1. Convert query to embedding |
|||
var queryVector = await _embeddingService.GetEmbeddingAsync(query); |
|||
|
|||
// 2. Search |
|||
return await _context.DocumentChunks |
|||
.OrderBy(c => c.Embedding.L2Distance(queryVector)) // 👈 Lower is better |
|||
.Take(5) |
|||
.ToListAsync(); |
|||
} |
|||
``` |
|||
|
|||
**Source**: [Pgvector.NET on GitHub](https://github.com/pgvector/pgvector-dotnet?tab=readme-ov-file#entity-framework-core) |
|||
|
|||
## Smart Tool Usage: Make RAG a Tool, Not a Tax |
|||
|
|||
A common mistake is calling RAG on every single user message. This wastes tokens and money. Instead, **make RAG a tool** and let the LLM decide when to use it. |
|||
|
|||
### ❌ Expensive Approach |
|||
```csharp |
|||
// Always call RAG, even for "Hello" |
|||
var context = await PerformRAG(userMessage); |
|||
var response = await chatClient.CompleteAsync($"{context}\n\n{userMessage}"); |
|||
``` |
|||
|
|||
### ✅ Smart Approach |
|||
```csharp |
|||
[KernelFunction] |
|||
[Description("Search the company knowledge base for information")] |
|||
public async Task<string> SearchKnowledgeBase( |
|||
[Description("The search query")] string query) |
|||
{ |
|||
var results = await _vectorDb.SearchAsync(query); |
|||
return string.Join("\n---\n", results.Select(r => r.Content)); |
|||
} |
|||
``` |
|||
|
|||
The LLM will call `SearchKnowledgeBase` only when needed: |
|||
- "Hello" → No tool call |
|||
- "What was our 2024 revenue?" → Calls tool |
|||
- "Tell me a joke" → No tool call |
|||
|
|||
## Multilingual RAG: Query Translation Strategy |
|||
|
|||
When your documents are in one language (e.g., English) but users query in another (e.g., Turkish), you need a translation strategy. |
|||
|
|||
 |
|||
|
|||
### Solution Options |
|||
|
|||
**Option 1**: Use an LLM that automatically calls tools in English |
|||
- Many modern LLMs can do this if properly instructed |
|||
|
|||
**Option 2**: Tool chain approach |
|||
```csharp |
|||
[KernelFunction] |
|||
[Description("Translate text to English")] |
|||
public async Task<string> TranslateToEnglish(string text) |
|||
{ |
|||
// Translation logic |
|||
} |
|||
|
|||
[KernelFunction] |
|||
[Description("Search knowledge base (English only)")] |
|||
public async Task<string> SearchKnowledgeBase(string englishQuery) |
|||
{ |
|||
// Search logic |
|||
} |
|||
``` |
|||
|
|||
The LLM will: |
|||
1. Call `TranslateToEnglish("2024 geliri nedir?")` |
|||
2. Get "What was 2024 revenue?" |
|||
3. Call `SearchKnowledgeBase("What was 2024 revenue?")` |
|||
4. Return results and respond in Turkish |
|||
|
|||
## Model Context Protocol (MCP): Beyond In-Process Tools |
|||
|
|||
Microsoft and Anthropic recently released official C# SDKs for the Model Context Protocol (MCP). This is a game-changer for tool reusability. |
|||
|
|||
 |
|||
|
|||
### MCP vs. Semantic Kernel Plugins |
|||
|
|||
| Feature | SK Plugins | MCP Servers | |
|||
|---------|-----------|-------------| |
|||
| **Process** | In-process | Out-of-process (stdio/http) | |
|||
| **Reusability** | Application-specific | Cross-application | |
|||
| **Examples** | Used within your app | VS Code Copilot, Claude Desktop | |
|||
|
|||
### Creating an MCP Server |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.Hosting; |
|||
using ModelContextProtocol.Extensions.Hosting; |
|||
|
|||
var builder = Host.CreateEmptyApplicationBuilder(settings: null); |
|||
|
|||
builder.Services.AddMcpServer() |
|||
.WithStdioServerTransport() |
|||
.WithToolsFromAssembly(); |
|||
|
|||
await builder.Build().RunAsync(); |
|||
``` |
|||
|
|||
Define your tools: |
|||
|
|||
```csharp |
|||
[McpServerToolType] |
|||
public static class FileSystemTools |
|||
{ |
|||
[McpServerTool, Description("Read a file from the file system")] |
|||
public static async Task<string> ReadFile(string path) |
|||
{ |
|||
// ⚠️ SECURITY: Always validate paths! |
|||
if (!IsPathSafe(path)) |
|||
throw new SecurityException("Invalid path"); |
|||
|
|||
return await File.ReadAllTextAsync(path); |
|||
} |
|||
|
|||
private static bool IsPathSafe(string path) |
|||
{ |
|||
// Implement path traversal prevention |
|||
var fullPath = Path.GetFullPath(path); |
|||
return fullPath.StartsWith(AllowedDirectory); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Your MCP server can now be used by VS Code Copilot, Claude Desktop, or any other MCP client! |
|||
|
|||
## Chat History Management: Truncation + RAG Hybrid |
|||
|
|||
For long conversations, storing all history in the context window becomes impractical. Here's the pattern that works: |
|||
|
|||
 |
|||
|
|||
### ❌ Lossy Approach |
|||
``` |
|||
First 50 messages → Summarize with LLM → Single summary message |
|||
``` |
|||
**Problem**: Detail loss (fidelity loss) |
|||
|
|||
### ✅ Hybrid Approach |
|||
1. **Recent messages** (last 5-10): Keep in prompt for immediate context |
|||
2. **Older messages**: Store in vector database as a tool |
|||
|
|||
```csharp |
|||
[KernelFunction] |
|||
[Description("Search conversation history for past discussions")] |
|||
public async Task<string> SearchChatHistory( |
|||
[Description("What to search for")] string query) |
|||
{ |
|||
var relevantMessages = await _vectorDb.SearchAsync(query); |
|||
return string.Join("\n", relevantMessages.Select(m => |
|||
$"[{m.Timestamp}] {m.Role}: {m.Content}")); |
|||
} |
|||
``` |
|||
|
|||
The LLM retrieves only relevant past context when needed, avoiding summary-induced information loss. |
|||
|
|||
## RAG vs. Fine-Tuning: Choose Wisely |
|||
|
|||
A common misconception is using fine-tuning for knowledge injection. Here's when to use each: |
|||
|
|||
| Purpose | RAG | Fine-Tuning | |
|||
|---------|-----|-------------| |
|||
| **Goal** | Memory (provide facts) | Behavior (teach style) | |
|||
| **Updates** | Dynamic (add docs anytime) | Static (requires retraining) | |
|||
| **Cost** | Low dev, higher inference | High dev, lower inference | |
|||
| **Hallucination** | Reduces | Doesn't reduce | |
|||
| **Use Case** | Company docs, FAQs | Brand voice, specific format | |
|||
|
|||
**Common mistake**: "Let's fine-tune on our company documents" ❌ |
|||
**Better approach**: Use RAG! ✅ |
|||
|
|||
Fine-tuning is for teaching the model *how* to respond, not *what* to know. |
|||
|
|||
**Source**: [Oracle - RAG vs Fine-Tuning](https://www.oracle.com/artificial-intelligence/generative-ai/retrieval-augmented-generation-rag/rag-fine-tuning/) |
|||
|
|||
## Bonus: Why SVG is Superior for LLM-Generated Images |
|||
|
|||
When using LLMs to generate diagrams and visualizations, always request SVG format instead of PNG or JPG. |
|||
|
|||
### Why SVG? |
|||
|
|||
✅ **Text-based** → LLMs produce better results |
|||
✅ **Lower cost** → Fewer tokens than base64-encoded images |
|||
✅ **Editable** → Easy to modify after generation |
|||
✅ **Scalable** → Perfect quality at any size |
|||
✅ **Version control friendly** → Works great in Git |
|||
|
|||
### Example Prompt |
|||
|
|||
``` |
|||
Create an architecture diagram showing PostgreSQL with pgvector integration. |
|||
Format: SVG, 800x400 pixels. Show: .NET Application → EF Core → PostgreSQL → Vector Search. |
|||
Use arrows to connect stages. Color scheme: Blue tones. |
|||
``` |
|||
|
|||
 |
|||
|
|||
All diagrams in this article were generated as SVG, resulting in excellent quality and lower token costs! |
|||
|
|||
> **Pro Tip**: If you don't need photographs or complex renders, always choose SVG. |
|||
|
|||
## Architecture Roadmap: Putting It All Together |
|||
|
|||
Here's the recommended stack for building production LLM applications with .NET: |
|||
|
|||
1. **Orchestration**: Microsoft.Extensions.AI + Semantic Kernel (when needed) |
|||
2. **Vector Database**: PostgreSQL + Pgvector.EntityFrameworkCore |
|||
3. **RAG Pattern**: Parent-Child chunks with 10-20% overlap |
|||
4. **Tools**: MCP servers for reusability |
|||
5. **Reasoning**: ReasoningEffortLevel instead of temperature |
|||
6. **Prompting**: Critical rules at the end |
|||
7. **Cost Optimization**: Make RAG a tool, not automatic |
|||
|
|||
## Key Takeaways |
|||
|
|||
Let me summarize the most important production tips: |
|||
|
|||
1. **Temperature is gone** → Use `ReasoningEffortLevel` with GPT-5 |
|||
2. **Rules at the end** → Combat "Lost in the Middle" |
|||
3. **RAG as a tool** → Reduce costs significantly |
|||
4. **Parent-Child pattern** → Search small, respond with large |
|||
5. **Always use overlap** → 10-20% is the standard |
|||
6. **pgvector for most cases** → Unless you have billions of vectors |
|||
7. **MCP for reusability** → One codebase, works everywhere |
|||
8. **SVG for diagrams** → Better results, lower cost |
|||
9. **Hybrid chat history** → Recent in prompt, old in vector DB |
|||
10. **RAG > Fine-tuning** → For knowledge, not behavior |
|||
|
|||
Happy coding! 🚀 |
|||
@ -0,0 +1 @@ |
|||
Learn how to build production-ready LLM applications with .NET. This comprehensive guide covers GPT-5 API changes, advanced RAG architectures with parent-child patterns, PostgreSQL pgvector integration, smart tool usage strategies, multilingual query handling, Model Context Protocol (MCP) for cross-application tool reusability, and chat history management techniques for enterprise applications. |
|||
@ -0,0 +1,60 @@ |
|||
# .NET Conf China 2025: Changing the World, Changing Ourselves - See You Again in Shanghai |
|||
|
|||
 |
|||
|
|||
.NET Conf China 2025 is an annual community event for developers, celebrating the release of .NET 10 (LTS) and the achievements of the past year in China. As an extension of .NET Conf 2025, this event brings together local tech communities, well-known companies, and open-source organizations. It has become the largest .NET online and offline conference in China, dedicated to spreading .NET technology in Chinese and fostering collaboration and exchange. |
|||
|
|||
## Event Highlights: Key Topics and Takeaways |
|||
|
|||
This year’s conference focused on three main themes: performance improvements, AI integration, and cross-platform development. Topics covered how to achieve performance gains while maintaining engineering quality, balancing between multi-platform consistency and native capabilities, and taking generative AI from “demo-level” to “production-ready.” On the community and ecosystem side, the event showcased the .NET Foundation’s and domestic and international companies’ progress in supporting architectures like ARM, LoongArch, and RISC-V. It also highlighted best practices in DevOps, observability, and engineering toolchains, creating a complete path from ideas to implementation. |
|||
|
|||
### 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. |
|||
|
|||
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. |
|||
|
|||
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. |
|||
|
|||
 |
|||
|
|||
### Roundtable Discussion |
|||
|
|||
The roundtable discussion, titled “Empowering with AI, Breaking Through Cross-Platform Barriers, and Ecosystem Innovation,” focused on practical implementation. It explored typical paths for large models and intelligent agents in enterprises, key considerations for choosing cross-platform UI frameworks, and the evolution of these frameworks. Panelists discussed questions like: How can AI capabilities be integrated into existing business processes instead of creating an “experimental” pipeline? How should cross-platform solutions be evaluated in terms of performance, ecosystem, and team skillsets? What are the unique opportunities for domestic ecosystems in the global tech landscape? And how can community collaboration help developers quickly adopt best practices? A shared consensus emerged: in the short term, focus on running scenarios; in the long term, return to engineering fundamentals. Both toolchains and methodologies are equally important. |
|||
|
|||
 |
|||
|
|||
### In-Depth Sessions |
|||
|
|||
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. |
|||
- **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. |
|||
|
|||
 |
|||
|
|||
## ABP Booth Highlights: Showcases, Conversations, and Fun |
|||
|
|||
The story of ABP began with a promise to create a better starting point. From the frustration of “copy-pasting boilerplate code,” we crafted a modular, opinionated framework. We chose open source and community collaboration. We founded Volosoft to turn our vision into reality with professional tools. Today, tens of thousands of developers explore the ABP framework, and thousands of teams rely on the ABP platform to deliver production-grade .NET applications faster and more securely. |
|||
|
|||
 |
|||
|
|||
At .NET Conf China 2025, we brought our “developer platform built for developers” to every visitor. Our booth demonstrations started with “a production-ready skeleton from the start”: modular layered architecture, built-in authentication and authorization systems, multi-tenancy support, audit logging, and localization—all out of the box. On the frontend and backend, ABP offers diverse options like MVC, Blazor, and Angular, enabling teams to quickly implement solutions on familiar stacks while maintaining flexibility for future evolution. We also showcased how ABP integrates with containerization, CI/CD, and observability, emphasizing “engineering built into the framework, not reinvented by every team.” |
|||
|
|||
 |
|||
|
|||
**Interaction and Prizes:** Sharing technology should also be warm and engaging. We hosted a QR code raffle at the booth, with prizes including ABP stickers, the book *Mastering ABP Framework*, and Bluetooth headphones. Multiple rounds of raffles and group photos made the interactions more memorable. Many developers shared their ABP experiences and plans for improvement right at the booth, and a few impromptu “code walkthroughs” naturally happened. The love and joy for technology were captured in every handshake and discussion. |
|||
|
|||
 |
|||
|
|||
## Looking Ahead: Building the Ecosystem Together |
|||
|
|||
From an open-source journey to a complete development platform for the future, we’ve always believed that developers deserve a better starting point. Around performance, intelligence, and cross-platform capabilities, we will continue investing in engineering, ecosystem collaboration, and best practice sharing. We also welcome more partners to contribute through documentation and examples, share your experiences, and submit your ideas. Together, let’s make “useful infrastructure” more stable, efficient, and business-friendly. |
|||
|
|||
We look forward to exchanging ideas, sharing practices, and building the ecosystem together at the next gathering. Technology meets creativity, and the possibilities are endless. We’re on the road and waiting for you at the next event. |
|||
|
|||
See you next year at .NET Conf China 2026! |
|||
|
|||
 |
|||
|
After Width: | Height: | Size: 396 KiB |
|
After Width: | Height: | Size: 502 KiB |
|
After Width: | Height: | Size: 432 KiB |
|
After Width: | Height: | Size: 328 KiB |
|
After Width: | Height: | Size: 524 KiB |
|
After Width: | Height: | Size: 378 KiB |
|
After Width: | Height: | Size: 671 KiB |
|
After Width: | Height: | Size: 399 KiB |
|
After Width: | Height: | Size: 103 KiB |
|
After Width: | Height: | Size: 93 KiB |
|
After Width: | Height: | Size: 7.0 KiB |
|
After Width: | Height: | Size: 4.1 KiB |
|
After Width: | Height: | Size: 7.8 KiB |
|
After Width: | Height: | Size: 7.5 KiB |
@ -0,0 +1,797 @@ |
|||
# Implement Automatic Method-Level Caching in ABP Framework |
|||
|
|||
Caching is one of the most effective ways to improve application performance, but implementing it manually for every method can be tedious and error-prone. What if you could cache method results automatically with just an attribute? In this article, we'll explore how to build an automatic method-level caching system in ABP Framework that handles cache invalidation, supports multiple scopes, and integrates seamlessly with your existing application. |
|||
|
|||
By the end of this guide, you'll understand how to implement attribute-based caching that automatically invalidates when entities change, supports user-specific and global caching scopes, and provides built-in metrics for monitoring cache performance. |
|||
|
|||
> 💡 **Complete Implementation Available**: This article is based on a working demo project. You can find the complete implementation in the [AbpAutoCacheDemo repository](https://github.com/salihozkara/AbpAutoCacheDemo), with the core AutoCache library implementation available in [this commit](https://github.com/salihozkara/AbpAutoCacheDemo/commit/946df1fc07de6eddd26eb14013a09968cd59329b). |
|||
|
|||
## What is Automatic Method-Level Caching? |
|||
|
|||
Automatic method-level caching is a technique that intercepts method calls and caches their results without requiring manual cache management code. Instead of writing cache logic in every method, you simply decorate methods with attributes that define caching behavior. |
|||
|
|||
 |
|||
|
|||
The key benefits include: |
|||
|
|||
- **Reduced Boilerplate:** No repetitive cache management code in your business logic |
|||
- **Consistent Caching Strategy:** Centralized cache configuration and behavior |
|||
- **Smart Invalidation:** Automatic cache clearing when related entities change |
|||
- **Multiple Scopes:** Support for global, user-specific, and entity-specific caching |
|||
- **Built-in Monitoring:** Track cache hits, misses, and performance metrics |
|||
|
|||
## Architecture Overview |
|||
|
|||
The automatic caching system consists of several key components working together: |
|||
|
|||
 |
|||
|
|||
**Core Components:** |
|||
|
|||
1. **CacheAttribute:** The attribute you apply to methods to enable automatic caching |
|||
2. **AutoCacheInterceptor:** Intercepts method calls and handles cache operations |
|||
3. **AutoCacheManager:** Manages cache storage, retrieval, and key generation |
|||
4. **IAutoCacheKeyManager:** Handles cache key mapping and invalidation |
|||
5. **AutoCacheInvalidationHandler:** Listens to entity changes and clears related caches |
|||
|
|||
This architecture leverages ABP's dynamic proxy system and event bus to provide seamless caching without modifying your business logic. |
|||
|
|||
## Prerequisites |
|||
|
|||
Before implementing automatic caching, ensure you have: |
|||
|
|||
- ABP Framework 10.0 or later |
|||
## Implementation |
|||
|
|||
> 📦 **Repository Structure**: The complete implementation is available in the [AbpAutoCacheDemo repository](https://github.com/salihozkara/AbpAutoCacheDemo). The AutoCache library is located in the `src/AutoCache` folder, making it easy to extract and reuse in your own projects. |
|||
|
|||
### Step - 1: Create the AutoCache Module |
|||
|
|||
First, let's create a separate module for our caching infrastructure. This makes it reusable across projects. |
|||
|
|||
### Step - 1: Create the AutoCache Module |
|||
|
|||
First, let's create a separate module for our caching infrastructure. This makes it reusable across projects. |
|||
|
|||
Create `AutoCache.csproj`: |
|||
|
|||
```xml |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
<PropertyGroup> |
|||
<TargetFramework>net10.0</TargetFramework> |
|||
<Nullable>enable</Nullable> |
|||
</PropertyGroup> |
|||
|
|||
<ItemGroup> |
|||
<PackageReference Include="Volo.Abp.Caching.StackExchangeRedis" Version="10.0.0" /> |
|||
<PackageReference Include="Volo.Abp.Core" Version="10.0.0" /> |
|||
<PackageReference Include="Volo.Abp.Ddd.Domain" Version="10.0.0" /> |
|||
</ItemGroup> |
|||
</Project> |
|||
``` |
|||
|
|||
Create the module class `AutoCacheModule.cs`: |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.DependencyInjection; |
|||
using Volo.Abp.Caching.StackExchangeRedis; |
|||
using Volo.Abp.Domain; |
|||
using Volo.Abp.Modularity; |
|||
|
|||
namespace AutoCache; |
|||
|
|||
[DependsOn(typeof(AbpDddDomainModule), typeof(AbpCachingStackExchangeRedisModule))] |
|||
public class AutoCacheModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.OnRegistered(AutoCacheRegister.RegisterInterceptorIfNeeded); // 👈 Register interceptor |
|||
} |
|||
} |
|||
``` |
|||
|
|||
This module automatically registers the cache interceptor for any class that uses the `CacheAttribute`. |
|||
|
|||
### Step - 2: Define the Cache Attribute |
|||
|
|||
The `CacheAttribute` is the core of our automatic caching system. It specifies which entities affect the cache and what scope to use. |
|||
|
|||
Create `CacheAttribute.cs`: |
|||
|
|||
```csharp |
|||
using System; |
|||
using Volo.Abp.Domain.Entities; |
|||
|
|||
namespace AutoCache; |
|||
|
|||
[AttributeUsage(AttributeTargets.Method)] |
|||
public class CacheAttribute : Attribute |
|||
{ |
|||
/// <summary> |
|||
/// Entity types that affect this cache. When these entities change, the cache will be invalidated. |
|||
/// </summary> |
|||
public Type[] InvalidateOnEntities { get; set; } |
|||
|
|||
/// <summary> |
|||
/// Scope of the cache (Global, CurrentUser, AuthenticatedUser, or Entity) |
|||
/// </summary> |
|||
public AutoCacheScope Scope { get; set; } = AutoCacheScope.Global; |
|||
|
|||
/// <summary> |
|||
/// Absolute expiration time relative to now in milliseconds (0 = use default, -1 = disabled) |
|||
/// </summary> |
|||
public long AbsoluteExpirationRelativeToNow { get; set; } |
|||
|
|||
/// <summary> |
|||
/// Sliding expiration time in milliseconds (0 = use default, -1 = disabled) |
|||
/// </summary> |
|||
public long SlidingExpiration { get; set; } |
|||
|
|||
public bool ConsiderUow { get; set; } |
|||
|
|||
public string AdditionalCacheKey { get; set; } |
|||
|
|||
public CacheAttribute(params Type[] invalidateOnEntities) // 👈 Specify entities that trigger cache invalidation |
|||
{ |
|||
foreach (var entityType in invalidateOnEntities) |
|||
{ |
|||
ArgumentNullException.ThrowIfNull(entityType); |
|||
if (!typeof(IEntity).IsAssignableFrom(entityType)) |
|||
{ |
|||
throw new ArgumentException($"Type {entityType.FullName} must implement IEntity interface."); |
|||
} |
|||
} |
|||
InvalidateOnEntities = invalidateOnEntities; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**Key Properties:** |
|||
|
|||
- **InvalidateOnEntities:** Array of entity types that, when modified, will clear this cache |
|||
- **Scope:** Determines cache visibility (Global, CurrentUser, AuthenticatedUser, Entity) |
|||
- **AbsoluteExpirationRelativeToNow / SlidingExpiration:** Control cache lifetime |
|||
|
|||
### Step - 3: Define Cache Scopes |
|||
|
|||
Cache scopes determine how cache entries are partitioned. Create `AutoCacheScope.cs`: |
|||
|
|||
```csharp |
|||
using System; |
|||
|
|||
namespace AutoCache; |
|||
|
|||
[Flags] |
|||
public enum AutoCacheScope |
|||
{ |
|||
/// <summary> |
|||
/// Cache is shared globally across all users |
|||
/// </summary> |
|||
Global, |
|||
|
|||
/// <summary> |
|||
/// Cache is scoped to the current user (based on user ID) |
|||
/// </summary> |
|||
CurrentUser, |
|||
|
|||
/// <summary> |
|||
/// Cache is scoped to authenticated vs unauthenticated users |
|||
/// </summary> |
|||
AuthenticatedUser, |
|||
|
|||
/// <summary> |
|||
/// Cache is scoped to the primary key of the entity involved |
|||
/// </summary> |
|||
Entity |
|||
} |
|||
``` |
|||
|
|||
 |
|||
|
|||
**When to Use Each Scope:** |
|||
|
|||
- **Global:** For data that's the same for all users (e.g., configuration, public lists) |
|||
- **CurrentUser:** For user-specific data (e.g., user profile, user's orders) |
|||
- **AuthenticatedUser:** For data that differs between authenticated and anonymous users |
|||
- **Entity:** For data tied to a specific entity instance (e.g., book details by ID) |
|||
|
|||
### Step - 4: Implement the Cache Interceptor |
|||
|
|||
The interceptor is the heart of automatic caching. It intercepts method calls, checks the cache, and stores results. Create `AutoCacheInterceptor.cs`: |
|||
|
|||
```csharp |
|||
using System; |
|||
using System.Collections.Concurrent; |
|||
using System.Linq; |
|||
using System.Reflection; |
|||
using System.Threading.Tasks; |
|||
using Microsoft.Extensions.Caching.Distributed; |
|||
using Microsoft.Extensions.Logging; |
|||
using Microsoft.Extensions.Options; |
|||
using Volo.Abp.DependencyInjection; |
|||
using Volo.Abp.DynamicProxy; |
|||
|
|||
namespace AutoCache; |
|||
|
|||
public class AutoCacheInterceptor : AbpInterceptor, ITransientDependency |
|||
{ |
|||
private readonly ILogger<AutoCacheInterceptor> _logger; |
|||
private readonly AutoCacheOptions _options; |
|||
private static readonly MethodInfo GetOrAddCacheAsyncMethod; |
|||
private readonly AutoCacheManager _autoCacheManager; |
|||
private static readonly ConcurrentDictionary<Type, MethodInfo> MethodCache = new(); |
|||
|
|||
static AutoCacheInterceptor() |
|||
{ |
|||
GetOrAddCacheAsyncMethod = typeof(AutoCacheInterceptor).GetMethod( |
|||
nameof(GetOrAddCacheAsync), |
|||
BindingFlags.NonPublic | BindingFlags.Instance |
|||
)!; |
|||
} |
|||
|
|||
public AutoCacheInterceptor( |
|||
ILogger<AutoCacheInterceptor> logger, |
|||
IOptions<AutoCacheOptions> options, |
|||
AutoCacheManager autoCacheManager) |
|||
{ |
|||
_logger = logger; |
|||
_autoCacheManager = autoCacheManager; |
|||
_options = options.Value; |
|||
} |
|||
|
|||
public override async Task InterceptAsync(IAbpMethodInvocation invocation) |
|||
{ |
|||
// Check if caching is enabled and method has [Cache] attribute |
|||
if(!_options.Enabled || |
|||
invocation.Method.GetCustomAttributes(typeof(CacheAttribute), true).FirstOrDefault() |
|||
is not CacheAttribute attribute) |
|||
{ |
|||
await invocation.ProceedAsync(); // 👈 No caching, proceed normally |
|||
return; |
|||
} |
|||
|
|||
var proceeded = false; |
|||
|
|||
try |
|||
{ |
|||
// Create generic method based on return type |
|||
var genericMethod = MethodCache.GetOrAdd(invocation.Method.ReturnType, t => |
|||
{ |
|||
var isGenericTask = t.IsGenericType && t.GetGenericTypeDefinition() == typeof(Task<>); |
|||
var resultType = isGenericTask ? t.GetGenericArguments()[0] : t; |
|||
return GetOrAddCacheAsyncMethod.MakeGenericMethod(resultType); |
|||
}); |
|||
|
|||
// Execute cache logic |
|||
(var result, proceeded) = await (Task<(object, bool)>)genericMethod.Invoke(this, [invocation, attribute])!; |
|||
invocation.ReturnValue = result; // 👈 Set cached or fresh result |
|||
} |
|||
catch (Exception e) |
|||
{ |
|||
_logger.LogError(e, "Error occurred while caching method {MethodName}", invocation.Method.Name); |
|||
|
|||
if(e is AutoCacheExceptionWrapper exceptionWrapper) |
|||
{ |
|||
if (_options.ThrowOnError) |
|||
{ |
|||
throw exceptionWrapper.OriginalException; |
|||
} |
|||
|
|||
_logger.LogWarning( |
|||
"Cache operation failed, falling back to method execution for {MethodName}", |
|||
invocation.Method.Name |
|||
); |
|||
} |
|||
|
|||
if (!proceeded && invocation.ReturnValue == null) |
|||
{ |
|||
await invocation.ProceedAsync(); // 👈 Fallback to actual method execution |
|||
} |
|||
} |
|||
} |
|||
|
|||
private async Task<(object?, bool)> GetOrAddCacheAsync<TResult>( |
|||
IAbpMethodInvocation invocation, |
|||
CacheAttribute attribute) |
|||
{ |
|||
var proceeded = false; |
|||
var result = await _autoCacheManager.GetOrAddAsync( |
|||
invocation.TargetObject, |
|||
Factory, |
|||
invocation.Arguments, |
|||
() => new DistributedCacheEntryOptions |
|||
{ |
|||
AbsoluteExpirationRelativeToNow = GetExpiration( |
|||
attribute.AbsoluteExpirationRelativeToNow, |
|||
_options.DefaultAbsoluteExpirationRelativeToNow), |
|||
SlidingExpiration = GetExpiration( |
|||
attribute.SlidingExpiration, |
|||
_options.DefaultSlidingExpiration) |
|||
}, |
|||
attribute.InvalidateOnEntities, |
|||
attribute.Scope, |
|||
attribute.ConsiderUow, |
|||
attribute.AdditionalCacheKey, |
|||
invocation.Method.Name); |
|||
|
|||
return (result, proceeded); |
|||
|
|||
async Task<TResult> Factory() |
|||
{ |
|||
await invocation.ProceedAsync(); // 👈 Execute actual method on cache miss |
|||
proceeded = true; |
|||
return (TResult)invocation.ReturnValue; |
|||
} |
|||
} |
|||
|
|||
private static TimeSpan? GetExpiration(long milliseconds, long defaultValue) |
|||
{ |
|||
return milliseconds switch |
|||
{ |
|||
0 => defaultValue > 0 ? TimeSpan.FromMilliseconds(defaultValue) : null, |
|||
< 0 => null, |
|||
_ => TimeSpan.FromMilliseconds(milliseconds) |
|||
}; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The interceptor intelligently determines whether to serve cached data or execute the actual method. |
|||
|
|||
### Step - 5: Implement the Cache Manager |
|||
|
|||
The `AutoCacheManager` handles the actual cache operations. Create a simplified version: |
|||
|
|||
```csharp |
|||
using System; |
|||
using System.Runtime.CompilerServices; |
|||
using System.Threading.Tasks; |
|||
using Microsoft.Extensions.Caching.Distributed; |
|||
using Microsoft.Extensions.Logging; |
|||
using Volo.Abp.DependencyInjection; |
|||
using Volo.Abp.DynamicProxy; |
|||
using Volo.Abp.Users; |
|||
|
|||
namespace AutoCache; |
|||
|
|||
public class AutoCacheManager : IScopedDependency |
|||
{ |
|||
private readonly IAutoCacheKeyManager _autoCacheKeyManager; |
|||
private readonly ICurrentUser _currentUser; |
|||
private readonly ILogger<AutoCacheManager> _logger; |
|||
private readonly IAutoCacheMetrics _metrics; |
|||
private readonly AutoCacheOptions _options; |
|||
|
|||
public AutoCacheManager( |
|||
IAutoCacheKeyManager autoCacheKeyManager, |
|||
ICurrentUser currentUser, |
|||
ILogger<AutoCacheManager> logger, |
|||
IAutoCacheMetrics metrics, |
|||
IOptions<AutoCacheOptions> options) |
|||
{ |
|||
_autoCacheKeyManager = autoCacheKeyManager; |
|||
_currentUser = currentUser; |
|||
_logger = logger; |
|||
_metrics = metrics; |
|||
_options = options.Value; |
|||
} |
|||
|
|||
public async Task<TResult> GetOrAddAsync<TResult>( |
|||
object? caller, |
|||
Func<Task<TResult>> func, |
|||
object?[]? parameters = null, |
|||
Func<DistributedCacheEntryOptions>? optionsFactory = null, |
|||
Type[]? invalidateOnEntities = null, |
|||
AutoCacheScope scope = AutoCacheScope.Global, |
|||
bool considerUow = false, |
|||
string? additionalCacheKey = null, |
|||
[CallerMemberName] string methodName = "") |
|||
{ |
|||
if (!_options.Enabled) |
|||
{ |
|||
return await func(); // 👈 Caching disabled, execute directly |
|||
} |
|||
|
|||
var callerType = caller != null ? ProxyHelper.GetUnProxiedType(caller) : GetType(); |
|||
parameters ??= []; |
|||
|
|||
// Generate unique cache key based on method, parameters, and scope |
|||
var cacheKey = GenerateCacheKey<TResult>( |
|||
callerType.Name, |
|||
additionalCacheKey, |
|||
methodName, |
|||
parameters, |
|||
scope); |
|||
|
|||
var (cachedResult, exception, wasHit) = await GetOrAddCacheAsync( |
|||
cacheKey, |
|||
func, |
|||
optionsFactory, |
|||
considerUow |
|||
); |
|||
|
|||
// Record metrics |
|||
if (wasHit) |
|||
{ |
|||
_metrics.RecordHit(cacheKey); |
|||
} |
|||
else |
|||
{ |
|||
_metrics.RecordMiss(cacheKey); |
|||
} |
|||
|
|||
if (exception != null) |
|||
{ |
|||
_metrics.RecordError(cacheKey, exception); |
|||
|
|||
if (_options.ThrowOnError) |
|||
{ |
|||
throw exception; |
|||
} |
|||
} |
|||
|
|||
return cachedResult; |
|||
} |
|||
|
|||
private string GenerateCacheKey<TResult>( |
|||
string callerTypeName, |
|||
string? additionalCacheKey, |
|||
string methodName, |
|||
object?[] parameters, |
|||
AutoCacheScope scope) |
|||
{ |
|||
var keyBuilder = new StringBuilder(); |
|||
keyBuilder.Append($"{callerTypeName}:{methodName}"); |
|||
|
|||
// Add parameters to key |
|||
foreach (var param in parameters) |
|||
{ |
|||
keyBuilder.Append($":{param}"); |
|||
} |
|||
|
|||
// Add scope-specific segments |
|||
if (scope.HasFlag(AutoCacheScope.CurrentUser) && _currentUser.Id.HasValue) |
|||
{ |
|||
keyBuilder.Append($":user:{_currentUser.Id}"); // 👈 User-specific cache key |
|||
} |
|||
|
|||
if (scope.HasFlag(AutoCacheScope.AuthenticatedUser)) |
|||
{ |
|||
keyBuilder.Append($":auth:{_currentUser.IsAuthenticated}"); |
|||
} |
|||
|
|||
if (!string.IsNullOrEmpty(additionalCacheKey)) |
|||
{ |
|||
keyBuilder.Append($":{additionalCacheKey}"); |
|||
} |
|||
|
|||
return keyBuilder.ToString(); |
|||
} |
|||
|
|||
// Additional methods for cache retrieval and storage... |
|||
} |
|||
``` |
|||
|
|||
The manager generates unique cache keys based on method signatures, parameters, and scope settings. |
|||
|
|||
### Step - 6: Implement Cache Invalidation |
|||
|
|||
When entities change, related caches must be cleared. Create `AutoCacheInvalidationHandler.cs`: |
|||
|
|||
```csharp |
|||
using System; |
|||
using System.Threading.Tasks; |
|||
using Microsoft.Extensions.Logging; |
|||
using Volo.Abp.Domain.Entities; |
|||
using Volo.Abp.Domain.Entities.Events; |
|||
using Volo.Abp.EventBus; |
|||
using Volo.Abp.Uow; |
|||
|
|||
namespace AutoCache; |
|||
|
|||
public class AutoCacheInvalidationHandler<TEntity> : |
|||
ILocalEventHandler<EntityChangedEventData<TEntity>> |
|||
where TEntity : class, IEntity |
|||
{ |
|||
private readonly IAutoCacheKeyManager _autoCacheKeyManager; |
|||
private readonly ILogger<AutoCacheInvalidationHandler<TEntity>> _logger; |
|||
private readonly IUnitOfWorkManager _unitOfWorkManager; |
|||
|
|||
public AutoCacheInvalidationHandler( |
|||
IAutoCacheKeyManager autoCacheKeyManager, |
|||
ILogger<AutoCacheInvalidationHandler<TEntity>> logger, |
|||
IUnitOfWorkManager unitOfWorkManager) |
|||
{ |
|||
_autoCacheKeyManager = autoCacheKeyManager; |
|||
_logger = logger; |
|||
_unitOfWorkManager = unitOfWorkManager; |
|||
} |
|||
|
|||
public async Task HandleEventAsync(EntityChangedEventData<TEntity> eventData) |
|||
{ |
|||
try |
|||
{ |
|||
var entityType = typeof(TEntity); |
|||
var context = new RemoveCacheKeyContext |
|||
{ |
|||
Keys = eventData.Entity.GetKeys()! |
|||
}; |
|||
|
|||
// Clear cache after unit of work completes |
|||
if(_unitOfWorkManager.Current != null) |
|||
{ |
|||
_unitOfWorkManager.Current.OnCompleted(async () => |
|||
{ |
|||
await _autoCacheKeyManager.RemoveCacheAndCacheKeys(entityType, context); // 👈 Invalidate cache |
|||
}); |
|||
} |
|||
else |
|||
{ |
|||
await _autoCacheKeyManager.RemoveCacheAndCacheKeys(entityType, context); |
|||
} |
|||
} |
|||
catch (Exception e) |
|||
{ |
|||
_logger.LogError( |
|||
e, |
|||
"Error occurred while clearing cache for entity type {EntityType}", |
|||
typeof(TEntity).FullName |
|||
); |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
 |
|||
|
|||
This handler listens to entity change events and automatically clears related caches. The invalidation happens after the unit of work completes to ensure data consistency. |
|||
|
|||
### Step - 7: Configure AutoCache in Your Application |
|||
|
|||
Add the `AutoCacheModule` to your application module dependencies: |
|||
|
|||
```csharp |
|||
[DependsOn( |
|||
typeof(AutoCacheModule), // 👈 Add AutoCache module |
|||
typeof(AbpCachingStackExchangeRedisModule), |
|||
// ... other modules |
|||
)] |
|||
public class YourApplicationModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
Configure<AutoCacheOptions>(options => |
|||
{ |
|||
options.Enabled = true; // 👈 Enable caching |
|||
options.DefaultAbsoluteExpirationRelativeToNow = 3600000; // 1 hour |
|||
options.DefaultSlidingExpiration = 600000; // 10 minutes |
|||
options.ThrowOnError = false; // Fallback to method execution on cache errors |
|||
}); |
|||
|
|||
// Configure Redis (if using distributed cache) |
|||
Configure<AbpDistributedCacheOptions>(options => |
|||
{ |
|||
options.KeyPrefix = "YourApp:"; |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Step - 8: Use Automatic Caching in Application Services |
|||
|
|||
Now comes the easy part - using automatic caching! Simply add the `[Cache]` attribute to your methods: |
|||
|
|||
```csharp |
|||
using AutoCache; |
|||
|
|||
[Authorize(AutoCacheDemoPermissions.Books.Default)] |
|||
public class BookAppService : ApplicationService, IBookAppService |
|||
{ |
|||
private readonly IRepository<Book, Guid> _repository; |
|||
private readonly AutoCacheManager _autoCacheManager; |
|||
|
|||
public BookAppService(IRepository<Book, Guid> repository, AutoCacheManager autoCacheManager) |
|||
{ |
|||
_repository = repository; |
|||
_autoCacheManager = autoCacheManager; |
|||
} |
|||
|
|||
// Cache this method, invalidate when Book entity changes |
|||
[Cache(typeof(Book), Scope = AutoCacheScope.Global)] |
|||
public virtual async Task<BookDto> GetAsync(Guid id) |
|||
{ |
|||
// You can also use AutoCacheManager directly for nested caching |
|||
var book = await _autoCacheManager.GetOrAddAsync( |
|||
this, |
|||
async () => await _repository.GetAsync(id), |
|||
[id], // 👈 Method parameters |
|||
invalidateOnEntities: [typeof(Book)], |
|||
scope: AutoCacheScope.Entity); |
|||
|
|||
return ObjectMapper.Map<Book, BookDto>(book!); |
|||
} |
|||
|
|||
// Cache book list, invalidate when any Book changes |
|||
[Cache(typeof(Book))] |
|||
public virtual async Task<PagedResultDto<BookDto>> GetListAsync(PagedAndSortedResultRequestDto input) |
|||
{ |
|||
var queryable = await _repository.GetQueryableAsync(); |
|||
var query = queryable |
|||
.OrderBy(input.Sorting.IsNullOrWhiteSpace() ? "Name" : input.Sorting) |
|||
.Skip(input.SkipCount) |
|||
.Take(input.MaxResultCount); |
|||
|
|||
var books = await AsyncExecuter.ToListAsync(query); |
|||
var totalCount = await AsyncExecuter.CountAsync(queryable); |
|||
|
|||
return new PagedResultDto<BookDto>( |
|||
totalCount, |
|||
ObjectMapper.Map<List<Book>, List<BookDto>>(books) |
|||
); |
|||
} |
|||
|
|||
// No caching on write operations |
|||
[Authorize(AutoCacheDemoPermissions.Books.Create)] |
|||
public async Task<BookDto> CreateAsync(CreateUpdateBookDto input) |
|||
{ |
|||
var book = ObjectMapper.Map<CreateUpdateBookDto, Book>(input); |
|||
await _repository.InsertAsync(book); // 👈 This will trigger cache invalidation |
|||
return ObjectMapper.Map<Book, BookDto>(book); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**What Happens Here:** |
|||
|
|||
1. When `GetAsync` is called, the interceptor checks the cache |
|||
2. On cache miss, the actual method executes and the result is cached |
|||
3. When `CreateAsync` inserts a `Book`, the invalidation handler clears all caches related to `Book` |
|||
4. Next call to `GetAsync` will fetch fresh data |
|||
|
|||
## Advanced Features |
|||
|
|||
### User-Specific Caching |
|||
|
|||
For user-specific data, use `AutoCacheScope.CurrentUser`: |
|||
|
|||
```csharp |
|||
[Cache(typeof(Order), Scope = AutoCacheScope.CurrentUser)] |
|||
public virtual async Task<List<OrderDto>> GetMyOrdersAsync() |
|||
{ |
|||
var orders = await _orderRepository.GetListAsync(x => x.UserId == CurrentUser.Id); |
|||
return ObjectMapper.Map<List<Order>, List<OrderDto>>(orders); |
|||
} |
|||
``` |
|||
|
|||
Each user gets their own cache entry, automatically invalidated when their orders change. |
|||
|
|||
### Custom Cache Keys |
|||
|
|||
For fine-grained control, add custom cache key segments: |
|||
|
|||
```csharp |
|||
[Cache( |
|||
typeof(Product), |
|||
Scope = AutoCacheScope.Global, |
|||
AdditionalCacheKey = "featured" |
|||
)] |
|||
public virtual async Task<List<ProductDto>> GetFeaturedProductsAsync() |
|||
{ |
|||
// Only featured products are cached separately |
|||
return await GetProductsByCategoryAsync("Featured"); |
|||
} |
|||
``` |
|||
|
|||
### Performance Metrics |
|||
|
|||
Monitor cache performance using `IAutoCacheMetrics`: |
|||
|
|||
```csharp |
|||
public class CacheMonitoringService : ITransientDependency |
|||
{ |
|||
private readonly IAutoCacheMetrics _metrics; |
|||
|
|||
public CacheMonitoringService(IAutoCacheMetrics metrics) |
|||
{ |
|||
_metrics = metrics; |
|||
} |
|||
|
|||
public AutoCacheStatistics GetStatistics() |
|||
{ |
|||
return _metrics.GetStatistics(); // 👈 Get hit rate, miss count, error count |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Testing the Application |
|||
|
|||
### 1. Run the Application |
|||
|
|||
```bash |
|||
abp new BookStore -u mvc -d ef |
|||
cd BookStore |
|||
dotnet run --project src/BookStore.Web |
|||
``` |
|||
|
|||
### 2. Test Cache Behavior |
|||
|
|||
Create a simple test to verify caching: |
|||
|
|||
```csharp |
|||
[Fact] |
|||
public async Task Should_Cache_Book_Results() |
|||
{ |
|||
// First call - cache miss |
|||
var book1 = await _bookAppService.GetAsync(testBookId); |
|||
|
|||
// Second call - cache hit (should be faster) |
|||
var book2 = await _bookAppService.GetAsync(testBookId); |
|||
|
|||
book1.Name.ShouldBe(book2.Name); |
|||
} |
|||
|
|||
[Fact] |
|||
public async Task Should_Invalidate_Cache_On_Update() |
|||
{ |
|||
// Cache the book |
|||
var book1 = await _bookAppService.GetAsync(testBookId); |
|||
|
|||
// Update the book |
|||
await _bookAppService.UpdateAsync(testBookId, new CreateUpdateBookDto |
|||
{ |
|||
Name = "Updated Name" |
|||
}); |
|||
|
|||
// Fetch again - should get updated data (cache was invalidated) |
|||
var book2 = await _bookAppService.GetAsync(testBookId); |
|||
|
|||
book2.Name.ShouldBe("Updated Name"); |
|||
} |
|||
``` |
|||
|
|||
### 3. Monitor Cache Performance |
|||
|
|||
Check your application logs for cache metrics: |
|||
|
|||
``` |
|||
[INF] Cache Hit: BookAppService:GetAsync:book-id-123 (Response Time: 5ms) |
|||
[INF] Cache Miss: BookAppService:GetListAsync (Response Time: 156ms) |
|||
[INF] Cache Invalidation: Book entity changed, cleared 3 cache entries |
|||
``` |
|||
|
|||
## Key Takeaways |
|||
|
|||
✅ **Automatic caching reduces boilerplate code** - Just add `[Cache]` attribute to methods instead of manual cache management |
|||
|
|||
✅ **Smart invalidation keeps data fresh** - Entity changes automatically clear related caches without manual intervention |
|||
|
|||
✅ **Multiple scoping options** - Support for global, user-specific, authenticated, and entity-level caching strategies |
|||
|
|||
✅ **Built-in fallback handling** - Gracefully falls back to method execution if caching fails |
|||
|
|||
✅ **Performance monitoring** - Track cache hits, misses, and errors for optimization |
|||
|
|||
## Conclusion |
|||
|
|||
Automatic method-level caching dramatically simplifies performance optimization in ABP Framework applications. By using attributes and interceptors, you can add sophisticated caching behavior without cluttering your business logic with cache management code. |
|||
|
|||
The system we've built provides intelligent cache invalidation, multiple scoping strategies, and built-in monitoring - all while maintaining clean, readable code. Whether you're building a small application or an enterprise system, this approach scales elegantly and integrates seamlessly with ABP's architecture. |
|||
|
|||
Ready to implement this in your project? The complete working implementation is available in the [AbpAutoCacheDemo repository](https://github.com/salihozkara/AbpAutoCacheDemo). You can clone the repository, explore the code, and even extract the `src/AutoCache` folder to use it as a standalone library in your own ABP applications. The [main implementation commit](https://github.com/salihozkara/AbpAutoCacheDemo/commit/946df1fc07de6eddd26eb14013a09968cd59329b) shows all the components working together, including interceptor registration, cache key management, and automatic invalidation handlers.r you're building a small application or an enterprise system, this approach scales elegantly and integrates seamlessly with ABP's architecture. |
|||
|
|||
Ready to implement this in your project? Check out the complete working example in the repository linked below, and start improving your application's performance today! |
|||
|
|||
### See Also |
|||
|
|||
- [ABP Caching Documentation](https://abp.io/docs/latest/framework/fundamentals/caching) |
|||
- [Interceptors in ABP](https://abp.io/docs/latest/framework/infrastructure/interceptors) |
|||
- [Event Bus Documentation](https://abp.io/docs/latest/framework/infrastructure/event-bus) |
|||
- [Sample Project on GitHub](https://github.com/salihozkara/AbpAutoCacheDemo) |
|||
|
|||
--- |
|||
|
|||
## References |
|||
|
|||
- [ABP Framework Documentation](https://docs.abp.io) |
|||
- [Redis Distributed Caching](https://redis.io/docs/) |
|||
- [Aspect-Oriented Programming Patterns](https://en.wikipedia.org/wiki/Aspect-oriented_programming) |
|||
@ -0,0 +1 @@ |
|||
Learn how to implement automatic method-level caching in ABP Framework using attributes and interceptors. This comprehensive guide covers building a reusable cache infrastructure with attribute-based caching, intelligent cache invalidation when entities change, support for multiple cache scopes (Global, CurrentUser, AuthenticatedUser, and Entity), seamless integration with ABP's dynamic proxy system and event bus, and built-in performance metrics for monitoring cache effectiveness in production applications. |
|||
@ -1,307 +0,0 @@ |
|||
# Artificial Intelligence |
|||
|
|||
ABP provides a simple way to integrate AI capabilities into your applications by unifying two popular .NET AI stacks under a common concept called a "workspace": |
|||
|
|||
- Microsoft.Extensions.AI `IChatClient` |
|||
- Microsoft.SemanticKernel `Kernel` |
|||
|
|||
A workspace is just a named scope. You configure providers per workspace and then resolve either default services (for the "Default" workspace) or workspace-scoped services. |
|||
|
|||
## Installation |
|||
|
|||
> This package is not included by default. Install it to enable AI features. |
|||
|
|||
It is suggested to use the ABP CLI to install the package. Open a command line window in the folder of the project (.csproj file) and type the following command: |
|||
|
|||
```bash |
|||
abp add-package Volo.Abp.AI |
|||
``` |
|||
|
|||
### Manual Installation |
|||
|
|||
Add nuget package to your project: |
|||
|
|||
```bash |
|||
dotnet add package Volo.Abp.AI |
|||
``` |
|||
|
|||
Then add the module dependency to your module class: |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
using Volo.Abp.Modularity; |
|||
|
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
## Usage |
|||
|
|||
### Chat Client |
|||
|
|||
#### Default configuration (quick start) |
|||
|
|||
Configure the default workspace to inject `IChatClient` directly. |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
using Microsoft.SemanticKernel; |
|||
using Volo.Abp.AI; |
|||
using Volo.Abp.Modularity; |
|||
|
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
}); |
|||
|
|||
// Chat client only in this quick start |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Once configured, inject the default chat client: |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
|
|||
public class MyService |
|||
{ |
|||
private readonly IChatClient _chatClient; // default chat client |
|||
|
|||
public MyService(IChatClient chatClient) |
|||
{ |
|||
_chatClient = chatClient; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### Workspace configuration |
|||
|
|||
Workspaces allow multiple, isolated AI configurations. Define workspace types (optionally decorated with `WorkspaceNameAttribute`). If omitted, the type’s full name is used. |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
|
|||
[WorkspaceName("GreetingAssistant")] |
|||
public class GreetingAssistant // ChatClient-only workspace |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
Configure a ChatClient workspace: |
|||
|
|||
```csharp |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<GreetingAssistant>(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
|
|||
chatClientConfiguration.BuilderConfigurers.Add(builder => |
|||
{ |
|||
// Anything you want to do with the builder: |
|||
// builder.UseFunctionInvocation().UseLogging(); // For example |
|||
}); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Semantic Kernel |
|||
|
|||
#### Default configuration |
|||
|
|||
|
|||
```csharp |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddAzureOpenAIChatClient("...", "..."); |
|||
}); |
|||
// Note: Chat client is not configured here |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Once configured, inject the default kernel: |
|||
|
|||
```csharp |
|||
using System.Threading.Tasks; |
|||
using Volo.Abp.AI; |
|||
|
|||
public class MyService |
|||
{ |
|||
private readonly IKernelAccessor _kernelAccessor; |
|||
public MyService(IKernelAccessor kernelAccessor) |
|||
{ |
|||
_kernelAccessor = kernelAccessor; |
|||
} |
|||
|
|||
public async Task DoSomethingAsync() |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; // Kernel might be null if no workspace is configured. |
|||
|
|||
var result = await kernel.InvokeAsync(/*... */); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### Workspace configuration |
|||
|
|||
```csharp |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<ContentPlanner>(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddOpenAIChatCompletion("...", "..."); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### Workspace usage |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
using Volo.Abp.AI; |
|||
using Microsoft.SemanticKernel; |
|||
|
|||
public class PlanningService |
|||
{ |
|||
private readonly IKernelAccessor<ContentPlanner> _kernelAccessor; |
|||
private readonly IChatClient<ContentPlanner> _chatClient; // available even if only Kernel is configured |
|||
|
|||
public PlanningService( |
|||
IKernelAccessor<ContentPlanner> kernelAccessor, |
|||
IChatClient<ContentPlanner> chatClient) |
|||
{ |
|||
_kernelAccessor = kernelAccessor; |
|||
_chatClient = chatClient; |
|||
} |
|||
|
|||
public async Task<string> PlanAsync(string topic) |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; // Microsoft.SemanticKernel.Kernel |
|||
// Use Semantic Kernel APIs if needed... |
|||
|
|||
var response = await _chatClient.GetResponseAsync( |
|||
[new ChatMessage(ChatRole.User, $"Create a content plan for: {topic}")] |
|||
); |
|||
return response?.Message?.Text ?? string.Empty; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Options |
|||
|
|||
`AbpAIOptions` configuration pattern offers `ConfigureChatClient(...)` and `ConfigureKernel(...)` methods for configuration. These methods are defined in the `WorkspaceConfiguration` class. They are used to configure the `ChatClient` and `Kernel` respectively. |
|||
|
|||
`Builder` is set once and is used to build the `ChatClient` or `Kernel` instance. `BuilderConfigurers` is a list of actions that are applied to the `Builder` instance for incremental changes. These actions are executed in the order they are added. |
|||
|
|||
If a workspace configures only the Kernel, a chat client may still be exposed for that workspace through the Kernel’s service provider (when available). |
|||
|
|||
|
|||
## Advanced Usage and Customizations |
|||
|
|||
### Addding Your Own DelegatingChatClient |
|||
|
|||
If you want to build your own decorator, implement a `DelegatingChatClient` derivative and provide an extension method that adds it to the `ChatClientBuilder` using `builder.Use(...)`. |
|||
|
|||
Example sketch: |
|||
|
|||
```csharp |
|||
using Microsoft.Extensions.AI; |
|||
|
|||
public class SystemMessageChatClient : DelegatingChatClient |
|||
{ |
|||
public SystemMessageChatClient(IChatClient inner, string systemMessage) : base(inner) |
|||
{ |
|||
SystemMessage = systemMessage; |
|||
} |
|||
|
|||
public string SystemMessage { get; set; } |
|||
|
|||
public override Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default) |
|||
{ |
|||
// Mutate messages/options as needed, then call base |
|||
return base.GetResponseAsync(messages, options, cancellationToken); |
|||
} |
|||
} |
|||
|
|||
public static class SystemMessageChatClientExtensions |
|||
{ |
|||
public static ChatClientBuilder UseSystemMessage(this ChatClientBuilder builder, string systemMessage) |
|||
{ |
|||
return builder.Use(client => new SystemMessageChatClient(client, systemMessage)); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
|
|||
```cs |
|||
chatClientConfiguration.BuilderConfigurers.Add(builder => |
|||
{ |
|||
builder.UseSystemMessage("You are a helpful assistant that greets users in a friendly manner with their names."); |
|||
}); |
|||
``` |
|||
|
|||
## Technical Anatomy |
|||
|
|||
- `AbpAIModule`: Wires up configured workspaces, registers keyed services and default services for the `"Default"` workspace. |
|||
- `AbpAIOptions`: Holds `Workspaces` and provides helper methods for internal keyed service naming. |
|||
- `WorkspaceConfigurationDictionary` and `WorkspaceConfiguration`: Configure per-workspace Chat Client and Kernel. |
|||
- `ChatClientConfiguration` and `KernelConfiguration`: Hold builders and a list of ordered builder configurers. |
|||
- `WorkspaceNameAttribute`: Names a workspace; falls back to the type’s full name if not specified. |
|||
- `IChatClient<TWorkspace>`: Typed chat client for a workspace. |
|||
- `IKernelAccessor<TWorkspace>`: Provides access to the workspace’s `Kernel` instance if configured. |
|||
- `AbpAIWorkspaceOptions`: Exposes `ConfiguredWorkspaceNames` for diagnostics. |
|||
|
|||
There are no database tables for this feature; it is a pure configuration and DI integration layer. |
|||
|
|||
## See Also |
|||
|
|||
- Microsoft.Extensions.AI (Chat Client) |
|||
- Microsoft Semantic Kernel |
|||
@ -0,0 +1,38 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Explore ABP Framework's AI integration, enabling seamless AI capabilities, workspace management, and reusable modules for .NET developers." |
|||
} |
|||
``` |
|||
|
|||
# Artificial Intelligence (AI) |
|||
ABP Framework provides integration for AI capabilities to your application by using Microsoft's popular AI libraries. The main purpose of this integration is to provide a consistent and easy way to use AI capabilities and manage different AI providers, models and configurations in a single application. |
|||
|
|||
ABP introduces a concept called **AI Workspace**. A workspace allows you to configure isolated AI configurations for a named scope. You can then resolve AI services for a specific workspace when you need to use them. |
|||
|
|||
> ABP Framework can work with any AI library or framework that supports .NET development. However, the AI integration features explained in the following documents provide a modular and standard way to work with AI, which allows ABP developers to create reusable modules and components with AI capabilities in a standard way. |
|||
|
|||
## Installation |
|||
|
|||
Use the [ABP CLI](../../../cli/index.md) to install the [Volo.Abp.AI](https://www.nuget.org/packages/Volo.Abp.AI) NuGet package into your project. Open a command line window in the root directory of your project (`.csproj` file) and type the following command: |
|||
|
|||
```bash |
|||
abp add-package Volo.Abp.AI |
|||
``` |
|||
|
|||
*For different installation options, check [the package definition page](https://abp.io/package-detail/Volo.Abp.AI).* |
|||
|
|||
## Usage |
|||
|
|||
The `Volo.Abp.AI` package provides integration with the following libraries: |
|||
|
|||
* [Microsoft.Extensions.AI](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai) |
|||
* [Microsoft.SemanticKernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) |
|||
|
|||
The Microsoft.Extensions.AI library is suggested for library developers to keep the library dependency minimum and simple (since it provides basic abstractions and fundamental AI provider integrations), while Semantic Kernel is suggested for applications that need rich and advanced AI integration features. |
|||
|
|||
Check the following documentation to learn how to use these libraries with the ABP integration: |
|||
|
|||
- [ABP Microsoft.Extensions.AI integration](./microsoft-extensions-ai.md) |
|||
- [ABP Microsoft.SemanticKernel integration](./microsoft-semantic-kernel.md) |
|||
|
|||
@ -0,0 +1,176 @@ |
|||
# Microsoft.Extensions.AI |
|||
[Microsoft.Extensions.AI](https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai) is a library that provides a unified API for integrating AI services. It is a part of the Microsoft AI Extensions Library. It is used to integrate AI services into your application. This documentation is about the usage of this library with ABP Framework. Make sure you have read the [Artificial Intelligence](./index.md) documentation before reading this documentation. |
|||
|
|||
## Usage |
|||
|
|||
You can resolve `IChatClient` to access configured chat client from your service and use it directly. |
|||
|
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClient _chatClient; |
|||
public MyService(IChatClient chatClient) |
|||
{ |
|||
_chatClient = chatClient; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
return await _chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can also resolve `IChatClientAccessor` to access the `IChatClient` optionally configured scenarios such as developing a module or a service that may use AI capabilities **optionally**. |
|||
|
|||
|
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClientAccessor _chatClientAccessor; |
|||
public MyService(IChatClientAccessor chatClientAccessor) |
|||
{ |
|||
_chatClientAccessor = chatClientAccessor; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var chatClient = _chatClientAccessor.ChatClient; |
|||
if (chatClient is null) |
|||
{ |
|||
return "No chat client configured"; |
|||
} |
|||
return await chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Workspaces |
|||
|
|||
Workspaces are a way to configure isolated AI configurations for a named scope. You can define a workspace by decorating a class with the `WorkspaceNameAttribute` attribute that carries the workspace name. |
|||
- Workspace names must be unique. |
|||
- Workspace names cannot contain spaces _(use underscores or camelCase)_. |
|||
- Workspace names are case-sensitive. |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
|
|||
[WorkspaceName("CommentSummarization")] |
|||
public class CommentSummarization |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
> [!NOTE] |
|||
> If you don't specify the workspace name, the full name of the class will be used as the workspace name. |
|||
|
|||
You can resolve generic versions of `IChatClient` and `IChatClientAccessor` services for a specific workspace as generic arguments. If Chat Client is not configured for a workspace, you will get `null` from the accessor services. You should check the accessor before using it. This applies only for specified workspaces. Another workspace may have a configured Chat Client. |
|||
|
|||
`IChatClient<TWorkSpace>` or `IChatClientAccessor<TWorkSpace>` can be resolved to access a specific workspace's chat client. This is a typed chat client and can be configured separately from the default chat client. |
|||
|
|||
|
|||
Example of resolving a typed chat client: |
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClient<CommentSummarization> _chatClient; |
|||
|
|||
public MyService(IChatClient<CommentSummarization> chatClient) |
|||
{ |
|||
_chatClient = chatClient; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
return await _chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Example of resolving a typed chat client accessor: |
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IChatClientAccessor<CommentSummarization> _chatClientAccessor; |
|||
} |
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var chatClient = _chatClientAccessor.ChatClient; |
|||
if (chatClient is null) |
|||
{ |
|||
return "No chat client configured"; |
|||
} |
|||
return await chatClient.GetResponseAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Configuration |
|||
|
|||
`AbpAIWorkspaceOptions` configuration is used to configure AI workspaces and their configurations. You can configure the default workspace and also configure isolated workspaces by using the this options class.It has to be configured **before the services are configured** in the `PreConfigure` method of your module class. It is important since the services are registered after the configuration is applied. |
|||
|
|||
- `AbpAIWorkspaceOptions` has a `Workspaces` property that is type of `WorkspaceConfigurationDictionary` which is a dictionary of workspace names and their configurations. It provides `Configure<T>` and `ConfigureDefault` methods to configure the default workspace and also configure isolated workspaces by using the workspace type. |
|||
|
|||
- Configure method passes `WorkspaceConfiguration` object to the configure action. You can configure the `ChatClient` by using the `ConfigureChatClient` method. |
|||
|
|||
- `ConfigureChatClient()` method passes `ChatClientConfiguration` parameter to the configure action. You can configure the `Builder` and `BuilderConfigurers` by using the `ConfigureBuilder` method. |
|||
- `Builder` is set once and is used to build the `ChatClient` instance. |
|||
- `BuilderConfigurers` is a list of actions that are applied to the `Builder` instance for incremental changes.These actions are executed in the order they are added. |
|||
|
|||
To configure a chat client, you'll need a LLM provider package such as [Microsoft.Extensions.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) or [OllamaSharp](https://www.nuget.org/packages/OllamaSharp/) to configure a chat client. |
|||
|
|||
_The following example requires [OllamaSharp](https://www.nuget.org/packages/OllamaSharp/) package to be installed._ |
|||
|
|||
|
|||
Demonstration of the default workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIWorkspaceOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
|
|||
Demonstration of the isolated workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIWorkspaceOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<CommentSummarization>(configuration => |
|||
{ |
|||
configuration.ConfigureChatClient(chatClientConfiguration => |
|||
{ |
|||
chatClientConfiguration.Builder = new ChatClientBuilder( |
|||
sp => new OllamaApiClient("http://localhost:11434", "mistral") |
|||
); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
|
|||
## See Also |
|||
|
|||
- [Usage of Semantic Kernel](./microsoft-semantic-kernel.md) |
|||
- [AI Samples for .NET](https://learn.microsoft.com/en-us/samples/dotnet/ai-samples/ai-samples/) |
|||
@ -0,0 +1,135 @@ |
|||
# Microsoft.SemanticKernel |
|||
[Microsoft.SemanticKernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) is a library that provides a unified SDK for integrating AI services. This documentation is about the usage of this library with ABP Framework. Make sure you have read the [Artificial Intelligence](./index.md) documentation before reading this documentation. |
|||
|
|||
## Usage |
|||
|
|||
Semantic Kernel can be used by resolving `IKernelAccessor` service that carries the `Kernel` instance. Kernel might be `null` if no workspace is configured. You should check the kernel before using it. |
|||
|
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IKernelAccessor _kernelAccessor; |
|||
public MyService(IKernelAccessor kernelAccessor) |
|||
{ |
|||
_kernelAccessor = kernelAccessor; |
|||
} |
|||
|
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; |
|||
if (kernel is null) |
|||
{ |
|||
return "No kernel configured"; |
|||
} |
|||
return await kernel.InvokeAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Workspaces |
|||
|
|||
Workspaces are a way to configure isolated AI configurations for a named scope. You can define a workspace by decorating a class with the `WorkspaceNameAttribute` attribute that carries the workspace name. |
|||
- Workspace names must be unique. |
|||
- Workspace names cannot contain spaces _(use underscores or camelCase)_. |
|||
- Workspace names are case-sensitive. |
|||
|
|||
```csharp |
|||
using Volo.Abp.AI; |
|||
|
|||
[WorkspaceName("CommentSummarization")] |
|||
public class CommentSummarization |
|||
{ |
|||
} |
|||
``` |
|||
|
|||
> [!NOTE] |
|||
> If you don't specify the workspace name, the full name of the class will be used as the workspace name. |
|||
|
|||
You can resolve generic versions of `IKernelAccessor` service for a specific workspace as generic arguments. If Kernel is not configured for a workspace, you will get `null` from the accessor service. You should check the accessor before using it. This applies only for specified workspaces. Another workspace may have a configured Kernel. |
|||
|
|||
|
|||
`IKernelAccessor<TWorkSpace>` can be resolved to access a specific workspace's kernel. This is a typed kernel accessor and each workspace can have its own kernel configuration. |
|||
|
|||
Example of resolving a typed kernel accessor: |
|||
```csharp |
|||
public class MyService |
|||
{ |
|||
private readonly IKernelAccessor<CommentSummarization> _kernelAccessor; |
|||
} |
|||
public async Task<string> GetResponseAsync(string prompt) |
|||
{ |
|||
var kernel = _kernelAccessor.Kernel; |
|||
if (kernel is null) |
|||
{ |
|||
return "No kernel configured"; |
|||
} |
|||
return await kernel.InvokeAsync(prompt); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Configuration |
|||
|
|||
`AbpAIWorkspaceOptions` configuration is used to configure AI workspaces and their configurations. You can configure the default workspace and also configure isolated workspaces by using the this options class.It has to be configured **before the services are configured** in the `PreConfigure` method of your module class. It is important since the services are registered after the configuration is applied. |
|||
|
|||
- `AbpAIWorkspaceOptions` has a `Workspaces` property that is type of `WorkspaceConfigurationDictionary` which is a dictionary of workspace names and their configurations. It provides `Configure<T>` and `ConfigureDefault` methods to configure the default workspace and also configure isolated workspaces by using the workspace type. |
|||
|
|||
- Configure method passes `WorkspaceConfiguration` object to the configure action. You can configure the `Kernel` by using the `ConfigureKernel` method. |
|||
|
|||
- `ConfigureKernel()` method passes `KernelConfiguration` parameter to the configure action. You can configure the `Builder` and `BuilderConfigurers` by using the `ConfigureBuilder` method. |
|||
- `Builder` is set once and is used to build the `Kernel` instance. |
|||
- `BuilderConfigurers` is a list of actions that are applied to the `Builder` instance for incremental changes.These actions are executed in the order they are added. |
|||
|
|||
To configure a kernel, you'll need a kernel connector package such as [Microsoft.SemanticKernel.Connectors.OpenAI](Microsoft.SemanticKernel.Connectors.OpenAI) to configure a kernel to use a specific LLM provider. |
|||
|
|||
_The following example requires [Microsoft.SemanticKernel.Connectors.AzureOpenAI](Microsoft.SemanticKernel.Connectors.AzureOpenAI) package to be installed._ |
|||
|
|||
Demonstration of the default workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.ConfigureDefault(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddAzureOpenAIChatClient("...", "..."); |
|||
}); |
|||
// Note: Chat client is not configured here |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Demonstration of the isolated workspace configuration: |
|||
```csharp |
|||
[DependsOn(typeof(AbpAIModule))] |
|||
public class MyProjectModule : AbpModule |
|||
{ |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
PreConfigure<AbpAIOptions>(options => |
|||
{ |
|||
options.Workspaces.Configure<CommentSummarization>(configuration => |
|||
{ |
|||
configuration.ConfigureKernel(kernelConfiguration => |
|||
{ |
|||
kernelConfiguration.Builder = Kernel.CreateBuilder() |
|||
.AddAzureOpenAIChatClient("...", "..."); |
|||
}); |
|||
}); |
|||
}); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## See Also |
|||
|
|||
- [Usage of Microsoft.Extensions.AI](./microsoft-extensions-ai.md) |
|||
- [AI Samples for .NET](https://learn.microsoft.com/en-us/samples/dotnet/ai-samples/ai-samples/) |
|||
@ -0,0 +1,280 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how to configure Server-Side Rendering (SSR) for your Angular application in the ABP Framework to improve performance and SEO." |
|||
} |
|||
``` |
|||
|
|||
# SSR Configuration |
|||
|
|||
[Server-Side Rendering (SSR)](https://angular.io/guide/ssr) is a process that involves rendering pages on the server, resulting in initial HTML content that contains the page state. This allows the browser to show the page to the user immediately, before the JavaScript bundles are downloaded and executed. |
|||
|
|||
SSR improves the **performance** (First Contentful Paint) and **SEO** (Search Engine Optimization) of your application. |
|||
|
|||
## 1. Install ABP Angular SSR |
|||
|
|||
The ABP Framework provides a schematic to easily add SSR support to your Angular application. |
|||
|
|||
Run the following command in the root folder of your Angular application: |
|||
|
|||
```shell |
|||
yarn ng generate @abp/ng.schematics:ssr-add |
|||
``` |
|||
|
|||
Alternatively, you can specify the project name if you have a multi-project workspace: |
|||
|
|||
```shell |
|||
yarn ng generate @abp/ng.schematics:ssr-add --project MyProjectName |
|||
``` |
|||
|
|||
This command automates the setup process by installing necessary dependencies, creating server-side entry points, and updating your configuration files. |
|||
|
|||
## 2. What Changes? |
|||
|
|||
When you run the schematic, it performs the following actions: |
|||
|
|||
### 2.1. Dependencies |
|||
|
|||
It adds the following packages to your `package.json`: |
|||
|
|||
- **express**: A minimal and flexible Node.js web application framework. |
|||
- **@types/express**: Type definitions for Express. |
|||
- **openid-client**: A library for OpenID Connect (OIDC) relying party (RP) implementation, used for authentication on the server. |
|||
|
|||
```json |
|||
{ |
|||
"dependencies": { |
|||
"express": "^4.18.2", |
|||
"openid-client": "^5.6.4" |
|||
}, |
|||
"devDependencies": { |
|||
"@types/express": "^4.17.17" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**For Webpack projects only:** |
|||
- **browser-sync** (Dev dependency): Used for live reloading during development. |
|||
|
|||
### 2.2. Scripts & Configuration |
|||
|
|||
The changes depend on the builder used in your project (Application Builder or Webpack). |
|||
|
|||
#### Application Builder (esbuild) |
|||
|
|||
If your project uses the **Application Builder** (`@angular/build:application`), the schematic: |
|||
|
|||
- **Scripts**: Adds `serve:ssr:project-name` to serve the SSR application. |
|||
- **angular.json**: Updates the `build` target to enable SSR (`outputMode: 'server'`) and sets the SSR entry point. |
|||
|
|||
```json |
|||
{ |
|||
"projects": { |
|||
"MyProjectName": { |
|||
"architect": { |
|||
"build": { |
|||
"options": { |
|||
"outputPath": "dist/MyProjectName", |
|||
"outputMode": "server", |
|||
"ssr": { |
|||
"entry": "src/server.ts" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
- **tsconfig**: Updates the application's `tsconfig` to include `server.ts`. |
|||
|
|||
#### Webpack Builder |
|||
|
|||
If your project uses the **Webpack Builder** (`@angular-devkit/build-angular:browser`), the schematic: |
|||
|
|||
- **Scripts**: Adds `dev:ssr`, `serve:ssr`, `build:ssr`, and `prerender` scripts. |
|||
- **angular.json**: Adds new targets: `server`, `serve-ssr`, and `prerender`. |
|||
- **tsconfig**: Updates the server's `tsconfig` to include `server.ts`. |
|||
|
|||
### 2.3. Files |
|||
|
|||
- **server.ts**: This file is the main entry point for the server-side application. |
|||
- **Standalone Projects**: Generates a server entry point compatible with `bootstrapApplication`. |
|||
- **NgModule Projects**: Generates a server entry point compatible with `platformBrowserDynamic`. |
|||
|
|||
```typescript |
|||
import { |
|||
AngularNodeAppEngine, |
|||
createNodeRequestHandler, |
|||
isMainModule, |
|||
writeResponseToNodeResponse, |
|||
} from '@angular/ssr/node'; |
|||
import express from 'express'; |
|||
import { dirname, resolve } from 'node:path'; |
|||
import { fileURLToPath } from 'node:url'; |
|||
import { environment } from './environments/environment'; |
|||
import { ServerCookieParser } from '@abp/ng.core'; |
|||
import * as oidc from 'openid-client'; |
|||
|
|||
// ... (OIDC configuration and setup) |
|||
|
|||
const app = express(); |
|||
const angularApp = new AngularNodeAppEngine(); |
|||
|
|||
// ... (OIDC routes: /authorize, /logout, /) |
|||
|
|||
/** |
|||
* Serve static files from /browser |
|||
*/ |
|||
app.use( |
|||
express.static(browserDistFolder, { |
|||
maxAge: '1y', |
|||
index: false, |
|||
redirect: false, |
|||
}), |
|||
); |
|||
|
|||
/** |
|||
* Handle all other requests by rendering the Angular application. |
|||
*/ |
|||
app.use((req, res, next) => { |
|||
angularApp |
|||
.handle(req) |
|||
.then(response => { |
|||
if (response) { |
|||
res.cookie('ssr-init', 'true', {...secureCookie, httpOnly: false}); |
|||
return writeResponseToNodeResponse(response, res); |
|||
} else { |
|||
return next() |
|||
} |
|||
}) |
|||
.catch(next); |
|||
}); |
|||
|
|||
// ... (Start server logic) |
|||
|
|||
export const reqHandler = createNodeRequestHandler(app); |
|||
``` |
|||
- **app.routes.server.ts**: Defines server-side routes and render modes (e.g., Prerender, Server, Client). This allows fine-grained control over how each route is rendered. |
|||
|
|||
```typescript |
|||
import { RenderMode, ServerRoute } from '@angular/ssr'; |
|||
|
|||
export const serverRoutes: ServerRoute[] = [ |
|||
{ |
|||
path: '**', |
|||
renderMode: RenderMode.Server |
|||
} |
|||
]; |
|||
``` |
|||
|
|||
- **app.config.server.ts**: Merges the application configuration with server-specific providers. |
|||
|
|||
```typescript |
|||
import { mergeApplicationConfig, ApplicationConfig, provideAppInitializer, inject, PLATFORM_ID, TransferState } from '@angular/core'; |
|||
import { isPlatformServer } from '@angular/common'; |
|||
import { provideServerRendering, withRoutes } from '@angular/ssr'; |
|||
import { appConfig } from './app.config'; |
|||
import { serverRoutes } from './app.routes.server'; |
|||
import { SSR_FLAG } from '@abp/ng.core'; |
|||
|
|||
const serverConfig: ApplicationConfig = { |
|||
providers: [ |
|||
provideAppInitializer(() => { |
|||
const platformId = inject(PLATFORM_ID); |
|||
const transferState = inject<TransferState>(TransferState); |
|||
if (isPlatformServer(platformId)) { |
|||
transferState.set(SSR_FLAG, true); |
|||
} |
|||
}), |
|||
provideServerRendering(withRoutes(serverRoutes)), |
|||
], |
|||
}; |
|||
|
|||
export const config = mergeApplicationConfig(appConfig, serverConfig); |
|||
``` |
|||
- **index.html**: Removes the loading spinner (`<div id="lp-page-loader"></div>`) to prevent hydration mismatches. |
|||
|
|||
## 3. Running the Application |
|||
|
|||
After the installation is complete, you can run your application with SSR support. |
|||
|
|||
### Application Builder |
|||
|
|||
To serve the application with SSR in development: |
|||
|
|||
```shell |
|||
yarn start |
|||
# or |
|||
yarn ng serve |
|||
``` |
|||
|
|||
To serve the built application (production): |
|||
|
|||
```shell |
|||
yarn run serve:ssr:project-name |
|||
``` |
|||
|
|||
### Webpack Builder |
|||
|
|||
**Development:** |
|||
|
|||
```shell |
|||
yarn run dev:ssr |
|||
``` |
|||
|
|||
**Production:** |
|||
|
|||
```shell |
|||
yarn run build:ssr |
|||
yarn run serve:ssr |
|||
``` |
|||
|
|||
## 4. Authentication & SSR |
|||
|
|||
The schematic installs `openid-client` to handle authentication on the server side. This ensures that when a user accesses a protected route, the server can validate their session or redirect them to the login page before rendering the content. |
|||
|
|||
> Ensure your OpenID Connect configuration (in `environment.ts` or `app.config.ts`) is compatible with the server environment. |
|||
|
|||
## 5. Deployment |
|||
|
|||
To deploy your Angular SSR application to a production server, follow these steps: |
|||
|
|||
### 5.1. Build the Application |
|||
|
|||
Run the build command to generate the production artifacts: |
|||
|
|||
```shell |
|||
yarn build |
|||
# or if using Webpack builder |
|||
yarn run build:ssr |
|||
``` |
|||
|
|||
### 5.2. Prepare Artifacts |
|||
|
|||
After the build is complete, you will find the output in the `dist` folder. |
|||
For the **Application Builder**, the output structure typically looks like this: |
|||
|
|||
``` |
|||
dist/MyProjectName/ |
|||
├── browser/ # Client-side bundles |
|||
└── server/ # Server-side bundles and entry point (server.mjs) |
|||
``` |
|||
|
|||
You need to copy the entire `dist/MyProjectName` folder to your server. |
|||
|
|||
### 5.3. Run the Server |
|||
|
|||
On your server, navigate to the folder where you copied the artifacts and run the server using Node.js: |
|||
|
|||
```shell |
|||
node server/server.mjs |
|||
``` |
|||
|
|||
> [!TIP] |
|||
> It is recommended to use a process manager like [PM2](https://pm2.keymetrics.io/) to keep your application alive and handle restarts. |
|||
|
|||
```shell |
|||
pm2 start server/server.mjs --name "my-app" |
|||
``` |
|||
|
Before Width: | Height: | Size: 407 KiB After Width: | Height: | Size: 559 KiB |
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 25 KiB |
|
After Width: | Height: | Size: 16 KiB |
|
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 41 KiB |
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue