When I use an AI coding agent, I do not only care about whether it can change files.

I care about what happens around those changes.

Which branch am I on? What exactly changed? Can I review the diff before I commit? Did I accidentally touch a file from another package? Is my branch behind the default branch? If a pull request already has feedback, can I bring that context back into the coding session without copying every comment by hand?

That is where Git integration in ABP Studio becomes important.

Git is not just the final step after the agent finishes. For me, it is the confidence layer around the whole workflow. It helps me keep AI-assisted work reviewable, recoverable, and connected to the same team process I already use every day.

Git In The AI Workflow

Most development work is not a straight line from prompt to done.

I may ask ABP Agent to make a small change, then review the diff and adjust the direction. I may ask it to address feedback from a pull request. I may start from a GitHub issue, create a branch, let the agent investigate, and then decide which changes are ready to commit.

In all of those moments, Git gives me a practical boundary:

• this is the branch I am working on,
• these are the files that changed,
• this is the diff I need to review,
• this is the commit I am about to create,
• and this is the context I want to send back to the team.

Without a Git-aware workflow, AI changes can feel a little too loose. The agent may be productive, but I still need a clean way to inspect, group, commit, push, and discuss the result.

ABP Studio Git Integration brings that loop into the same place where I already work with the solution and the agent.

Initializing Git For A Solution

The Git panel starts with the active solution.

If the solution is not a Git repository yet, ABP Studio does not pretend otherwise. It shows a simple empty state and lets me initialize Git from there. I can choose the initial branch name, create a .gitignore, and create the first commit.

That is useful for new ABP solutions because the first Git step is part of the project setup, not something I need to remember after the fact.

If I want to put the solution on GitHub, Studio can also help with that path. After connecting my GitHub account, I can publish the repository under my account or an organization, choose the repository name, add a description, and decide whether it should be private.

The small but important detail is that Git becomes part of the solution experience early. I do not need to move from ABP Studio to a separate Git tool just to create the repository before I start working with ABP Agent.

Changed Files And Diff Review

Once Git is active, the Git panel becomes the place I check after an agent session or a manual edit.

I can see the current branch, remote state, changed files, and the selected file diff. The changes are not only a flat list. In an ABP solution, they can be grouped in a way that follows the solution structure, so changes under different packages or solution areas are easier to scan.

That grouping matters in real ABP work.

If I asked ABP Agent to adjust a public web page, but I see changes in an admin package, I immediately know to slow down and review why. If a change touches a contract package and a UI package, the grouping helps me understand that relationship before I commit.

The diff viewer is also part of the same loop. I do not need to leave the workspace just to answer the basic review question:

What did this task actually change?

That is the question I want to answer before a commit, especially when AI helped produce the diff.

Selected Files And Commit Messages

Committing is not only pressing a button.

I still want to choose which files belong together. I still want the commit message to match the change. I still want to avoid committing work on a protected branch by accident.

ABP Studio keeps that flow visible. I can select the files I want, write a summary and description, and commit to the current branch. When AI is enabled, Studio can generate a commit message from the selected diffs.

I like this because it keeps the AI help close to the actual diff.

A generic prompt like "write a commit message" depends on what I paste into the chat. In Studio, the commit message generator can work from the selected files. That makes the result more focused, and I still stay in control because the generated text lands in the commit fields before I use it.

The protected branch warning is another important part of the experience. If the current branch should not receive direct commits, Studio makes that visible and pushes me toward the safer workflow: create a branch, review the diff, then commit there.

That is the right kind of guardrail. It does not make Git complicated. It makes the normal team habit harder to miss.

Branching, Stashing, And Syncing

AI-assisted development often starts with a branch decision.

Sometimes I am starting fresh from the default branch. Sometimes I am building on work already in my current branch. Sometimes I have local changes and need to switch context without losing them.

ABP Studio exposes those decisions in the Git panel.

I can create a branch, switch branches, update from the default branch, fetch, pull, push, and see whether I am ahead or behind. If I switch branches while I have local changes, Studio asks what should happen to that work: leave it behind as a stash or bring it with me.

That choice is more important than it looks.

When I am working with an agent, I do not want local changes to silently follow me into the wrong branch. I also do not want to lose half-finished work just because I need to inspect another issue. The stash flow turns that into an explicit decision.

The same idea applies to sync.

If my branch is behind, I can update before I continue. If I have local commits, I can push them. If a merge or pull produces conflicts, Studio shows the conflicted files and gives me a path to resolve, abort, continue, or send the conflict context to ABP Agent.

That keeps the Git workflow close to the coding workflow. I can move from change to review to sync without mentally switching tools.

AI Review And Manual Diff Comments

There is a moment before a commit where I often want a second look.

Not a full pull request review. Not a long architecture discussion. Just a focused pass over the files I selected:

Does this diff contain something suspicious?
Did the agent miss a small edge case?
Is there a line I should check again before committing?

ABP Studio supports that with AI review on selected Git changes.

AI review is not the only way to leave notes on a diff. I can also write my own comments directly on changed lines while I am reviewing.

The useful part is that the review is attached to the diff. Suggestions and notes appear near the changed lines, and if there is something I want the agent to handle, I can send those review notes to ABP Agent.

That changes the feel of the workflow.

Instead of asking the agent to code and then manually re-explaining my review comments, I can turn the review result back into a task. Whether a note comes from AI review or from something I wrote myself, the agent gets the file, line, and note context. I still review the result, but I spend less time copying context between places.

Git also helps with recovery. In a Git repository, ABP Studio can offer Back to this point in the agent conversation. For me, that is a comfort feature: if an agent turn takes the work in the wrong direction, I can return to an earlier point instead of manually untangling every changed file.

I still treat Git commits as the real checkpoints for team work. But during a live agent session, being able to go back to a previous point makes experimentation feel less risky.

GitHub Issue Context

Many tasks do not start as a prompt. They start as an issue.

The issue has the requirement, comments, labels, screenshots, and sometimes a conversation about what is expected. If that context stays only in the browser, I have to copy it into the agent manually.

ABP Studio can bring GitHub issues into the Git area.

I can filter issues, open one, read the description and comments, create a branch for that issue, and send the issue context to ABP Agent.

That makes the workflow feel natural:

1. Pick the issue.
2. Create a branch for it.
3. Send the relevant context to ABP Agent.
4. Let the agent inspect the solution and implement the change.
5. Review the Git diff before committing.

The important detail is that the agent starts from the same context I would start from as a developer. It sees the issue title, description, labels, included comments, and attached images when they are part of the selected context.

That is much better than writing a vague prompt that tries to summarize the issue from memory.

Pull Request Feedback Context

Pull request feedback is another place where Git integration helps the AI workflow.

When I open a pull request inside ABP Studio, I can see the PR title, branches, comments, reviews, and requested changes. If I am not on the PR branch, Studio can switch to it. Then I can choose which comments or requested changes should be included and send that context to ABP Agent.

This is the workflow I want when a reviewer asks for changes:

• read the feedback,
• switch to the right branch,
• include only the relevant comments,
• send the request to ABP Agent,
• review the resulting diff,
• commit and push.

The include and exclude controls matter here. Not every PR comment should become an agent instruction. Some comments are discussion, some are already resolved, and some are optional. I want to choose what becomes context.

That keeps the agent from treating the entire PR timeline as one undifferentiated command. I can shape the task before sending it.

Git Integration In The Deep Dive Series

In the earlier articles, we looked at modes, tools, MCP, scopes, and workflows.

Git integration connects those ideas to the normal development lifecycle.

• Ask and Plan help me understand and shape the work.
• Agent mode can make the change.
• Tools help the agent use ABP Studio context.
• Scopes keep the working area focused.
• Workflows make repeated actions predictable.
• Git integration lets me review, recover, commit, push, and collaborate around the result.

That last part is easy to underestimate.

The value of an AI coding agent is not only how quickly it can modify files. The value is whether I can bring those modifications into a professional development workflow without losing control.

Git is the structure that makes that possible.

Conclusion

ABP Studio Git Integration makes ABP Agent feel more grounded.

It gives me a clear path from issue to branch, from agent work to diff review, from selected files to commit, and from pull request feedback back into the agent.

For everyday work, that means fewer context switches. For AI-assisted work, it means more confidence.

I can let the agent help, but I do not have to accept the result blindly. I can inspect the diff, ask for a review, commit intentionally, push when ready, and keep the whole process connected to GitHub and the team workflow.

That is the part I value most: Git integration turns AI output into reviewable development work.

There is one question I ask almost as often as "Which mode should I use?":

Which model should do this work?

At first, it is tempting to answer that question by always choosing the strongest model in the list. That feels safe. If a model is more capable, why not use it for everything?

In real work, I do not think about it that way.

When I use ABP Studio AI, the model choice is part of the workflow. Some tasks need careful reasoning. Some need speed. Some need a large context window. Some need image support because the browser or a screenshot is involved. Some are small text-processing tasks where using the most capable model would only make the work slower and more expensive.

So I treat model selection as a practical decision, not a trophy selection.

What ABP Studio Supports Today

ABP Studio gives me a curated model setup by default. It keeps the first experience simple, while still letting me choose from a broader model catalog when I want to tune the setup for a specific kind of work.

The important word here is focused.

ABP Studio does not treat every model as an equally good choice for agent work. A coding agent needs things like a useful context window, tool support, text output, and reliable behavior in repeated agent loops. Studio keeps the model experience closer to that reality.

The built-in model set currently includes:

| Model | How I think about it | | --- | --- | | Claude Sonnet 4.6 | The default main model for day-to-day Ask, Plan, and Agent work. | | Claude Haiku 4.5 | A fast supporting model for research, browser work, and lightweight text processing. | | Claude Opus 4.7 | A stronger option when the task needs deeper reasoning or more careful review. | | GPT-5.5 | Another strong option for main conversations or review-style work. | | GLM-5.1 | A text/code option for tasks that do not need image input. |

I do not read this list as a ranking. I read it as the default toolbox.

And it is not a closed box. If I need a different model for a specific task, I can open the Models settings, search the catalog, filter by category, and add more models to my selection.

That is an important distinction. The built-in models are there so I can start with sensible defaults. They are not there to force every team, every solution, or every workflow into the same model choices.

The Main Model

The main model is the one I feel most directly in the conversation.

It is used when I ask questions, create plans, or let ABP Agent work through an implementation. This is the model behind the normal flow of the chat.

For most work, I keep a balanced model as the main model. A Sonnet-style model is a good default because it is capable enough for real development tasks without making every small question feel heavy.

This is the model I use for:

• Understanding a module or package
• Planning a feature before editing code
• Applying a reviewed plan
• Fixing ordinary build or test failures
• Making changes where the expected result is easy to review

When the task gets broader, I become more intentional.

If I am asking ABP Agent to reason across several modules, plan a risky refactor, review architecture, or inspect a subtle regression, I am more willing to switch to a stronger model. The extra capability is useful when the cost of a shallow answer is high.

For a quick localization change or a small DTO update, that same choice can be wasteful. The strongest model is not always the best model for the moment.

Role-Based Models

One detail I like in ABP Studio AI is that model selection is not only one global dropdown.

Studio separates the main conversation model from supporting model roles. That means I can keep the main model strong enough for the conversation while using lighter models for background work.

The roles are easier to understand if I describe them by how they feel in daily use.

Main Model is the model I am actively talking to. It carries the normal Ask, Plan, and Agent experience.

Research Model is for research and ABP documentation searcher work. I usually keep this lightweight because research often involves gathering, narrowing, and summarizing context before the main model decides what to do with it.

Browser Model is used by the browser subagent in Agent mode. This role should stay fast and practical. When browser screenshots are involved, I choose a model that supports image input. A text-only model may be fine for code, but it is not the right fit when the work depends on seeing the UI.

Text Processor Model is for smaller language tasks such as summarizing errors, generating commit messages, or consolidating learned lessons. This is exactly where I do not want to spend the most capable model every time.

The Git Review model is separate too.

For AI Review, I like the "Ask me every time" behavior. Some reviews are routine. Some reviews deserve a stronger model because the change is large, security-sensitive, or touches architecture. Asking each time keeps that decision close to the actual change.

If a team wants consistent review behavior, a fixed review model also makes sense. The key is that Git Review does not have to silently follow the same model I use for ordinary chat.

How I Choose In Practice

For quick questions, I use the default main model.

If I am asking "Where is this permission defined?" or "Why does this module reference that package?", I do not need to overthink the model. I want a clear answer and maybe a few source references.

For planning larger work, I use a stronger main model when the decision matters.

Plan mode is where the model can save me from an expensive wrong turn. If the change crosses layers, modules, permissions, UI, or database behavior, I prefer a model that can hold more context and reason carefully. I still narrow the scope where possible, because a focused prompt usually beats a huge unfocused one.

For implementation, I care about reliability more than raw size.

Agent mode is not only about generating code. It is about reading the solution, editing files, running checks, seeing failures, and trying again. A good main model should follow instructions consistently and use tools well. For supporting roles, I usually keep the lighter defaults.

For UI and browser tasks, I check image support.

If the task involves screenshots, browser interaction, visual verification, or UI state, the browser model needs to be able to understand images. This is one reason I do not treat every text/code model as interchangeable.

For reviews, I choose based on risk.

A small formatting or localization change does not need the same review setup as a large change in authorization, multi-tenancy, persistence, or distributed behavior. For deeper reviews, I am willing to use a stronger model because the goal is not speed. The goal is to catch what I missed.

For cost and latency, I avoid using the strongest model everywhere.

This is not only about credits. It is also about pace. If every background task uses a heavy model, the development loop feels slower. Keeping lightweight models for lightweight jobs makes ABP Studio AI feel more responsive.

A Simple Rule

The model name matters less than the job.

When I choose a model in ABP Studio AI, I usually ask:

| Situation | Model choice I prefer | | --- | --- | | Normal Ask, Plan, or Agent work | Balanced main model | | Broad planning or risky implementation | Stronger main model | | Research and documentation lookup | Lightweight supporting model | | Browser tasks with screenshots | Vision-capable browser model | | Error summaries and commit messages | Lightweight text processor model | | Important AI Review | Stronger model or ask each time |

That keeps the experience practical.

Modes decide how much action I want: Ask, Plan, or Agent.

Models decide which brain should handle the work.

When those two choices are made intentionally, ABP Studio AI feels less like one generic AI button and more like a set of tools I can tune for the task in front of me.

There is a small question I like to answer before I type anything into ABP Agent:

Do I want an answer, a plan, or action?

That question looks simple, but it changes the whole experience. Sometimes I am only trying to understand why a module is structured a certain way. Sometimes I already know the direction, but I want the implementation path checked before touching files. And sometimes the task is clear enough that I want ABP Agent to do the work, run the checks, and iterate with me.

That is where the three modes in ABP Studio AI become more than labels. They help me choose the right level of trust, risk, and action for the moment.

Ask Mode: When I Want To Understand

Ask is the mode I reach for when I want to stay in learning mode.

It is useful when I am reading a solution and want to ask questions like:

• What is this module responsible for?
• Why is this permission checked here?
• How does this application service relate to the domain layer?
• What would happen if I changed this setting, dependency, or flow?
• Which ABP concept should I use for this requirement?

The important part is that Ask mode is read-only. I can explore the codebase, ABP concepts, architecture, or possible approaches without worrying that files will be changed as a side effect of the conversation.

That makes it a comfortable starting point. I do not need to prepare a perfect prompt. I can ask a rough question, follow up with more context, and slowly turn uncertainty into something clearer.

For me, Ask mode is especially helpful when I join a solution after some time away. Instead of jumping between files and trying to rebuild the story manually, I can ask ABP Agent to explain the shape of the solution in the language of ABP: modules, layers, permissions, application services, entities, settings, events, and runtime pieces.

Plan Mode: When I Want To Think Before Changing Code

Plan is the mode I use when the next step is probably implementation, but I do not want to start editing yet.

This is the middle ground between a conversation and a code change. ABP Agent can inspect the solution in a read-only way, ask clarifying questions when the requirement is not clear enough, and produce a structured plan before any file is modified.

That changes the feeling of working with AI. Instead of saying "go build this" and reviewing only the result, I can review the approach first:

• Which files will likely be affected?
• Which ABP layers are involved?
• Does the implementation path match the existing solution style?
• Are there missing decisions before the work starts?
• Is this a small change, or is it actually a larger workflow?

This is useful for changes that cross boundaries: adding a new entity, adjusting an application service, introducing a permission, changing a UI flow, or touching more than one module. Those are exactly the moments where I want a second pass before code starts moving.

When a plan is active, ABP Studio gives me clear actions around it. I can view the plan, detach it if it is no longer the right direction, or apply it with Agent mode when I am ready to move from planning to implementation.

The small detail I like here is that the plan does not disappear into the chat history. It becomes something I can review and intentionally carry into the next step.

Agent Mode: When I Am Ready For Action

Agent is the mode I choose when I am ready to let ABP Agent work on the solution.

This is the action mode. ABP Agent can edit files, run commands, build projects, use ABP Studio tasks, and iterate when something fails. It is the right choice when the task is clear enough and I am comfortable letting the agent make changes that I will review afterward.

For small trusted tasks, I may go directly to Agent mode:

• Add a missing localization entry
• Fix a straightforward build error
• Update a simple DTO mapping
• Add a validation rule that matches an existing pattern
• Apply a plan that I have already reviewed

For larger work, I prefer not to start here. Agent mode is powerful, and power is better when it is intentional. If I am not sure about the shape of the change, I usually start with Ask or Plan first.

A Practical Workflow

The modes are most useful when I treat them as a workflow, not as three disconnected buttons.

For larger changes, my usual flow is:

1. Ask to understand the area and the existing conventions.
2. Plan to turn the requirement into a reviewable implementation path.
3. Agent to apply the plan, build, and iterate.

For learning, I often stay entirely in Ask mode. If I am trying to understand ABP multi-tenancy behavior, module dependencies, permission definitions, or why a solution is organized a certain way, there is no need to involve file changes.

For small tasks, I may go directly to Agent mode. The key is that I already know what I want, the risk is low, and the expected result is easy to review.

Here is the simple rule I keep in mind:

| Situation | Mode I Choose | Why | | --- | --- | --- | | I need an explanation | Ask | It keeps the conversation read-only. | | I need a direction before implementation | Plan | It gives me a reviewable path before changes. | | I am ready for ABP Agent to work | Agent | It can edit, build, run tasks, and iterate. |

Why This Matters

AI-assisted development can feel too fast when the tool moves from idea to code before I have decided what kind of help I actually need.

The three modes slow that moment down in a good way. They let me say:

• "Just explain this."
• "Think through the change first."
• "Now implement it."

That separation makes the work feel more intentional. It also makes the output easier to review, because the mode already tells me what kind of result I should expect.

Ask gives me understanding. Plan gives me a path. Agent gives me action.

Used together, they make ABP Studio AI feel less like a single big button and more like a development partner that can adapt to the level of confidence I have at each step.

We are excited to announce that ABP Studio, our cross-platform desktop application for ABP developers, is now available on Linux.

With this release, Linux users can download and run ABP Studio as an x64 AppImage. This is an important step in making ABP Studio available wherever .NET and ABP developers prefer to work.

What can you do with ABP Studio?

ABP Studio is a desktop application designed to make ABP development faster, easier, and more comfortable. It offers:

• Easy creation of new solutions, from simple applications to distributed systems
• Visual architecture management for modular monolith and microservice solutions
• Solution exploration tools for entities, services, packages, and HTTP APIs
• Simplified running, debugging, and monitoring of multi-application solutions
• Kubernetes integration capabilities
• Built-in access to ABP-specific tooling and workflows

The screenshots below were captured from ABP Studio on Linux through the AppImage.

Linux Support Has Arrived

ABP Studio has already been supporting multiple desktop environments, and now Linux joins that list.

You can currently use ABP Studio on:

• Windows x64
• Windows ARM
• macOS Apple Silicon
• macOS Intel
• Linux x64 (New!)

On Linux, the current distribution format is AppImage, which provides a practical way to distribute a desktop application across different Linux distributions without requiring a distribution-specific installer package.

What This Means for Developers

Many ABP developers use Linux as their daily development environment. Until now, they needed to switch to another operating system to use ABP Studio. With Linux support, developers can now stay on their preferred platform and still benefit from ABP Studio's solution creation, architecture design, solution runner, monitoring, and integrated development experience.

This is especially valuable for teams that already build and run their backend services on Linux-based environments and want to keep their development workflow aligned with that ecosystem.

AI Agent Is Available on Linux Too

Another common question from the community has been whether ABP Studio AI Agent can be used on Linux machines. With this release, the answer is yes.

Linux users can now use ABP Studio AI Agent in their own development environment. You can ask questions about your solution, plan implementation steps before changing code, and let the agent help with coding tasks while ABP Studio understands your ABP solution structure, build flow, and runtime context.

For a deeper look at the AI Agent experience, see the original announcement: Introducing ABP Studio AI Agent.

Getting Started

Downloading and running ABP Studio on Linux is simple:

1. Go to abp.io/studio
2. Download the Linux x64 AppImage
3. Open a terminal in the folder where the file was downloaded
4. Make the AppImage executable and run it

chmod +x ./AbpStudio-stable.AppImage
./AbpStudio-stable.AppImage

Once launched, you can start using ABP Studio just like on the other supported platforms.

If the AppImage Does Not Run Directly

Some Linux distributions may require additional runtime support for direct AppImage execution.

For example, on some Ubuntu and Debian-based systems, you may need libfuse2:

sudo apt update
sudo apt install libfuse2

If FUSE is not available on your machine, you can still extract and run the AppImage manually:

./AbpStudio-stable.AppImage --appimage-extract
./squashfs-root/AppRun

This fallback can be useful for testing or for environments where AppImage mounting is restricted.

Current Scope and Limitations

This first Linux release is intentionally focused so we can deliver a reliable experience quickly.

Here is the current scope:

• Linux distribution is currently provided as an x64 AppImage
• Linux ARM builds are not published yet
• Depending on your Linux distribution, some native desktop or browser-related libraries may need to be installed
• When ABP Studio can detect a known native dependency problem, it tries to show guidance in the UI instead of leaving you with an unclear failure

This means Linux support is ready to use today, and we will continue to improve the Linux experience in future releases.

A Better Cross-Platform Experience

ABP Studio has always aimed to be the default way to start and develop ABP solutions. Linux support brings us closer to that goal by making the Studio experience more accessible across major desktop platforms.

Whether you are creating a new solution, exploring packages and services, running multiple applications together, or monitoring runtime behavior, you can now do that on Linux too.

Conclusion

We are happy to finally make ABP Studio available on Linux.

This first release focuses on a practical and reliable target: Linux x64 through AppImage. It already opens the door for many developers who prefer Linux as their primary development environment, and it gives us a strong foundation to improve the Linux experience further.

Please download it, try it in your daily workflow, and share your feedback with us. If you encounter a problem or want to request additional Linux targets like ARM, feel free to open an issue and let us know.

If you have followed ABP for a while, you probably know that React support has been one of the most requested topics in the community.

With ABP 10.4.0-rc.1, that wait ends. React in ABP is no longer just something people ask about, hope for, or imagine as the next step. You can now create it, run it, and explore it today as a beta/preview experience in the modern template system.

As part of the ABP Framework team, and as one of the developers working on this React effort, I am genuinely happy to finally share it. This RC gives the community an early chance to try it, share feedback, and help us polish the final details before ABP 10.4 stable, where we plan to make the React UI generally available.

Why this matters

ABP Framework has always been about helping teams build modern, maintainable, production-ready applications faster. With the new React UI, we are extending that same vision to teams who want ABP on the backend and React on the frontend without losing the built-in application features that make ABP productive from day one.

This is not another empty starter. The goal is a first-class UI option that fits into the ABP application startup experience and works naturally with familiar ABP concepts such as authentication, authorization, localization, multi-tenancy, modularity, runtime configuration, and deployment.

There is one important detail: the React UI belongs to ABP's modern template system. You create it with the --modern flag in the ABP CLI or by selecting the modern template flow in ABP Studio. You can find the technical documentation here: React UI documentation.

A quick look at the architecture

The final shape is clearer now: a modern React solution gives you a real React application in the solution, plus the ABP administration experience.

First, there is your React application. In the modern templates, this lives directly in the solution as a real app under react/ or apps/react/. It contains the frontend code you work with every day, including pages, components, routing, API integration, runtime configuration, and authentication setup.

Second, there is the ABP Admin Console. The Admin Console is a pre-built React application that provides the standard ABP module management pages. It is delivered through the Volo.Abp.AdminConsole NuGet package, so it can evolve with ABP package updates while your own React application stays focused on your product's business features.

For layered and single-layer modern applications, the Admin Console is hosted by the backend and served under /admin-console/*. For microservice solutions, it runs as a separate React app under apps/react-admin-console/, with its own runtime configuration and the same /admin-console/ base path. In both cases, the main React app can link users into the Admin Console when they need full administrative screens.

This split is a practical design choice. Your business UI stays yours, while administration capabilities remain available, consistent, and upgradeable.

A different frontend philosophy

One of the most important things to understand is that this React UI is not being shaped with exactly the same architecture as some previous UI options.

We are not trying to ship the whole frontend experience as a closed set of page implementations coming from npm packages. Instead, the generated solution includes the actual page code inside the app itself. You can open it, understand it, refactor it, redesign it, and adapt it without fighting against a packaged black box.

The Admin Console covers ABP's standard module administration pages. Your own React application remains intentionally open and direct. That gives teams a good balance: built-in administrative power from ABP, and full ownership of the product-facing frontend.

Built for AI-driven development

The new React UI is also shaped for the era of AI-assisted development.

React, TypeScript, Vite, TanStack Router, TanStack Query, Axios, Zod, React Hook Form, and shadcn/ui are technologies that modern coding assistants understand very well. Just as importantly, the generated application contains real frontend code in the solution. That gives AI tools and coding agents concrete project context to read, extend, and refactor.

This direction also fits the broader ABP AI story. ABP Studio already includes an AI assistant experience, and the new ABP AI Agent is being introduced to bring code generation, project understanding, issue fixing, and natural-language application evolution directly into the ABP workflow. You can follow that work here: The Future of ABP Studio: AI Agent + Code Generation. For the wider toolset, see the ABP AI Toolkit.

What the React experience looks like

The current template already points to the kind of experience React developers expect from a modern application:

• A Vite-powered React + TypeScript frontend
• TanStack Router for client-side routing
• TanStack Query for server state and data fetching
• OIDC authentication against the ABP Auth Server
• Axios-based HTTP client integration
• Runtime configuration through dynamic-env.json
• Localization and permission-aware behavior integrated with ABP application configuration
• Tailwind CSS and shadcn/ui components that live in your project and can be customized directly
• Zod and React Hook Form for form handling and validation
• Vitest for frontend tests
• A dedicated Admin Console for ABP module administration

Even in its current form, the React UI already feels like a real ABP solution experience, not just a login page plus a few demo screens.

More than a hello world

The generated React app is intentionally small enough to understand, but it is not empty.

Out of the box, you already get the kind of foundation most teams expect: login, registration, forgot-password and reset-password flows, runtime configuration, localization, permission-aware routing, API proxy generation, and a simple users page that can deep-link into the Admin Console when full user management is needed.

Depending on the selected options, it can also include a sample Books CRUD page that demonstrates how to build a full create/read/update/delete flow against an ABP backend.

The Admin Console provides the standard management experience for ABP modules, including identity management, roles, organization units, settings, audit logs, OpenIddict administration, language management, text templates, GDPR, SaaS and tenant management, and other module pages depending on your solution configuration.

That is the core value: developers get a clean React application to build their product, while ABP continues to provide the administrative capabilities expected from a production-ready application platform.

Try it with ABP 10.4 RC

During the RC period, you can create a modern React solution with ABP 10.4.0-rc.1:

abp new Acme.BookStore --template app --modern

The React UI is the default UI option when --modern is used, but you can also pass it explicitly:

abp new Acme.BookStore --template app --modern --ui-framework react

For a single-layer application:

abp new Acme.BookStore --template app-nolayers --modern

For a microservice solution:

abp new Acme.BookStore --template microservice --modern

Once ABP 10.4 stable is released, the same modern React experience is planned to become generally available without needing to target the RC version explicitly.

What's next

The React UI is now real in ABP 10.4 RC, and the final polishing work continues toward the stable release. If you have been waiting for a real React path in ABP, this is the point where it stops being a wish and starts becoming something you can actually build with.

For me, one of the nicest parts of this RC is that we can finally stop talking about React support in ABP as a future idea and start improving something real together.

Try it, explore it, and share feedback with us while we keep polishing it for ABP 10.4 stable.

The ABP Framework is famous for its Convention-over-Configuration approach, which means a lot of things work automatically without explicit configuration. In this article, I'll uncover these "hidden magics" that make ABP so powerful but often go unnoticed by developers.

1. Automatic Service Registration Without Any Attributes

The Magic: Any class implementing ITransientDependency, ISingletonDependency, or IScopedDependency is automatically registered with the corresponding lifetime.

// This is automatically registered as Transient - no configuration needed!
public class MyService : IMyService, ITransientDependency
{
    public void DoSomething() { }
}

Where it happens: Volo.Abp.Core/Volo/Abp/DependencyInjection/ConventionalRegistrarBase.cs

The framework scans all assemblies and automatically determines service lifetime from class hierarchy. This is why you rarely need to manually register services in ABP.

2. All Interfaces Are Exposed By Default

The Magic: When you register a service, it's automatically registered as both itself AND all its implemented interfaces.

public class UserService : IUserService, IValidationInterceptor
{
    // Registered as both IUserService AND IValidationInterceptor
    // No ExposeServices attribute needed!
}

Where it happens: Volo.Abp.Core/DependencyInjection/ExposedServiceExplorer.cs:9-14

private static readonly ExposeServicesAttribute DefaultExposeServicesAttribute =
    new ExposeServicesAttribute
    {
        IncludeDefaults = true,
        IncludeSelf = true
    };

3. Automatic Validation on Every Method

The Magic: Every application service method parameters are automatically validated - you don't need to add [Validate] attributes.

Where it happens: Volo.Abp.Validation/ValidationInterceptorRegistrar.cs

The ValidationInterceptor is automatically added to the interceptor pipeline for all services. Every method call triggers automatic validation of input parameters.

4. Automatic Unit of Work Management

The Magic: Every database operation is automatically wrapped in a transaction. You don't need to explicitly configure unit of work for most scenarios.

Where it happens: The UnitOfWorkInterceptor is auto-registered and automatically:

• Begins transaction before method execution
• Commits on success
• Rolls back on exception

5. Auditing Is Enabled By Default

The Magic: Auditing is ON by default, even for anonymous users!

public class AbpAuditingOptions
{
    public AbpAuditingOptions()
    {
        IsEnabled = true;                    // Enabled by default!
        IsEnabledForAnonymousUsers = true;   // Anonymous users are audited!
        HideErrors = true;                   // Errors are silently hidden
        AlwaysLogOnException = true;         // Exceptions always logged
    }
}

Where it happens: Volo.Abp.Auditing/AbpAuditingOptions.cs:73-91

This means every entity change and service call is logged automatically unless explicitly disabled.

6. Security Logging Is Always On

The Magic: Security logging is enabled by default in ABP!

public AbpSecurityLogOptions()
{
    IsEnabled = true;  // Hidden: ON by default!
}

Every authentication attempt, authorization failure, and security-relevant action is logged automatically.

7. Data Filters Are Enabled By Default

The Magic: ISoftDelete and IMultiTenant filters are enabled by default.

// In DataFilter.cs - Line 103
_filter.Value = _options.DefaultStates.GetOrDefault(typeof(TFilter))?.Clone() 
    ?? new DataFilterState(true);  // true = enabled!

This means:

• Deleted entities are automatically filtered out
• Multi-tenant data is automatically isolated

You must explicitly disable these filters when you need to access all data:

using (_dataFilter.Disable<IMultiTenant>())
{
    // Query all tenants
}

8. Object Mapping (Mapperly - The New Standard)

The Magic: Starting with ABP v9.0, new project templates use Mapperly instead of AutoMapper. Any class using Mapperly attributes is automatically configured.

// Starting with ABP v10.0, new projects use Mapperly instead of AutoMapper

// Inherit from MapperBase - automatically registered with IObjectMapper
public partial class UserMapper : MapperBase<User, UserDto>
{
    public override partial UserDto Map(User source);
}

// For two-way mapping
public partial class UserTwoWayMapper : TwoWayMapperBase<User, UserDto>
{
    public override partial UserDto Map(User source);
    public override partial User ReverseMap(UserDto source);
}

The mapping is done at compile-time (no reflection overhead), and it's automatically registered with ABP's IObjectMapper.

Where it happens: Volo.Abp.Mapperly/AbpMapperlyConventionalRegistrar.cs

// Automatically discovers and configures all Mapperly mappers
context.Services.OnRegistered(context =>
{
    if (typeof(MapperBase).IsAssignableFrom(context.ImplementationType))
    {
        // Register the mapper
    }
});

9. Automatic Data Seed Contributor Discovery

The Magic: Any class implementing IDataSeedContributor is automatically discovered and executed on application startup.

// Automatically discovered and run on startup!
public class MyDataSeeder : IDataSeedContributor
{
    public Task SeedAsync(DataSeedContext context)
    {
        // Seed data here
    }
}

Where it happens: Volo.Abp.Data/AbpDataModule.cs:40-56

10. Automatic Definition Provider Discovery

The Magic: These are all auto-discovered without any configuration:

• ISettingDefinitionProvider - Settings
• IPermissionDefinitionProvider - Permissions
• IFeatureDefinitionProvider - Features
• INavigationProvider - Navigation items

11. Automatic Widget Discovery

The Magic: Any class implementing IWidget is automatically registered and can be rendered in pages.

Where it happens: Volo.Abp.AspNetCore.Mvc.UI.Widgets/AbpAspNetCoreMvcUiWidgetsModule.cs

12. Remote Services Are Enabled By Default

The Magic: All API controllers have remote service functionality enabled by default:

public class RemoteServiceAttribute : Attribute
{
    public bool IsEnabled { get; set; } = true;  // Enabled by default!
}

13. Auto API Controllers - Application Services Become REST APIs Automatically

The Magic: When you create an application service (class implementing an interface or inheriting from ApplicationService), ABP automatically creates REST API endpoints for it - no manual controller needed!

// This interface is automatically exposed as /api/app/product
public interface IProductAppService
{
    Task<List<ProductDto>> GetListAsync();
    Task<ProductDto> CreateAsync(CreateProductDto input);
    Task DeleteAsync(Guid id);
}

// The implementation automatically becomes an API Controller
public class ProductAppService : ApplicationService, IProductAppService
{
    public Task<List<ProductDto>> GetListAsync() { ... }
    public Task<ProductDto> CreateAsync(CreateProductDto input) { ... }
    public Task DeleteAsync(Guid id) { ... }
}

// Available endpoints (auto-generated):
// GET  /api/app/product
// POST /api/app/product
// DELETE /api/app/product/{id}

Where it happens: Volo.Abp.AspNetCore.Mvc/AbpServiceConvention.cs

The framework:

• Converts camelCase method names to kebab-case routes
• Maps HTTP methods automatically (Get→GET, Create→POST, Delete→DELETE)
• Generates proper DTOs from parameters and return types
• Handles serialization/deserialization

14. Dynamic Client Proxies - Client-Side Code Generated Automatically

The Magic: On the client side, you don't need to write HTTP client code. ABP automatically generates Dynamic JavaScript Proxies and Dynamic C# Proxies that let you call your APIs as if they were local method calls!

JavaScript (MVC/Razor Pages):

// Just call it like a local function!
var products = await productAppService.getList();
await productAppService.create({ name: "New Product" });
await productAppService.delete(id);

C# (Blazor/Console Apps):

// Inject and use like local method calls!
public class ProductListModel : PageModel
{
    private readonly IProductAppService _productAppService;
    
    public async Task OnGetAsync()
    {
        // Actually makes HTTP call to the server!
        var products = await _productAppService.GetListAsync();
    }
}

Where it happens:

• JavaScript: Volo.Abp.AspNetCore.Mvc.UI - Dynamic JavaScript proxies
• C#: Volo.Abp.AspNetCore.Mvc.Client - Dynamic C# HTTP clients

This is why you can inject application service interfaces directly in Blazor and call them like local methods!

15. Permission Checks

By default, all application service methods and controllers are public and accessible. Add [Authorize] or [AbpAuthorize] to restrict access:

[Authorize]
public async Task CreateAsync(CreateDto input) { }

[AbpAuthorize("MyApp.Permissions.CanCreate")]
public async Task CreateAsync(CreateDto input) { }

The AuthorizationInterceptor is added only when [Authorize] attribute is present on the class or method.

16. Background Workers Auto-Registration

The Magic: Background workers are enabled by default, and any class implementing IBackgroundWorker or IQuartzBackgroundWorker is auto-registered.

17. Entity ID Generation

The Magic: ABP automatically detects the best ID generation strategy based on the entity type:

• Guid → Auto-generates GUID
• int/long → Database identity
• string → No auto-generation (must provide)

Where it happens: Volo.Abp.Ddd.Domain/Entities/EntityHelper.cs

18. Anti-Forgery Token Magic

The Magic: ABP automatically handles CSRF protection with these hardcoded values:

// Blazor Client
private const string AntiForgeryCookieName = "XSRF-TOKEN";
private const string AntiForgeryHeaderName = "RequestVerificationToken";

19. Automatic Event Handler Discovery

The Magic: Any class implementing IEventHandler<TEvent> is automatically subscribed to handle events - no manual registration needed!

// This handler is automatically registered when the assembly loads!
public class OrderCreatedHandler : IEventHandler<OrderCreatedEvent>
{
    public Task HandleEventAsync(OrderCreatedEvent eventData)
    {
        // Handle the event - automatically subscribed!
    }
}

20. Unit of Work Events - Automatic Save

The Magic: Events are not fired immediately - they're collected during the unit of work and fired at the end when everything succeeds!

// In UnitOfWorkEventPublisher.cs
// Events are queued and published only when UOW successfully completes
await _localEventBus.PublishAsync(
    entityChangeEvent,
    onUnitOfWorkComplete: true  // Wait for UOW to complete!
);

This ensures transactional consistency - if your UOW fails, no events are fired.

21. Distributed Event Bus - Outbox Pattern

The Magic: ABP implements the Outbox Pattern automatically for distributed events, ensuring no events are lost!

// In DistributedEventBusBase.cs
// Events are stored in outbox table and processed reliably
foreach (var outboxConfig in AbpDistributedEventBusOptions.Outboxes.Values.OrderBy(x => x.Selector is null))
{
    // Outbox processing happens automatically
}

22. Automatic Object Extension Properties

The Magic: Any property decorated with [DisableAuditing] is automatically excluded from audit logs without any configuration!

// This property is automatically excluded from auditing
[DisableAuditing]
public string SecretData { get; set; }

23. Virtual File System

The Magic: ABP provides a virtual file system that merges embedded resources from all modules into a single virtual path!

// Any file embedded as "EmbeddedResource" is accessible virtually
// No configuration needed for module authors!

Where it happens: Volo.Abp.VirtualFileSystem/AbpVirtualFileSystemModule.cs

This is how ABP modules include static files (CSS, JS, images) that work without copying to wwwroot.

24. Automatic JSON Serialization Settings

The Magic: ABP pre-configures JSON serialization with:

• Camel case property naming
• Null value handling
• Reference loop handling
• Custom converters for common types

All configured automatically.

26. Localization Automatic Discovery

The Magic: All .json localization files in the application are automatically discovered and loaded:

/Localization/MyApp/
  en.json
  tr.json
  de.json

No explicit registration needed - just add files and they're available!

27. Feature Checks

Add [RequiresFeature] to restrict access based on feature flags:

[RequiresFeature("MyApp.Features.SomeFeature")]
public async Task DoSomethingAsync()
{
}

The FeatureInterceptor is added only when [RequiresFeature] attribute is present on the class or method.

28. API Versioning Convention

The Magic: ABP automatically handles API versioning with sensible defaults:

• Default version: 1.0
• Version from URL path: /api/v1/...
• Version from header: Accept: application/json;v=1.0

All configured automatically unless overridden.

29. Health Check Endpoints

The Magic: Health check endpoints are auto-registered:

• /health - Overall health status
• /health/ready - Readiness check
• /health/live - Liveness check

Includes automatic checks for:

• Database connectivity
• Cache availability
• External services

30. Swagger/OpenAPI Auto-Configuration

The Magic: If you reference Volo.Abp.AspNetCore.Mvc.UI.Swagger, Swagger UI is automatically generated with:

• All API endpoints documented
• Authorization support
• Versioning support
• XML documentation

No configuration needed beyond the package reference!

31. Background Job Queue Magic

The Magic: Background jobs are automatically retried with exponential backoff:

// Jobs are automatically:
// - Queued when published
// - Retried on failure (3 times default)
// - Delayed with exponential backoff

Where it happens: Volo.Abp.BackgroundJobs/AbpBackgroundJobOptions.cs

Summary Table

| # | Feature | Default Behavior | You Need to Know | |---|---------|-----------------|------------------| | 1 | Service Registration | Auto by interface | Implement ITransientDependency | | 2 | Service Exposure | Self + all interfaces | Default is generous | | 3 | Validation | All methods validated | Happens automatically | | 4 | Unit of Work | Transactional by default | Auto-commits/rollbacks | | 5 | Auditing | Enabled + anonymous users | Can disable per entity/method | | 6 | Security Log | Always on | Can configure what to log | | 7 | Soft Delete Filter | Enabled by default | Must disable to query deleted | | 8 | Multi-Tenancy Filter | Enabled by default | Must disable for host data | | 9 | Object Mapping | Mapperly (compile-time) | Inherit from MapperBase | | 10 | Data Seeds | Auto-discovery | Implement IDataSeedContributor | | 11 | Remote Services | Enabled by default | Can disable per service/method | | 12 | Auto API Controllers | App services → REST APIs | No manual controller needed | | 13 | Dynamic Client Proxies | Auto-generated | Call APIs like local methods | | 14 | Permissions | NOT automatic | Must add [Authorize] | | 15 | Settings | Auto-discovery | Define via ISettingDefinitionProvider | | 16 | Features | NOT automatic | Must add [RequiresFeature] | | 17 | Background Workers | Auto-registration | Implement IBackgroundWorker | | 18 | Entity ID Generation | Auto by type | Guid, int, string strategies | | 19 | Anti-Forgery | Auto-enabled | Token cookie/header handling | | 20 | Event Handlers | Auto-discovery | Implement IEventHandler<TEvent> | | 21 | UOW Events | Deferred execution | Transactional consistency | | 22 | Distributed Events | Outbox pattern | Reliable messaging | | 23 | Virtual Files | Module merging | Embedded resources as virtual | | 24 | JSON Settings | Pre-configured | CamelCase, null handling | | 25 | Tenant Resolution | Multi-source chain | Route → Query → Header → Cookie → Subdomain | | 26 | Localization | Auto-discovery | JSON files in /Localization | | 27 | API Versioning | Default v1.0 | URL, header, query support | | 28 | Health Checks | Auto-registered | /health, /health/ready, /health/live | | 29 | Swagger | Auto-generated | With authorization support | | 30 | Background Job Queue | Auto with backoff | 3 retries default | | 31 | Widgets | Auto-discovery | Implement IWidget |

Conclusion

ABP Framework's hidden magic is what makes it so productive to use. These conventions allow developers to focus on business logic rather than boilerplate configuration. However, understanding these defaults is crucial for:

1. Debugging - Knowing why certain behaviors happen
2. Optimization - Disabling what you don't need
3. Security - Understanding what's logged/audited by default
4. Architecture - Following the intended patterns

The next time something "just works" in ABP, there's likely a hidden convention behind it!

What hidden ABP magic have you discovered? Share your findings in the comments!

Global query filters are one of Entity Framework Core's most powerful features for automatically filtering data based on certain conditions. They allow you to define filter criteria at the entity level that are automatically applied to all LINQ queries, making it impossible for developers to accidentally forget to include important filtering logic. In this article, we'll explore how to implement multiple global query filters in ABP Framework, covering built-in filters, custom filters, and performance optimization techniques.

By the end of this guide, you'll understand how ABP Framework's data filtering system works, how to create custom global query filters for your specific business requirements, how to combine multiple filters effectively, and how to optimize filter performance using user-defined functions.

Understanding Global Query Filters in EF Core

Global query filters were introduced in EF Core 2.0 and allow you to automatically append LINQ predicates to queries generated for an entity type. This is particularly useful for scenarios like multi-tenancy, soft delete, data isolation, and row-level security.

In traditional applications, developers must remember to add filter conditions manually to every query:

// Manual filtering - error-prone and tedious
var activeBooks = await _bookRepository
    .GetListAsync(b => b.IsDeleted == false && b.TenantId == currentTenantId);

With global query filters, this logic is applied automatically:

// Filter is applied automatically - no manual filtering needed
var activeBooks = await _bookRepository.GetListAsync();

ABP Framework provides a sophisticated data filtering system built on top of EF Core's global query filters, with built-in support for soft delete, multi-tenancy, and the ability to easily create custom filters.

Important: Plain EF Core vs ABP Composition

In plain EF Core, calling HasQueryFilter multiple times for the same entity does not create multiple active filters. The last call replaces the previous one (unless you use newer named-filter APIs in recent EF Core versions).

ABP provides HasAbpQueryFilter to compose query filters safely. This method combines your custom filter with ABP's built-in filters (such as ISoftDelete and IMultiTenant) and with other HasAbpQueryFilter calls.

ABP Framework's Data Filtering System

ABP's data filtering system is defined in the Volo.Abp.Data namespace and provides a consistent way to manage filters across your application. The core interface is IDataFilter<TFilter>, which allows you to enable or disable filters programmatically.

Built-in Filters

ABP Framework comes with several built-in filters:

1. ISoftDelete: Automatically filters out soft-deleted entities
2. IMultiTenant: Automatically filters entities by current tenant (for SaaS applications)
3. IIsActive: Filters entities based on active status

Let's look at how these are implemented in the ABP framework:

The ISoftDelete interface is straightforward:

namespace Volo.Abp;

public interface ISoftDelete
{
    bool IsDeleted { get; }
}

Any entity implementing this interface will automatically have deleted records filtered out of queries.

Enabling and Disabling Filters

ABP provides the IDataFilter<TFilter> service to control filter behavior at runtime:

public class BookAppService : ApplicationService
{
    private readonly IDataFilter<ISoftDelete> _softDeleteFilter;
    private readonly IRepository<Book, Guid> _bookRepository;

    public BookAppService(
        IDataFilter<ISoftDelete> softDeleteFilter,
        IRepository<Book, Guid> bookRepository)
    {
        _softDeleteFilter = softDeleteFilter;
        _bookRepository = bookRepository;
    }

    public async Task<List<Book>> GetAllBooksIncludingDeletedAsync()
    {
        // Temporarily disable the soft delete filter
        using (_softDeleteFilter.Disable())
        {
            return await _bookRepository.GetListAsync();
        }
    }

    public async Task<List<Book>> GetActiveBooksAsync()
    {
        // Filter is enabled by default - soft-deleted items are excluded
        return await _bookRepository.GetListAsync();
    }
}

You can also check if a filter is enabled and enable/disable it programmatically:

public async Task ProcessBooksAsync()
{
    // Check if filter is enabled
    if (_softDeleteFilter.IsEnabled)
    {
        // Enable or disable explicitly
        _softDeleteFilter.Enable();
        // or
        _softDeleteFilter.Disable();
    }
}

Creating Custom Global Query Filters

Now let's create custom global query filters for a real-world scenario. Imagine we have a library management system where we need to filter books based on:

1. Publication Status: Only show published books in public areas
2. User's Department: Users can only see books from their department
3. Approval Status: Only show approved content

Step 1: Define Filter Interfaces

First, create the filter interfaces. You can define them in the same file as your entity or in separate files:

// Can be placed in the same file as Book entity or in separate files
namespace Library;

public interface IPublishable
{
    bool IsPublished { get; }
    DateTime PublishDate { get; set; }
}

public interface IDepartmentRestricted
{
    Guid DepartmentId { get; }
}

public interface IApproveable
{
    bool IsApproved { get; }
}

public interface IPublishedFilter
{
}

public interface IApprovedFilter
{
}

IPublishable / IApproveable are implemented by entities and define entity properties. IPublishedFilter / IApprovedFilter are filter-state interfaces used with IDataFilter so you can enable/disable those filters at runtime.

Step 2: Add Filter Expressions to DbContext

Now let's add the filter expressions to your existing DbContext. First, here's how to use HasAbpQueryFilter to create always-on filters (they cannot be toggled at runtime):

// MyProjectDbContext.cs
using Microsoft.EntityFrameworkCore;
using Volo.Abp.EntityFrameworkCore;
using Volo.Abp.GlobalFeatures;
using Volo.Abp.MultiTenancy;
using Volo.Abp.Authorization;
using Volo.Abp.Data;
using Volo.Abp.EntityFrameworkCore.Modeling;

namespace Library;

public class LibraryDbContext : AbpDbContext<LibraryDbContext>
{
    public DbSet<Book> Books { get; set; }
    public DbSet<Department> Departments { get; set; }
    public DbSet<Author> Authors { get; set; }

    public LibraryDbContext(DbContextOptions<LibraryDbContext> options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);

        builder.Entity<Book>(b =>
        {
            b.ToTable("Books");
            b.ConfigureByConvention();

            // HasAbpQueryFilter creates ALWAYS-ACTIVE filters
            // These cannot be toggled at runtime via IDataFilter
            b.HasAbpQueryFilter(book =>
                book.IsPublished &&
                book.PublishDate <= DateTime.UtcNow);

            b.HasAbpQueryFilter(book => book.IsApproved);
        });

        builder.Entity<Department>(b =>
        {
            b.ToTable("Departments");
            b.ConfigureByConvention();
        });
    }
}

Note: Using HasAbpQueryFilter alone creates filters that are always active and cannot be toggled at runtime. This approach is simpler but less flexible. For toggleable filters, see Step 3 below.

Step 3: Make Filters Toggleable (Optional)

If you need filters that can be enabled/disabled at runtime via IDataFilter<T>, override ShouldFilterEntity and CreateFilterExpression instead of (or in addition to) HasAbpQueryFilter:

// MyProjectDbContext.cs
using System;
using System.Linq.Expressions;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata;
using Microsoft.EntityFrameworkCore.Metadata.Builders;
using Volo.Abp.EntityFrameworkCore;

namespace Library;

public class LibraryDbContext : AbpDbContext<LibraryDbContext>
{
    protected bool IsPublishedFilterEnabled => DataFilter?.IsEnabled<IPublishedFilter>() ?? false;
    protected bool IsApprovedFilterEnabled => DataFilter?.IsEnabled<IApprovedFilter>() ?? false;

    protected override bool ShouldFilterEntity<TEntity>(IMutableEntityType entityType)
    {
        if (typeof(IPublishable).IsAssignableFrom(typeof(TEntity)))
        {
            return true;
        }

        if (typeof(IApproveable).IsAssignableFrom(typeof(TEntity)))
        {
            return true;
        }

        return base.ShouldFilterEntity<TEntity>(entityType);
    }

    protected override Expression<Func<TEntity, bool>>? CreateFilterExpression<TEntity>(
        ModelBuilder modelBuilder,
        EntityTypeBuilder<TEntity> entityTypeBuilder)
        where TEntity : class
    {
        var expression = base.CreateFilterExpression<TEntity>(modelBuilder, entityTypeBuilder);

        if (typeof(IPublishable).IsAssignableFrom(typeof(TEntity)))
        {
            Expression<Func<TEntity, bool>> publishFilter = e =>
                !IsPublishedFilterEnabled ||
                (
                    EF.Property<bool>(e, nameof(IPublishable.IsPublished)) &&
                    EF.Property<DateTime>(e, nameof(IPublishable.PublishDate)) <= DateTime.UtcNow
                );

            expression = expression == null
                ? publishFilter
                : QueryFilterExpressionHelper.CombineExpressions(expression, publishFilter);
        }

        if (typeof(IApproveable).IsAssignableFrom(typeof(TEntity)))
        {
            Expression<Func<TEntity, bool>> approvalFilter = e =>
                !IsApprovedFilterEnabled || EF.Property<bool>(e, nameof(IApproveable.IsApproved));

            expression = expression == null
                ? approvalFilter
                : QueryFilterExpressionHelper.CombineExpressions(expression, approvalFilter);
        }

        return expression;
    }
}

This mapping step is what connects IDataFilter<IPublishedFilter> and IDataFilter<IApprovedFilter> to entity-level predicates. Without this step, HasAbpQueryFilter expressions remain always active.

Important: Note that we use DateTime (not DateTime?) in the filter expression to match the entity property type. Adjust accordingly if your entity uses nullable DateTime?.

Step 4: Disable Custom Filters with IDataFilter

Once custom filters are mapped to the ABP data-filter pipeline, you can disable them just like built-in filters:

public class BookAppService : ApplicationService
{
    private readonly IRepository<Book, Guid> _bookRepository;
    private readonly IDataFilter<IPublishedFilter> _publishedFilter;
    private readonly IDataFilter<IApprovedFilter> _approvedFilter;

    public BookAppService(
        IRepository<Book, Guid> bookRepository,
        IDataFilter<IPublishedFilter> publishedFilter,
        IDataFilter<IApprovedFilter> approvedFilter)
    {
        _bookRepository = bookRepository;
        _publishedFilter = publishedFilter;
        _approvedFilter = approvedFilter;
    }

    public async Task<List<Book>> GetIncludingUnpublishedAndUnapprovedAsync()
    {
        using (_publishedFilter.Disable())
        using (_approvedFilter.Disable())
        {
            return await _bookRepository.GetListAsync();
        }
    }
}

Advanced: Multiple Filters with User-Defined Functions

Starting from ABP v8.3, you can use user-defined function (UDF) mapping for better performance. This approach generates more efficient SQL and allows EF Core to create better execution plans.

Step 1: Enable UDF Mapping

First, configure your module to use UDF mapping:

// MyProjectModule.cs
using Volo.Abp.EntityFrameworkCore;
using Volo.Abp.EntityFrameworkCore.GlobalFilters;
using Microsoft.Extensions.DependencyInjection;

namespace Library;

[DependsOn(
    typeof(AbpEntityFrameworkCoreModule),
    typeof(AbpDddDomainModule)
)]
public class LibraryModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        Configure<AbpEfCoreGlobalFilterOptions>(options =>
        {
            options.UseDbFunction = true; // Enable UDF mapping
        });
    }
}

Step 2: Define DbFunctions

Create static methods that EF Core will map to database functions:

// LibraryDbFunctions.cs
using Microsoft.EntityFrameworkCore;

namespace Library;

public static class LibraryDbFunctions
{
    public static bool IsPublishedFilter(bool isPublished, DateTime? publishDate)
    {
        return isPublished && (publishDate == null || publishDate <= DateTime.UtcNow);
    }

    public static bool IsApprovedFilter(bool isApproved)
    {
        return isApproved;
    }

    public static bool DepartmentFilter(Guid entityDepartmentId, Guid userDepartmentId)
    {
        return entityDepartmentId == userDepartmentId;
    }
}

Step 4: Apply UDF Filters

Update your DbContext to use the UDF-based filters:

// MyProjectDbContext.cs
protected override void OnModelCreating(ModelBuilder builder)
{
    base.OnModelCreating(builder);

    // Map CLR methods to SQL scalar functions.
    // Create matching SQL functions in a migration.
    var isPublishedMethod = typeof(LibraryDbFunctions).GetMethod(
        nameof(LibraryDbFunctions.IsPublishedFilter),
        new[] { typeof(bool), typeof(DateTime?) })!;
    builder.HasDbFunction(isPublishedMethod);

    var isApprovedMethod = typeof(LibraryDbFunctions).GetMethod(
        nameof(LibraryDbFunctions.IsApprovedFilter),
        new[] { typeof(bool) })!;
    builder.HasDbFunction(isApprovedMethod);

    builder.Entity<Book>(b =>
    {
        b.ToTable("Books");
        b.ConfigureByConvention();

        // ABP way: define separate filters. HasAbpQueryFilter composes them.
        b.HasAbpQueryFilter(book =>
            LibraryDbFunctions.IsPublishedFilter(book.IsPublished, book.PublishDate));

        b.HasAbpQueryFilter(book =>
            LibraryDbFunctions.IsApprovedFilter(book.IsApproved));
    });
}

This approach generates cleaner SQL and improves query performance, especially in complex scenarios with multiple filters.

Working with Complex Filter Combinations

When combining multiple filters, it's important to understand how they interact. Let's explore some common scenarios.

Combining Tenant and Department Filters

In a multi-tenant application, you might need to combine tenant isolation with department-level access control:

public class BookAppService : ApplicationService
{
    private readonly IRepository<Book, Guid> _bookRepository;
    private readonly IDataFilter<IMultiTenant> _tenantFilter;
    private readonly ICurrentUser _currentUser;

    public BookAppService(
        IRepository<Book, Guid> bookRepository,
        IDataFilter<IMultiTenant> tenantFilter,
        ICurrentUser currentUser)
    {
        _bookRepository = bookRepository;
        _tenantFilter = tenantFilter;
        _currentUser = currentUser;
    }

    public async Task<List<BookDto>> GetMyDepartmentBooksAsync()
    {
        var currentUser = _currentUser;
        var userDepartmentId = GetUserDepartmentId(currentUser);

        // Get all books without department filter, then filter in memory
        // (for scenarios where you need custom filter logic)
        using (_tenantFilter.Disable()) // Optional: disable tenant filter if needed
        {
            var allBooks = await _bookRepository.GetListAsync();
            
            // Apply department filter in memory (custom logic)
            var departmentBooks = allBooks
                .Where(b => b.DepartmentId == userDepartmentId)
                .ToList();

            return ObjectMapper.Map<List<Book>, List<BookDto>>(departmentBooks);
        }
    }

    private Guid GetUserDepartmentId(ICurrentUser currentUser)
    {
        // Get user's department from claims or database
        var departmentClaim = currentUser.FindClaim("DepartmentId");
        return Guid.Parse(departmentClaim.Value);
    }
}

Filter Priority and Override

Sometimes you need to override filters in specific scenarios. ABP provides a flexible way to handle this:

public async Task<Book> GetBookForEditingAsync(Guid id)
{
    // Disable soft delete filter to get deleted records for restoration
    using (DataFilter.Disable<ISoftDelete>())
    {
        return await _bookRepository.GetAsync(id);
    }
}

public async Task<Book> GetBookIncludingUnpublishedAsync(Guid id)
{
    // Use GetQueryableAsync to customize the query
    var query = await _bookRepository.GetQueryableAsync();
    
    // Manually apply or bypass filters
    var book = await query
        .FirstOrDefaultAsync(b => b.Id == id);

    return book;
}

Best Practices for Multiple Global Query Filters

When implementing multiple global query filters, consider these best practices:

1. Keep Filters Simple

Complex filter expressions can significantly impact query performance. Keep each condition focused on a single concern. In ABP, you can define them separately with HasAbpQueryFilter, which composes with ABP's built-in filters:

// Good (ABP): separate, focused filters composed by HasAbpQueryFilter
b.HasAbpQueryFilter(b => b.IsPublished);
b.HasAbpQueryFilter(b => b.IsApproved);
b.HasAbpQueryFilter(b => b.DepartmentId == userDeptId);

// Avoid: calling HasQueryFilter multiple times for the same entity
// in plain EF Core (the last call replaces the previous one)
b.HasQueryFilter(b => b.IsPublished);
b.HasQueryFilter(b => b.IsApproved);

2. Use Indexing

Ensure your database has appropriate indexes for filtered columns:

builder.Entity<Book>(b =>
{
    b.HasIndex(b => b.IsPublished);
    b.HasIndex(b => b.IsApproved);
    b.HasIndex(b => b.DepartmentId);
    b.HasIndex(b => new { b.IsPublished, b.PublishDate });
});

3. Consider Performance Impact

Use UDF mapping for better performance with complex filters. Profile your queries and analyze execution plans.

4. Document Filter Behavior

Clearly document which filters are applied to each entity to help developers understand the behavior:

/// <summary>
/// Book entity with the following global query filters:
/// - ISoftDelete: Automatically excludes soft-deleted books
/// - IMultiTenant: Automatically filters by current tenant
/// - IPublishable: Excludes unpublished books (based on IsPublished and PublishDate)
/// - IApproveable: Excludes unapproved books (based on IsApproved)
/// </summary>
/// <remarks>
/// Filter interfaces (IPublishable, IApproveable, IPublishedFilter, IApprovedFilter)
/// are defined in Step 1: Define Filter Interfaces
/// </remarks>
public class Book : AuditedAggregateRoot<Guid>, ISoftDelete, IMultiTenant, IPublishable, IApproveable
{
    public string Name { get; set; }

    public BookType Type { get; set; }

    public DateTime PublishDate { get; set; }

    public float Price { get; set; }

    public bool IsPublished { get; set; }

    public bool IsApproved { get; set; }

    public Guid? TenantId { get; set; }

    public bool IsDeleted { get; set; }

    public Guid DepartmentId { get; set; }
}

Testing Global Query Filters

Testing with global query filters can be challenging. Here's how to do it effectively:

Unit Testing Filters

[Fact]
public void Book_QueryFilter_Should_Filter_Unpublished()
{
    var options = new DbContextOptionsBuilder<BookStoreDbContext>()
        .UseInMemoryDatabase(databaseName: "TestDb")
        .Options;

    using (var context = new BookStoreDbContext(options))
    {
        context.Books.Add(new Book { Name = "Published Book", IsPublished = true });
        context.Books.Add(new Book { Name = "Unpublished Book", IsPublished = false });
        context.SaveChanges();
    }

    using (var context = new BookStoreDbContext(options))
    {
        // Query with filter enabled (default)
        var publishedBooks = context.Books.ToList();
        Assert.Single(publishedBooks);
        Assert.Equal("Published Book", publishedBooks[0].Name);
    }
}

Integration Testing with Filter Control

[Fact]
public async Task Should_Get_Deleted_Book_When_Filter_Disabled()
{
    var dataFilter = GetRequiredService<IDataFilter>();

    // Arrange
    var book = await _bookRepository.InsertAsync(
        new Book { Name = "Test Book" },
        autoSave: true
    );

    await _bookRepository.DeleteAsync(book);

    // Act - with filter disabled
    using (dataFilter.Disable<ISoftDelete>())
    {
        var deletedBook = await _bookRepository
            .FirstOrDefaultAsync(b => b.Id == book.Id);

        deletedBook.ShouldNotBeNull();
        deletedBook.IsDeleted.ShouldBeTrue();
    }
}

Testing Custom Global Query Filters

Here's a complete example of testing custom toggleable filters:

[Fact]
public async Task Should_Filter_Unpublished_Books_By_Default()
{
    // Default: filters are enabled
    var result = await WithUnitOfWorkAsync(async () =>
    {
        var bookRepository = GetRequiredService<IRepository<Book, Guid>>();
        return await bookRepository.GetListAsync();
    });

    // Only published and approved books should be returned
    result.All(b => b.IsPublished).ShouldBeTrue();
    result.All(b => b.IsApproved).ShouldBeTrue();
}

[Fact]
public async Task Should_Return_All_Books_When_Filter_Disabled()
{
    var result = await WithUnitOfWorkAsync(async () =>
    {
        // Disable the published filter to see unpublished books
        using (_publishedFilter.Disable())
        {
            var bookRepository = GetRequiredService<IRepository<Book, Guid>>();
            return await bookRepository.GetListAsync();
        }
    });

    // Should include unpublished books
    result.Any(b => b.Name == "Unpublished Book").ShouldBeTrue();
}

[Fact]
public async Task Should_Combine_Filters_Correctly()
{
    // Test combining multiple filter disables
    using (_publishedFilter.Disable())
    using (_approvedFilter.Disable())
    {
        var bookRepository = GetRequiredService<IRepository<Book, Guid>>();
        var allBooks = await bookRepository.GetListAsync();
        
        // All books should be visible
        allBooks.Count.ShouldBe(5);
    }
}

Tip: When using ABP's test base, inject IDataFilter<IPublishedFilter> and IDataFilter<IApprovedFilter> to control filters in your tests.

Key Takeaways

✅ Global query filters automatically apply filter criteria to all queries, reducing developer error and ensuring consistent data filtering across your application.

✅ ABP Framework provides a sophisticated data filtering system with built-in support for soft delete (ISoftDelete) and multi-tenancy (IMultiTenant), plus the ability to create custom filters.

✅ Use IDataFilter<TFilter> to control filters at runtime, enabling or disabling filters as needed for specific operations.

✅ To make custom filters toggleable, override ShouldFilterEntity and CreateFilterExpression in your DbContext. Using only HasAbpQueryFilter creates filters that are always active.

✅ Combine multiple filters carefully and consider performance implications, especially with complex filter expressions.

✅ Leverage user-defined function (UDF) mapping for better SQL generation and query performance, available since ABP v8.3.

✅ Always test filter behavior to ensure filters work as expected in different scenarios, including edge cases.

Conclusion

Global query filters are essential for building secure, well-isolated applications. ABP Framework's data filtering system provides a robust foundation that builds on EF Core's capabilities while adding convenient features like runtime filter control and UDF mapping optimization.

By implementing multiple global query filters strategically, you can ensure data isolation, simplify your query logic, and reduce the risk of accidentally exposing unauthorized data. Remember to keep filters simple, add appropriate database indexes, and test thoroughly to maintain optimal performance.

Start implementing global query filters in your ABP applications today to leverage automatic data filtering across all your repositories and queries.

See Also

• ABP Data Filtering Documentation
• EF Core Global Query Filters
• ABP Multi-Tenancy Documentation
• Using User-defined function mapping for global filters

References

• ABP Framework Documentation
• Entity Framework Core Documentation
• EF Core Global Query Filters
• User-defined Function Mapping

We are excited to announce the AI Management Module, a powerful new module to the ABP Platform that makes managing AI capabilities in your applications easier. No need to redeploy your application, now you can configure, test, and manage your AI integrations on the fly through an intuitive user interface!

What is the AI Management Module?

Built on top of the ABP Framework's AI infrastructure, the AI Management Module allows you to manage AI workspaces dynamically without touching your code. Whether you're building a customer support chatbot, adding AI-powered search, or creating intelligent automation workflows, this module provides everything you need to manage AI integrations through a user-friendly interface.

Note: The AI Management Module is currently in preview and available to ABP Team or higher license holders.

What it offers?

Manage AI Without Redeployment

Create, configure, and update AI workspaces directly from the UI. Switch between different AI providers (OpenAI, Azure OpenAI, Ollama, etc.), change models, adjust prompts, and test configurations, all without restarting your application or deploying new code.

Built-In Chat Interface

Test your AI workspaces immediately with the included chat interface in playground pages. Verify your configurations work correctly before using them in production. Perfect for experimenting with different models, prompts, and settings.

Flexible for Any Architecture

Whether you're building a monolith, microservices, or something in between, the module adapts to your needs:

• Host AI management directly in your application with full UI and database
• Deploy a centralized AI service that multiple applications can consume
• Use it as an API gateway pattern for your microservices

Works with Any AI Provider

Even AI Management module doesn't implement all the providers by default, it provides extensibility options with a good abstraction for other providers like Azure, Anthropic Claude, Google Gemini, and more. Or you can directly use the OpenAI adapter with LLMs that support OpenAI API.

• Example of using Gemini as an OpenAI provider:

  

You can even add your own custom AI providers: learn how to implement a custom AI provider factory in the documentation.

Ready to Use Chat Widget

Drop a compact, pre-built chat widget into any page with minimal code. It includes streaming support, conversation history, and API integration for customization.

• Simple to use with minimal code

  @await Component.InvokeAsync(typeof(ChatClientChatViewComponent), new ChatClientChatViewModel
  {
      WorkspaceName = "StoryTeller",
  })
  

• And result is a working, pre-integrated widget

  

• See the widget documentation for details and all parameters for customization.

Security

Control who can manage and use AI workspaces with permission-based access control. Isolate your AI configurations by using workspaces with different permissions. Also, resource based authorization on workspaces is on the way and will be available in the next versions. It'll allow you to manage access to specific workspaces by a user or role.

Getting Started

Installation is straightforward using the ABP Studio. You can just enable AI Management module while creating a new project with ABP Studio and configure your preferred AI provider and model in the solution creation wizard.

Roadmap

v10.0 ✅

• Workspace Management
• MVC UI
• Playground
  • Chat History (Client-Side)
• Client Components
• Integration to Startup Templates

v10.1 ✅

• Blazor UI
• Angular UI
• Resource based authorization on Workspaces
• Agent-Framework compatibility examples

Future Goals

• Microservice templates
• MCP Support
• RAG with file upload (md, pdf, txt)
• Chat History (Server-Side Conversations)
• OpenAI Compatible Endpoints
• Tenant-Based Configuration
• Extended RAG capabilities, (ie. providing application data as tools)

Ready to Get Started?

The AI Management Module is available now for ABP Team and higher license holders.

Learn More:

• AI Management Module Documentation - All features, scenarios, and technical details.
• AI Infrastructure Documentation - Understanding AI workspaces in the framework.
• Usage Scenarios - Examples for different architectures.

The AI Management Module is currently in preview. We're excited to hear your feedback as we continue to improve and add new features!

We are glad to announce that ABP 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, 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 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:

dotnet tool install -g Volo.Abp.Studio.Cli

Or to update the existing CLI, you can run the following command:

dotnet tool update -g Volo.Abp.Studio.Cli

After installing/updating the ABP CLI, you can use the update command to update all the ABP related NuGet and NPM packages in your solution as follows:

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

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
  • Optimize your .NET app for production Part 1
  • Optimize your .NET app for production Part 2
  • Return Code vs Exceptions: Which One is Better?
• Sumeyye Kurtulus
  • Building Scalable Angular Apps with Reusable UI Components
  • Angular Library Linking Made Easy: Paths, Workspaces and Symlinks
• erdem çaygör
  • Building Dynamic Forms in Angular for Enterprise
  • From Server to Browser: Angular TransferState Explained
• Mansur Besleney
  • Top 10 Exception Handling Mistakes in .NET
• Berkan Şaşmaz
  • How to Dynamically Set the Connection String in EF Core
• Oğuzhan Ağır
  • The ASP.NET Core Dependency Injection System
• Selman Koç
  • 5 Things Keep in Mind When Deploying Clustered Environment
• Muhammet Ali ÖZKAYA
  • Repository Pattern in ASP.NET Core
• Armağan Ünlü
  • UI/UX Trends That Will Shape 2026
• Salih
  • What is That Domain Service in DDD for .NET Developers?
  • Building an API Key Management System with ABP Framework
• Fahri Gedik
  • Signal-Based Forms in Angular

Thanks to the ABP Community for all the content they have published. You can also post your ABP related (text or video) content to the ABP Community.

About the Next Version

The next feature version will be 10.1. You can follow the release planning here. Please submit an issue if you have any problems with this version.

If you’ve ever shoved a bunch of Guid.NewGuid() values into a SQL Server table with a clustered index on the PK, you’ve probably felt the pain: Index fragmentation so bad you could use it as modern art. Inserts slow down, page splits go wild, and your DBA starts sending you passive-aggressive Slack messages.

And yet… we keep doing it. Why? Because GUIDs are easy. They’re globally unique, they don’t need a round trip to the DB, and they make distributed systems happy. But here’s the catch: random GUIDs are absolute chaos for ordered indexes.

The Problem with Vanilla GUIDs

• Randomness kills order — clustered indexes thrive on sequential inserts; random GUIDs force constant reordering.

• Performance hit — every insert can trigger page splits and index reshuffling.

• Storage bloat — fragmentation means wasted space and slower reads.

Sure, you could switch to int or long identity columns, but then you lose the distributed generation magic and security benefits (predictable IDs are guessable).

Sequential GUIDs to the Rescue

Sequential GUIDs keep the uniqueness but add a predictable ordering component, usually by embedding a timestamp in part of the GUID. This means:

• Inserts happen at the “end” of the index, not all over the place.

• Fragmentation drops dramatically.

• You still get globally unique IDs without DB trips.

Think of it as GUIDs with manners.

ABP Framework’s Secret Sauce

Here’s where ABP Framework flexes: it uses sequential GUIDs by default for entity IDs. No ceremony, no “remember to call this helper method”, it’s baked in.

Under the hood:

• ABP ships with IGuidGenerator (default: SequentialGuidGenerator).

• It picks the right sequential strategy for your DB provider:

  • SequentialAtEnd → SQL Server

  • SequentialAsString → MySQL/PostgreSQL

  • SequentialAsBinary → Oracle

• EF Core integration packages auto-configure this, so you rarely need to touch it.

Example in ABP:

public class MyProductService : ITransientDependency
{
    private readonly IRepository<Product, Guid> _productRepository;
    private readonly IGuidGenerator _guidGenerator;


    public MyProductService(
        IRepository<Product, Guid> productRepository,
        IGuidGenerator guidGenerator)
    {
        _productRepository = productRepository;
        _guidGenerator = guidGenerator;
    }


    public async Task CreateAsync(string productName)
    {
        var product = new Product(_guidGenerator.Create(), productName);
        await _productRepository.InsertAsync(product);
    }
}

No Guid.NewGuid() here, _guidGenerator.Create() gives you a sequential GUID every time.

Benefits of Sequential GUIDs

Let’s say you’re inserting 1M rows into a table with a clustered primary key:

• Random GUIDs → fragmentation ~99%, insert throughput tanks.

• Sequential GUIDs → fragmentation stays low, inserts fly.

In high-volume systems, this difference is not academic, it’s the difference between smooth scaling and spending weekends rebuilding indexes.

When to Use Sequential GUIDs

• Distributed systems that still want DB-friendly inserts.

• High-write workloads with clustered indexes on GUID PKs.

• Multi-tenant apps where IDs need to be unique across tenants.

When Random GUIDs Still Make Sense

• Security through obscurity, if you don’t want IDs to hint at creation order.

• Non-indexed identifiers, fragmentation isn’t a concern.

The Final Take

ABP’s default sequential GUID generation is one of those “small but huge” features. It’s the kind of thing you don’t notice until you benchmark, and then you wonder why you ever lived without it.

Links

You may want to check the following references to learn more about sequential GUIDs:

• ABP Framework Documentation: Sequential GUIDs

We are happy to release ABP version 10.0 RC (Release Candidate). This blog post introduces the new features and important changes in this new version.

Try this version and provide feedback for a more stable version of ABP v10.0! Thanks to you in advance.

Get Started with the 10.0 RC

You can check the Get Started page to see how to get started with ABP. You can either download ABP Studio (recommended, if you prefer a user-friendly GUI application - desktop application) or use the ABP CLI.

By default, ABP Studio uses stable versions to create solutions. Therefore, if you want to create a solution with a preview version, first you need to create a solution and then switch your solution to the preview version from the ABP Studio UI:

Migration Guide

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.3 or earlier: ABP Version 10.0 Migration Guide.

What's New with ABP v10.0?

In this section, I will introduce some major features released in this version. Here is a brief list of titles explained in the next sections:

• Upgraded to .NET 10.0
• Upgraded to Blazorise 1.8.2
• New Module: Workflow (Elsa)
• New Object Mapper: Mapperly
• Localization: Nested object support in JSON files
• Support EF Core Shared Entity Types on Repositories
• Add failure retry policy to InboxProcessor
• Migrate to New Esbuild-based Angular Builder
• Angular SSR support

Upgraded to .NET 10.0

We've upgraded ABP to .NET 10.0, so you need to move your solutions to .NET 10.0 if you want to use ABP 10.0.

Since the stable version of .NET 10 hasn't been released yet, we upgraded ABP to .NET v10.0-rc.1. Stable NET 10 is scheduled to launch as a Long-Term Support (LTS) release during .NET Conf 2025, which takes place November 11-13, 2025. We'll update the ABP Platform to the .NET 10 as soon as possible official .NET 10 release is completed.

Upgraded to Blazorise v1.8.2

Upgraded the Blazorise library to v1.8.2 for Blazor UI. If you are upgrading your project to v10.0 RC, please ensure that all the Blazorise-related packages are using v1.8.2 in your application. Otherwise, you might get errors due to incompatible versions.

See #23717 for the updated NuGet packages.

New Module: Workflow (Elsa)

ABP now ships a Workflow module that integrates Elsa Workflows to build visual, long-running, event-driven workflows in your ABP solutions (monolith or microservices). It provides seamless integration with ABP authentication/authorization, distributed event bus, persistence, background processing and includes support for hybrid UIs via Elsa Studio.

For a hands-on reference showcasing an end-to-end order/payment workflow across services, see the sample: Elsa Workflows - Sample Workflow Demo. For capabilities, installation and configuration details (activities, storage, hosting, dashboard), see the module docs: Workflow (Elsa) module.

New Object Mapper: Mapperly

ABP modules now use Mapperly as the default object-to-object mapper. Mapperly is a compile-time, source generator–based mapper that removes runtime reflection and offers better performance with simpler maintenance. For background and implementation details, see the planning issue and the PR: Switch to another object mapping library and Use Mapperly to replace AutoMapper in all modules.

The Volo.Abp.AutoMapper package remains available for backward compatibility. You can keep using AutoMapper in your solutions, but you are responsible for obtaining and managing its license if needed. For upgrade guidance and practical steps, follow the migration guide: AutoMapper to Mapperly.

Localization: Nested object support in JSON files

ABP now supports nested objects (and arrays) in JSON localization files, allowing you to organize translations hierarchically and access them using the double underscore (__) separator. This improves maintainability for larger resource files and aligns lookups with familiar key paths.

See the PR for details: feat(l8n): add support for nested objects in localization files.

Declaration (nested objects):

{
  "culture": "en",
  "texts": {
    "MyNestedTranslation": {
      "SomeKey": "Some nested value",
      "SomeOtherKey": "Some other nested value"
    }
  }
}

Usage:

L["MyNestedTranslation__SomeKey"];
L["MyNestedTranslation__SomeOtherKey"];

Declaration (arrays):

{
  "culture": "en",
  "texts": {
    "Menu": {
      "Items": ["Home", "About", "Contact"]
    }
  }
}

Usage:

L["Menu__Items__0"]; // Home
L["Menu__Items__2"]; // Contact

Support EF Core Shared Entity Types on Repositories

ABP repositories now support EF Core shared-type entity types by allowing a custom entity name to be set on a repository before performing operations. Internally, this uses EF Core's DbContext.Set<T>(string name) to target the correct DbSet/table for the same CLR type, enabling scenarios like per-tenant tables, archives, or partitioning, and you can switch the target at runtime. See the PR: Support EF Core Shared Entity Types on Repositories and the EF Core documentation on shared-type entity types.

Example:

// Set the shared entity name so repository operations target that table
var repo = serviceProvider.GetRequiredService<IRepository<MyEntity, Guid>>();
repo.SetCustomEntityName("MyEntity_TenantA");
var list = await repo.GetListAsync();

// Switch to another shared name later on the same instance
repo.SetCustomEntityName("MyEntity_Archive");
await repo.InsertAsync(new MyEntity { /* ... */ });

Add failure retry policy to InboxProcessor

InboxProcessor now supports configurable failure handling strategies per event: Retry (default; reprocess in the next cycle), RetryLater (skip the failing event and retry it later with exponential backoff; the backoff factor and maximum retries are configurable), and Discard (drop the failing event). This prevents a single failing handler from blocking subsequent events and improves resiliency.

Note: This is a breaking change because IncomingEvent entity properties were updated. See the PR for details: Add failure retry policy to InboxProcessor.

Migrate to New Esbuild-based Angular Builder

We've migrated ABP Angular templates and packages to Angular's new esbuild-based build system (introduced in Angular 17+ and fully supported in Angular 20) to deliver faster builds, modern ESM support, built-in SSR/prerender capabilities, and a better development experience. This change is non-breaking for existing apps. See the tracking issue and PR: Angular - Migrate to New Esbuild-based Angular Builder, feat: Update Angular templates to Angular 20 new build system.

Key updates in templates/config:

• Builder switched from @angular-devkit/build-angular:browser to @angular-devkit/build-angular:application.
• main option replaced by browser; polyfills moved to array form.
• TypeScript updated to es2020 with esModuleInterop: true; module target esnext.

More Angular updates:

• Unit tests have been updated for the new builder and configuration: #23460.

Warnings:

• Constructor injections migrated to Angular's inject() function. If you extend a class and previously called super(...) with injected params, remove those parameters. See: Angular inject() migration.
• provideLogo and withEnvironmentOptions have moved from LeptonX packages to @abp/ng.theme-shared.
• If you use the new application builder and have tsconfig.json path mappings that point into node_modules, remove those mappings and prefer symlinks instead. See a symlink reference: Creating symbolic links.

Angular SSR support

ABP Angular templates now support Server-Side Rendering (SSR) with the Angular Application Builder, enabling hybrid rendering (SSR + CSR) for improved first paint, SEO and perceived performance. This includes SSR-safe platform checks (no direct window/location/localStorage), OIDC auth compatibility via cookie-backed storage, and TransferState to prevent duplicate HTTP GETs during hydration. For implementation highlights and usage (including how to run the SSR dev server and the transferStateInterceptor), see the issue and PR: Angular SSR, Hybrid Rendering & Application Builder.

See Angular's official guide for details on hybrid rendering (prerender + SSR + CSR): Angular SSR and on the builder migration: Angular build system migration.

Community News

Recent Events

We recently hosted two sessions of ABP Community Talks:

Community Talks 2025.06: Microservices with ABP Template

The Easiest Way to Get Started with Microservices on .NET Using ABP Microservice Solution Template: a deep dive into ABP’s microservice template, showing how ABP Studio streamlines creating, running, and scaling distributed systems. See the event page: Community Talks: Microservices with ABP Template.

Community Talks 2025.07: Developer-Friendly CMS for .NET

Beyond WordPress: A Developer-Friendly CMS for .NET: an overview of building custom web apps with ABP CMS Kit, integrating content management with your application code. Learn more: Community Talks: Developer-Friendly CMS for .NET.

Weekly Webinar: Discover ABP Platform

We’ve started a weekly live webinar series designed for developers who want to get the most out of the ABP Platform. This event is designed for those new to ABP to help you understand its core features, capabilities, and licensing models.

Every webinar features live coding demos, practical examples, and an open Q&A segment where you can get your questions answered directly by the ABP team. Whether you’re just starting with ABP or looking to explore advanced scenarios, these sessions will help you build better apps faster.

👉 Register here to join an upcoming session!

New ABP Community Articles

There are exciting articles contributed by the ABP community as always. I will highlight some of them here:

• Alper Ebiçoğlu:
  • High-Performance .NET Libraries You Didn’t Know You Needed
  • .NET 10: What You Need to Know (LTS Release, Coming November 2025)
  • Best Free Alternatives to AutoMapper in .NET — Why We Moved to Mapperly
• Liming Ma:
  • Keep Track of Your Users in an ASP.NET Core Application
  • App Services vs Domain Services
  • Using Hangfire Dashboard in ABP API Website
• Fahri Gedik:
  • Backward‑Compatible REST APIs in .NET Microservices
  • Best Practices for Designing Backward‑Compatible REST APIs in a Microservice Solution for .NET Developers
  • Stepbystep AWS Secrets Manager Integration in ABP
• Engincan Veske:
  • Building a Permission-Based Authorization System for ASP.NET Core
  • Where and How to Store Your Blob Objects in .NET
• Salih Özkara:
  • Truly Layering a .NET Application Based on DDD Principles
• Kori Francis:
  • ABP Postmark Email Integration, Templated Emails
  • Universal Redis Configuration in ABP Aspire Deployment
• Sajankumar Vijayan:
  • Multi-tenant SaaS apps, Cloudflare DNS
• Selman Koc:
  • Azure DevOps, CI/CD pipelines, Azure DevOps best practices
• Sümeyye Kurtuluş:
  • ABP Now Supports Angular Standalone Applications
  • Supercharge your Angular app: A developer's guide to unlock
• Mansur Besleney:
  • Demystified Aggregates in DDD & .NET: From Theory to Practice
  • How to Build Persistent Background Jobs with ABP Framework and Quartz
  • Angular Application Builder: Transitioning from Webpack to Esbuild
• Muhammet Ali Özkaya:
  • Implementing Unit of Work with ASP.NET Core
• Enis Necipoğlu:
  • Integration Services Explained: What They Are & When to Use
• Berkan Şaşmaz:
  • How to Dynamically Set the Connection String in EF Core
• Emre Kara:
  • A Developer's Guide to Distributed Event Buses in .NET
• Oğuzhan Ağır:
  • In-Memory Background Job Queue in ASP.NET Core
• Alperen Samurlu:
  • How Can We Apply the DRY Principle in a Better Way?
• Ahmet Çelik:
  • Best Practices Guide for REST API Design
• Elanur Oğuz:
  • Web Design Basics for Graphic Designers Who Don't Code
• Seda Şen:
  • Color Psychology in Web Design
• Halime Karayay:
  • 10 Modern HTML CSS Techniques Every Designer Should Know
• Anto Subash:
  • ABP React CMS Module: Building Dynamic Pages with Puck
• Yağmur Çelik:
  • Integration Testing Best Practices for Building a Robust API
• Suhaib Mousa:
  • Visual Studio 2026 - What's New and Why I'm Excited About It
• Alex Maiereanu:
  • ABP-Hangfire-AzurePostgreSQL
• Jack Fistelmann:
  • ABP and maildev
• Tarık Özdemir:
  • AI-First Architecture for .NET Projects: A Modern Blueprint
• Prabhjot Singh:
  • Switching from Project References to Package References
• Yunus Emre Kalkan:
  • New in ABP Studio: Docker Container Management
• Burak Demir:
  • Solving MongoDB GUID Issues After an ABP Framework Upgrade

Thanks to the ABP Community for all the content they have published. You can also post your ABP-related (text or video) content to the ABP Community.

Conclusion

This version comes with some new features and a lot of enhancements to the existing features. You can see the Road Map documentation to learn about the release schedule and planned features for the next releases. Please try ABP v10.0 RC and provide feedback to help us release a more stable version.

Thanks for being a part of this community!

If you’ve been building with ABP for a while, you’ve probably used Application Services for your UI and APIs in your .NET and ASP.NET Core apps. Integration Services are similar—but with a different mission: they exist for service-to-service or module-to-module communication, not for end users.

If you want the formal spec, see the official doc: Integration Services. This post is the practical, no-fluff guide.

What is an Integration Service?

An Integration Service is an application service or ASP.NET Core MVC controller marked with the [IntegrationService] attribute. That marker tells ABP “this endpoint is for internal communication.”

• They are not exposed by default (safer for reusable modules and monoliths).
• When exposed, their route prefix is /integration-api (so you can easily protect them at your gateway or firewall).
• Auditing is disabled by default for them (less noise for machine-to-machine calls).

Quick look:

[IntegrationService]
public interface IProductIntegrationService : IApplicationService
{
    Task<List<ProductDto>> GetProductsByIdsAsync(List<Guid> ids);
}

public class ProductIntegrationService : ApplicationService, IProductIntegrationService
{
    public Task<List<ProductDto>> GetProductsByIdsAsync(List<Guid> ids)
    {
        // fetch and return minimal product info for other services/modules
    }
}

Are they HTTP endpoints?

• By default: no (they won’t be reachable over HTTP in the ASP.NET Core routing pipeline).
• If you need them over HTTP (typically for microservices), explicitly enable:

Configure<AbpAspNetCoreMvcOptions>(options =>
{
    options.ExposeIntegrationServices = true;
});

Once exposed, ABP puts them under /integration-api/... instead of /api/... in the ASP.NET Core routing pipeline. That’s your hint to restrict them from public internet access.

Enable auditing (optional)

If you want audit logs for integration calls, enable it explicitly:

Configure<AbpAuditingOptions>(options =>
{
    options.IsEnabledForIntegrationServices = true;
});

When should you use Integration Services?

• Internal, synchronous operations between services or modules.
• You need a “thin” API designed for other services (not for UI): minimal DTOs, no view concerns, predictable contracts.
• You want to hide these endpoints from public clients, or only allow them inside your private network or k8s cluster.
• You’re packaging a reusable module that might be used in both monolith and microservice deployments.

When NOT to use them

• Public APIs or anything intended for browsers/mobile apps → use regular application services/controllers.
• Asynchronous cross-service workflows → consider domain events + outbox/inbox; use Integration Services for sync calls.
• Complex, chatty UI endpoints → those belong to your external API surface, not internal integration.

Common use-cases and examples

• Identity lookups across services: an Ordering service needs basic user info from the Identity service.
• Permission checks from another module: a CMS module asks a Permission service for access decisions.
• Product data hydrations: a Cart service needs minimal product details (price, name) from Catalog.
• Internal admin/maintenance operations that aren’t meant for end users but are needed by other services.

Example: microservice-to-microservice call

1. Mark and expose the integration service in the target service:

[IntegrationService]
public interface IUserIntegrationService : IApplicationService
{
    Task<UserBriefDto?> FindByIdAsync(Guid id);
}

Configure<AbpAspNetCoreMvcOptions>(o => o.ExposeIntegrationServices = true);

2. In the caller service, add an HTTP client proxy only for Integration Services if you like to keep things clean:

services.AddHttpClientProxies(
    typeof(TargetServiceApplicationModule).Assembly,
    remoteServiceConfigurationName: "TargetService",
    asDefaultServices: true,
    applicationServiceTypes: ApplicationServiceTypes.IntegrationServices);

3. Call it just like a local service (ABP’s HTTP proxy handles the wire):

public class OrderAppService : ApplicationService
{
    private readonly IUserIntegrationService _userIntegrationService;

    public OrderAppService(IUserIntegrationService userIntegrationService)
    {
        _userIntegrationService = userIntegrationService;
    }

    public async Task PlaceOrderAsync(CreateOrderDto input)
    {
        var user = await _userIntegrationService.FindByIdAsync(CurrentUser.GetId());
        // validate user status, continue placing order...
    }
}

Monolith vs. Microservices

• Monolith: keep them unexposed and call via DI in-process. You get the same clear contract with zero network overhead.
• Microservices: expose them and route behind your gateway. The /integration-api prefix makes it easy to firewall/gateway-restrict.

Practical tips

• Keep integration DTOs lean and stable. These are machine contracts—don’t mix UI concerns.
• Name them clearly (e.g., UserIntegrationService) so intent is obvious.
• Guard your ASP.NET Core gateway application: block /integration-api/* from public traffic.
• Enable auditing only if you truly need the logs for these calls.

Further reading

• Official docs: Integration Services

That’s it! Integration Services give you a clean, intentional way to design internal APIs—great in monoliths, essential in microservices.

ABP Framework covers all the multi-tenant features already and you can easily build a SAAS application with ABP Framework. But... "How about While Labeling?

White Labeling

White-labeling refers to the practice of developing a software solution that can be rebranded and resold by different companies under their own branding. So, our purpose is to build a software solution that can be rebranded by the tenant admin itself by changing the theme, logo, etc.

Getting Started

I skip the steps to create a new ABP solution and go straight to the point. I'll show you how to white-label to your existing ABP solution. Let's see prerequisites first.

• An ABP solution in MVC UI with Basic Theme.
  • (other templates should be ok, but you need to use the correct components to override)
• Setting Management module is installed. (It's already installed in the ABP project templates)

Plan

The plan is to create a new setting group and settings in the Setting Management module to use different settings for each tenant. We'll provide a UI to the tenant admin to change the settings. Then, we'll use these settings to change the theme, logo, etc by overriding the theme components.

Create a new setting group

Navigate to WhileLabelAppSettingDefinitionProvider.cs file and add a new setting that we'll use:

public class WhileLabelAppSettingDefinitionProvider : SettingDefinitionProvider
{
    public override void Define(ISettingDefinitionContext context)
    {
        // Skip the default values since we'll do not change anything if it's not set.
        context.Add(
            new SettingDefinition(WhileLabelAppSettings.AppName),
            new SettingDefinition(WhileLabelAppSettings.Theme),
            new SettingDefinition(WhileLabelAppSettings.AppLogo),
            new SettingDefinition(WhileLabelAppSettings.PrimaryColor)
        );
    }
}

// WhileLabelAppSettings.cs
public static class WhileLabelAppSettings
{
    private const string Prefix = "WhileLabelApp";
    public const string AppName = Prefix + "AppName";
    public const string AppLogo = Prefix + "AppLogo";
    public const string Theme = Prefix + "Theme";
    public const string PrimaryColor = Prefix + "PrimaryColor";
}

Now, we'll provide an API to get and update the settings by using Application Services.

• Define a simple permission for the settings.

public class WhileLabelAppPermissionDefinitionProvider : PermissionDefinitionProvider
{
    public override void Define(IPermissionDefinitionContext context)
    {
        var myGroup = context.AddGroup(WhileLabelAppPermissions.GroupName);

        // Add related constant in WhileLabelAppPermissions.cs and add localization in en.json
        myGroup.AddPermission(WhileLabelAppPermissions.WhiteLabelSettings, L("Permission:WhiteLabelSettings"));
    }
    // ...
}

Building the Settings UI

Now, we'll build the settings UI. We'll use the Setting Management module to create a new setting group and settings. Each tenant will see their own settings in the Setting Management page. To build this UI, we'll need to implement by using ISettingManager from Setting Management module. It provides keeping the settings tenant-specific.

• Create IWhiteLabelSettingsAppService interface in Aplication.Contracts project and WhiteLabelSettingsAppService class in Application project.

public interface IWhiteLabelSettingsAppService : IApplicationService
{
    Task<WhiteLabelSettingsDto> GetAsync();
    Task UpdateAsync(WhiteLabelSettingsDto input);
}

public class WhiteLabelSettingsDto
{
    public string? AppName { get; set; }
    public string? AppLogo { get; set; }
    public string? Theme { get; set; }
    public string? PrimaryColor { get; set; }
}

public class WhiteLabelSettingsAppService(ISettingManager settingManager) : ApplicationService, IWhiteLabelSettingsAppService   
{
    [Authorize(WhileLabelAppPermissions.WhiteLabelSettings)]
    public async Task<WhiteLabelSettingsDto> GetAsync()
    {
        return new WhiteLabelSettingsDto
        {
            AppName = await settingManager.GetOrNullForCurrentTenantAsync(WhileLabelAppSettings.AppName),
            AppLogo = await settingManager.GetOrNullForCurrentTenantAsync(WhileLabelAppSettings.AppLogo),
            Theme = await settingManager.GetOrNullForCurrentTenantAsync(WhileLabelAppSettings.Theme),
            PrimaryColor = await settingManager.GetOrNullForCurrentTenantAsync(WhileLabelAppSettings.PrimaryColor)
        };
    }

    [Authorize(WhileLabelAppPermissions.WhiteLabelSettings)]
    public async Task UpdateAsync(WhiteLabelSettingsDto input)
    {
        await settingManager.SetForCurrentTenantAsync(WhileLabelAppSettings.AppName, input.AppName);
        await settingManager.SetForCurrentTenantAsync(WhileLabelAppSettings.AppLogo, input.AppLogo);
        await settingManager.SetForCurrentTenantAsync(WhileLabelAppSettings.Theme, input.Theme);
        await settingManager.SetForCurrentTenantAsync(WhileLabelAppSettings.PrimaryColor, input.PrimaryColor);
    }
}

Now we're ready to build the UI. I'll use pre-defined bootstrap themes to allow tenants to choose a base design.

Download 3 themes from here and put them in the wwwroot/themes folder. I downloaded darky, morph and quartz themes and renamed them to darky.min.css, morph.min.css and quartz.min.css respectively. They all were bootstrap.min.css before renaming.

• Create a new ViewComponent in Web project.
  • /Components/WhiteLabelSettings/Default.cshtml
  • /Components/WhiteLabelSettings/WhiteLabelSettingsViewComponent.cshtml.cs

@using Acme.WhileLabelApp.Settings
@model WhiteLabelSettingsDto

<form id="WhiteLabelSettingsForm">
    <abp-input asp-for="AppName" />
    <abp-input asp-for="AppLogo" />

    <div class="form-group mb-3">
        @Html.LabelFor(m => m.Theme)
        <select class="form-select" asp-for="Theme">
            <option value="">Default</option>
            <option value="darky">Darky</option>
            <option value="morph">Morph</option>
            <option value="quartz">Quartz</option>
        </select>
    </div>

    <div class="form-group">    
        @Html.LabelFor(m => m.PrimaryColor)
        <div class="mb-2">
            <input type="checkbox" id="useDefaultColor" class="form-check-input me-2" />
            <label for="useDefaultColor" class="form-check-label">Use Default</label>
        </div>
        <div id="colorPickerContainer">
            <input type="color" class="form-control w-25" asp-for="PrimaryColor" id="primaryColorPicker" />
        </div>
    </div>

    <hr />
    <abp-button type="submit" class="mt-3" button-type="Primary" text="Save" icon="fa-solid fa-save" />
</form>


<script>
    $(function() {
        const form = $('#WhiteLabelSettingsForm');
        const useDefaultCheckbox = $('#useDefaultColor');
        const colorPickerContainer = $('#colorPickerContainer');
        const primaryColorPicker = $('#primaryColorPicker');
        
        // Initialize checkbox state based on existing value
        
        @if (Model.PrimaryColor.IsNullOrEmpty())
        {
            <text>
                useDefaultCheckbox.prop('checked', true);
                colorPickerContainer.hide();
            </text>
        }
        
        // Handle checkbox change
        useDefaultCheckbox.change(function() {
            if (this.checked) {
                colorPickerContainer.hide();
                primaryColorPicker.val(''); // Clear the color picker value
            } else {
                colorPickerContainer.show();
            }
        });
        
        form.submit(function(e) {
            e.preventDefault();
            
            var data = form.serializeFormToObject();
            
            // If "Use Default" is checked, set PrimaryColor to null
            if (useDefaultCheckbox.prop('checked')) {
                data.PrimaryColor = null;
            }

            acme.whileLabelApp.settings.whiteLabelSettings.update(data).then(function() {
                abp.notify.success('White label settings updated successfully');
                window.location.reload();
            }).catch(function(error) {
                abp.notify.error(error.message);
            });
        });
    });
    
</script>

public class WhiteLabelSettingsViewComponent(IWhiteLabelSettingsAppService whiteLabelSettingsAppService) : AbpViewComponent
{
    public async Task<IViewComponentResult> InvokeAsync()
    {
        var settings = await whiteLabelSettingsAppService.GetAsync();
        return View("~/Components/WhiteLabelSettings/Default.cshtml", settings);
    }
}

• Create a new WhiteLabelAppSettingPageContributor to add the ViewComponent to the Setting Management page.

public class WhiteLabelAppSettingPageContributor : ISettingPageContributor
{
    public async Task<bool> CheckPermissionsAsync(SettingPageCreationContext context)
    {
        var authService = context.ServiceProvider.GetRequiredService<IAuthorizationService>();
        return await authService.IsGrantedAsync(WhileLabelAppPermissions.WhiteLabelSettings);
    }

    public Task ConfigureAsync(SettingPageCreationContext context)
    {
        var l = context.ServiceProvider.GetRequiredService<IStringLocalizer<WhileLabelAppResource>>();
         context.Groups.Add(
            new SettingPageGroup(
                "Volo.Abp.WhiteLabelSettingsGroup",
                l["WhiteLabelSettings"],
                typeof(WhiteLabelSettingsViewComponent),
                order : 1
            )
        );

        return Task.CompletedTask;
    }
}

• ⚠️ Important ⚠️
  • You need to add the WhiteLabelAppSettingPageContributor to the SettingManagementPageOptions in the WhileLabelAppWebModule.cs file.

Configure<SettingManagementPageOptions>(options =>
{
    options.Contributors.Add(new WhiteLabelAppSettingPageContributor());
});

Applying the Styles

Application Name & Logo

Now we're ready to apply the styles. Let's start with BrandingProvider.

[Dependency(ReplaceServices = true)]
public class WhileLabelAppBrandingProvider(
    IStringLocalizer<WhileLabelAppResource> l,
    ISettingProvider settingProvider
    ) : DefaultBrandingProvider
{
    public override string AppName 
    { 
        get 
        {
            var appNameSettingValue = settingProvider.GetOrNullAsync(WhileLabelAppSettings.AppName)
            .GetAwaiter().GetResult();
            
            return appNameSettingValue ?? l["AppName"];
        }
    }


    public override string? LogoUrl
    {
        get
        {
            var logoUrlSettingValue = settingProvider.GetOrNullAsync(WhileLabelAppSettings.AppLogo).GetAwaiter().GetResult();
            return logoUrlSettingValue ?? base.LogoUrl;
        }
    }
}

⚠️ Unfortunatelly, BrandingProvider doesn't support async operations since it implemented to use properties. As a best practice, overriding the logo component from the theme is a better approach.

Theme for each tenant

Now, we'll apply the bootstrap theme to the application. To achieve this, we'll create a new BundleContributor and override bundle files according to the setting value of the tenant.

• Create a new WhiteLabelAppBundleContributor class:

public class WhiteLabelAppBundleContributor(ISettingProvider settingProvider) : BundleContributor
{
    public override async Task ConfigureBundleAsync(BundleConfigurationContext context)
    {
        var theme = await settingProvider.GetOrNullAsync(WhileLabelAppSettings.Theme);

        if (theme.IsNullOrEmpty())
        {
            return;
        }

        context.Files.RemoveAll(f => f.FileName.Contains("bootstrap"));
        context.Files.Add($"/themes/{theme}.min.css");
    }
}

• Add the bundle contributor to the bundle:

 Configure<AbpBundlingOptions>(options =>
{
    options.StyleBundles.Configure(
        BasicThemeBundles.Styles.Global,
        bundle =>
        {
            bundle.AddFiles("/global-styles.css");
            // Add the bundle contributor to the bundle 👇
            bundle.AddContributors(typeof(WhiteLabelAppBundleContributor));
        }
    );

    // ...
});

Primary Color

Now, we'll apply the primary color to the application. To achieve this, we'll need a new style as the latest element of the head section.

We'll use ABP's Layout Hooks feature to achieve this.

• Create a new component BootstrapStyleViewComponent class:

public class BootstrapStyleViewComponent(ISettingProvider settingProvider) : AbpViewComponent
{
    public async Task<IViewComponentResult> InvokeAsync()
    {
        var primaryColor = await settingProvider.GetOrNullAsync(WhileLabelAppSettings.PrimaryColor);
        return View("~/Components/BootstrapStyle/Default.cshtml", primaryColor);
    }
}

• Add the Default.cshtml file to the Components/BootstrapStyle folder:

@model string
@if (Model.IsNullOrEmpty())
{
    return;
}
<style>
    body {
        --primary-color: @Model;
    }

    .btn-primary {
        background-color: var(--primary-color);
        border-color: var(--primary-color);
    }

    .btn-primary:hover {
        background-color: var(--primary-color);
        border-color: var(--primary-color);
        opacity: 0.8;
    }

    .btn-primary:focus {
        background-color: var(--primary-color);
        border-color: var(--primary-color);
        box-shadow: 0 0 0 0.25rem rgba(var(--primary-color), 0.25);
    }

    .bg-primary {
        background-color: var(--primary-color);
    }

    .text-primary {
        color: var(--primary-color);
    }

    .border-primary {
        border-color: var(--primary-color);
    }

    .btn-outline-primary {
        border-color: var(--primary-color);
        color: var(--primary-color);
    }

    .btn-outline-primary:hover {
        background-color: var(--primary-color);
        border-color: var(--primary-color);
        color: var(--primary-color);
    }

    .btn-outline-primary:focus {
        background-color: var(--primary-color);
        border-color: var(--primary-color);
        color: var(--primary-color);
    }

    .nav-pills .nav-link.active, .nav-pills .show>.nav-link {
        background-color: var(--primary-color);
    }

    .nav-link.active:hover {
        background-color: var(--primary-color);
        opacity: 0.8;
    }
</style>

Result

Now, you can see the result. You can easily customize the application by using the Setting Management page.

Now create another tenant and switch to the new tenant. You can see the application is opened without any changes when you switch to the new tenant. Login with the new tenant's credentials and you can see the tenant has its own branding that it can customize itself.

Source Code

You can find the source code of the example application in GitHub.

Conclusion

ABP Framework provides a powerful set of features to implement white-labeling easily in your application. This tutorial is a proof of concept to show how to implement white-labeling in your application.

In modern web development, integrating dynamic front-end frameworks with server-side technologies has become increasingly essential for creating responsive and interactive applications. This article explores how to effectively use Vue components within Razor Pages in an ABP Framework application. We will delve into the process of consuming endpoints through ABP Client Proxies, leveraging ABP's powerful localization features to enhance user experience, and implementing ABP permissions to ensure secure access control. By the end of this guide, you will have a comprehensive understanding of how to seamlessly blend Vue.js with Razor Pages, empowering you to build robust and user-friendly applications.

This article won't use any SPA approach. The goal of this article is to use Razor Pages with simple Vue components to eliminate jQuery while developing MVC application.

🎉 Also video version is available!

Watch on YouTube Now!

Creating the Solution

Let's create a simple TODO list application to demonstrate how to use Vue components in Razor Pages. I'll build a really simple backend without a connection to a database for demonstration purposes. We will focus on the frontend part.

• Creating a solution with ABP CLI:

abp new MyTodoApp -t app-nolayers -csf

Configure Vue

We need to add the @abp/vue package to the project to use Vue components.

npm install @abp/vue

• Install client libraries by using ABP CLI:

abp install-libs

As a last step, we need to configure our bundle in the ConfigureBundles method in the MyTodoAppModule.cs file:

private void ConfigureBundles()
{
    Configure<AbpBundlingOptions>(options =>
    {
        // ...

        options.ScriptBundles.Configure(
            // Or BasicThemeBundles.Scripts.Global
            // Or LeptonXLiteThemeBundles.Scripts.Global
            // 👇 Depends on the theme you are using
            LeptonXThemeBundles.Scripts.Global,
            bundle =>
            {
                bundle.AddFiles("/global-scripts.js");
                // 👇 Make sure to add this line
                bundle.AddContributors(typeof(VueScriptContributor));
            }
        );
    });
}

If your IDE doesn't recognize the namespace of the VueScriptContributor, you can add it manually:

using Volo.Abp.AspNetCore.Mvc.UI.Packages.Vue;

Now we're ready to use Vue components in our Razor Pages.

Creating a Vue Component

Let's create a simple Vue component to display the TODO list.

Passing a simple message to the component

• Remove existing HTML codes in Index.cshtml and replace with the following code:

<div id="vue-app">
    <message-component :message="'Welcome, @CurrentUser.UserName !'"></message-component>
</div>

• Navigate to the Index.cshtml.js file and add the following code:

Vue.component('message-component', {
    template: '<div>Hello, {{ message }}</div>',
    props: ['message']
});

new Vue({
    el: '#vue-app'
});

Run the application and you should see the following output:

Hard refresh might be required to see the component since we added a new vue js file to the bundle.

If still you can't see the component, please check the browser console for any errors.

Interacting with the component

Let's add a button to the component to interact with the component.

• Add another component in the Index.cshtml file:

<div id="vue-app">
    <message-component :message="'Welcome, @CurrentUser.UserName !'"></message-component>
    <counter-component></counter-component>
</div>

Vue.component('counter-component', {
    template:`
    <div class="card">
        <div class="card-body">
            <p>Count: {{ count }}</p>
            <button class="btn btn-primary" @click="increment">Increment</button>
        </div>
    </div>
    `,
    data: function () {
        return {
            count: 0
        };
    },
    methods: {
        increment: function () {
            this.count++;
        }
    }
});

Do not replicate new Vue({}) code block in the file. It's already in the Index.cshtml.js file. Keep it at the bottom of the file as it is.

Run the application and you should see the following output:

Using ABP Client Proxy, Authorization and Localization

Building the backend

Before we go, let's build our backend to use in the component.

• Creating a simple Application Service:

public class TodoAppService : MyTodoAppAppService, ITodoAppService
{
    public static List<TodoItem> Items { get; } = new List<TodoItem>();

    [Authorize("Todo.Create")]
    public async Task<TodoItem> AddTodoItemAsync(TodoItem input)
    {
        Items.Add(input);
        return input;
    }

    [Authorize("Todo")]
    public async Task<List<TodoItem>> GetAllAsync()
    {
        await Task.Delay(1500);
        return Items;
    }
}

• TodoItem.cs

public class TodoItem
{
    public string Description { get; set; }
    public bool IsDone { get; set; }
}

• ITodoAppService.cs

public interface ITodoAppService
{
    Task<List<TodoItem>> GetAllAsync();
    Task<TodoItem> AddTodoItemAsync(TodoItem input);
}

• Run the application and if you can see the following client proxy in the browser console, you're ready to go:

  

[!NOTE] If you can't see the client proxy in the browser console, please check the Dynamic JavaScript Proxies to learn how to enable it.

• Add a new permission in the MyTodoAppPermissionDefinitionProvider.cs file:

public override void Define(IPermissionDefinitionContext context)
{
    var myGroup = context.AddGroup(MyTodoAppPermissions.GroupName);

    var todo = myGroup.AddPermission("Todo");
    todo.AddChild("Todo.Create");
}

I go without localization or constants for simplicity.

• Add a localization key in the en.json file:

{
    "TodoItems": "Todo Items Localized"
}

Building the Vue Component: Using ABP Localization, Authorization and Client Proxy

Since the component it directly loaded into the page, we can access the abp object on the page.

So we can use:

• abp.localization.localize() to localize a string.
• abp.auth.isGranted() to check the authorization.
• myTodoApp.todo.getAll() and myTodoApp.todo.addTodoItem to call the Application Service.

inside Vue Component code.

• Let's add another component named todo-component and usee all the ABP Features in it.

<div id="vue-app">
    <!-- ... -->
    <todo-component></todo-component>
</div>

• Implement the todo-component in Index.cshtml.js file:

Vue.component('todo-component', {
    template: `
    <div class="card" v-if="abp.auth.isGranted('Todo')">
        <div class="card-header border-bottom">
            <h3>{{ abp.localization.localize('TodoItems') }}</h3>
        </div>
        <div class="card-body">
            <div v-if="isBusy" class="w-100 text-center"> 
                <div class="spinner-border" role="status">
                    <span class="visually-hidden">Loading...</span>
                </div>
            </div>
            <ul v-else-if="todos.length > 0" class="list-group">
                <li class="list-group-item" v-for="item in todos" :key="item.description">
                    <input class="form-check-input" type="checkbox" v-model="item.isDone">
                    <label class="form-check-label">{{ item.description }}</label>
                </li>
            </ul>
            <p v-else>No todos yet</p>
        </div>
        <div v-if="abp.auth.isGranted('Todo.Create')" class="card-footer d-flex flex-column gap-2 border-top pt-2">
            <input class="form-control" type="text" v-model="newTodo.description" placeholder="Add a new todo">
            <div class="form-check">
                <input class="form-check-input" type="checkbox" v-model="newTodo.isDone" id="isDone">
                <label class="form-check-label" for="isDone">Is Done</label>
            </div>

            <button class="btn btn-primary" @click="addTodo">Add</button>
        </div>
    </div>
    `,
    data: function () {
        return {
            newTodo: {
                description: '',
                isDone: false
            },
            isBusy: false,
            todos: []
        };
    },
    methods: {
        addTodo() {
            myTodoApp.todo.addTodoItem(this.newTodo);
            this.newTodo = { description: '', isDone: false };
            this.todos.push(this.newTodo);

            // Preferrable, you can load entire list of todos again.
            // this.loadTodos();
        },
        async loadTodos() {
             if (!abp.auth.isGranted('Todo')) {
                return;
            }
            this.isBusy = true;
            this.todos = await myTodoApp.todo.getAll();
            this.isBusy = false;
        }
    },
    mounted() {
        this.loadTodos();
    }
});

And see the result:

Since we use abp.auth.isGranted() to check the authorization, we can see the component only if we have the permission.

Whenever you remove Todo.Create permission, you can see the component is not rendered.

You won't see the card footer:

C# 13 is the latest version of C# and it comes with a lot of new features. In this article, we will discuss some of the new features of C# 13.

params collections

With the C# 13, method parameter with params keyword isn't limited to be an array. You can now use any collection type that implements IEnumerable<T> interface.

Let's see how it can help us in our code.

public IEnumerable<int> GetOdds(params IEnumerable<int> numbers)
{
    foreach (var number in numbers)
    {
        if (number % 2 != 0)
        {
            Console.WriteLine(number);
        }
    }
}

New lock object

I'm sure you have used lock statement in your code to synchronize access to a shared resource. With C# 13, you can now use a new lock object that is more efficient than the traditional lock object. The new Lock type provides better thread synchronization through its API. When Lock.EnterScope() method is called, it returns a struct named Scope that contains a Dispose method. The Dispose method is called when the Scope object goes out of scope, which releases the lock. C# using statement recognizes the Dispose method and calls it automatically like it does with other IDisposable objects.

It was something similar before:

private object _lock = new();

public void DoSomething()
{
    lock (_lock)
    {
        // Do something
    }
}

Now, you can use the new lock object like this:

System.Threading.Lock x = new System.Threading.Lock();
public void DoSomething()
{
    using (x.EnterScope())
    {
        // Do something
    }
}

New escape sequence

In C# 13, a new escape sequence \e has been introduced to represent the ESCAPE character, Unicode U+001B. Previously, you had to use \u001b or \x1b to represent this character. The new \e escape sequence simplifies this process and avoids potential issues with hexadecimal digits following \x1b.

You can check here for ANSI escape codes.

Implicit index access

The implicit "from the end" index operator, ^, is now allowed in an object initializer expression.

It was not possible before, but now you can do this:

var countdown = new TimerRemaining()
{
    buffer =
    {
        [^1] = 0,
        [^2] = 1,
        [^3] = 2,
        [^4] = 3,
        [^5] = 4,
        [^6] = 5,
        [^7] = 6,
        [^8] = 7,
        [^9] = 8,
        [^10] = 9
    }
};

It's a great feature that makes the code more readable and maintainable. Still not a big deal, but it's nice to have it.

ref and unsafe in iterators and async methods

In C# 13, the restrictions on using ref and unsafe constructs in iterators and async methods have been relaxed. Previously, you couldn't declare local ref variables or use unsafe contexts in these methods. Now, you can declare ref local variables and use unsafe contexts in async methods and iterators, provided they are not accessed across await or yield boundaries

This change allows for more expressive and efficient code, especially when working with types like System.Span<T> and System.ReadOnlySpan<T>. The compiler ensures that these constructs are used safely, and it will notify you if any safety rules are violated.

You can read more about this feature on the Microsoft Learn page.

More partial members

In C# 13, the concept of partial members has been expanded to include partial properties and partial indexers. Previously, only methods could be defined as partial members. This means you can now split the definition of properties and indexers across multiple files, just like you could with methods.

For example, you can declare a partial property in one part of your class and implement it in another part. Here's a simple illustration:

public partial class MyClass
{
    // Declaring declaration
    public partial string MyProperty { get; set; }
}

public partial class MyClass
{
    // Implementing declaration
    private string _myProperty;
    public partial string MyProperty
    {
        get => _myProperty;
        set => _myProperty = value;
    }
}

This feature allows for better organization and modularization of your code, especially in large projects where different parts of a class might be implemented by different team members.

Overload resolution priority

What does "Overload resolution priority" section mean in this page? In C# 13, the OverloadResolutionPriority attribute allows library authors to specify which method overload should be preferred by the compiler when multiple overloads are available. This attribute helps avoid ambiguity and ensures that the most appropriate overload is chosen, even if it might not be the most obvious choice based on traditional overload resolution rules.

This may be useful in scenarios where you have multiple overloads that are equally valid, but you want to prioritize one over the others. The attribute can be applied to a method or constructor to indicate its priority in the overload resolution process. It can prevent unexpected behavior and make your code more predictable and maintainable.

Let me show with an example:

public class Example
{
    // Existing method
    public void Display(string message = "Hello!")
    {
        Console.WriteLine("Message: " + message);
    }

    // New, more efficient method with higher priority
    [OverloadResolutionPriority(1)]
    public void Display(string message = "Hello!", int repeatCount = 3)
    {
        for (int i = 0; i < repeatCount; i++)
        {
            Console.WriteLine("Message: " + message);
        }
    }
}

class Program
{
    static void Main()
    {
        Example example = new Example();

        // Normally, you can't compile this code because of ambiguity:
        example.Display();
    }
}

Output:

Message: Hello!
Message: Hello!
Message: Hello!

The field keyword

n C# 13, the field keyword is introduced as a preview feature to simplify property accessors. This keyword allows you to reference the compiler-generated backing field directly within a property accessor, eliminating the need to declare an explicit backing field in your type declaration.

For example, instead of writing:

private int _value;
public int Value
{
    get => _value;
    set => _value = value;
}

You can now write:

public int Value
{
    get => field;
    set => field = value;
}

This makes your code cleaner and more concise. However, be cautious if you have a field named field in your class, as it could cause confusion. You can disambiguate by using @field or this.field.

Make sure you're using the latest LangVersion in your .csproj project file to enable this feature.

<LangVersion>preview</LangVersion>

Native AOT (Ahead-of-Time) compilation is a feature that allows developers to create a self-contained app compiled to native code that can run on machines without the .NET runtime installed. It results in benefits such as minimized disk footprint, reduced executable size, reduced startup time, and reduced memory demand.

Native AOT compilation isn't a new feature in .NET 8. It's first introduced in .NET 7.

Differences between the AOT Compilation of .NET 7 and .NET 8 are:

• System.Text.Json improvements: .NET 8 adds support for more types, source generation, interface hierarchies, naming policies, read-only properties, and more.
• New types for performance: .NET 8 introduces new types such as FrozenDictionary, FrozenSet, SearchValues, CompositeFormat, TimeProvider, and ITimer to improve the app performance.
• System.Numerics and System.Runtime.Intrinsics enhancements: .NET 8 adds support for Vector512, AVX-512, IUtf8SpanFormattable, Lerp, and more.
• System.ComponentModel.DataAnnotations additions: .NET 8 adds new data validation attributes for cloud-native services and a new ValidateOptionsResultBuilder type.
• Hosted services lifecycle methods: .NET 8 adds new methods such as StartAsync, StopAsync, StartBackgroundAsync, and StopBackgroundAsync for hosted services.

It's important to note that not all features in ASP.NET Core are currently compatible with native AOT. For more information, see Native AOT deployment overview.

How to use Native AOT Compilation in .NET 8

You can add <PublishAot>true</PublishAot> in your project .csproj file to enable Native AOT Compilation.

• For the new projects, you can create them with the --aot parameter. Example: dotnet new console --aot.

By default, the compiler chooses a blended approach code optimization but you can specify an optimization preference inside your .csproj file. You can choose size or speed according your requirements.

<OptimizationPreference>Size</OptimizationPreference>

or

<OptimizationPreference>Speed</OptimizationPreference>

Results

I have created a simple console application to test the Native AOT Compilation. I have used a simple console application that writes "Hello World!" to the console 100 times. I have tested the application with different optimization preferences. I have used the following results:

| | Size | Speed | | --- | --- | --- | | .NET 8
(Self-Contained, Single File) | 65938 kb | 00.0051806 ~5ms | | .NET 7 AOT (default) | 4452 kb | 00.0029823 ~2ms | | .NET 8 AOT (default) | 1242 kb | 00.0028638 ~2ms | | AOT (Speed)| 1280 kb | 00.0023838 ~2ms | | AOT (Size) | 1111 kb | 00.0025145 ~2ms |

Most of existing libraries don't support AOT compilation yet, so I couldn't use BenchmarkDotnet to measure the performance. I have used Stopwatch to measure the performance. So the performance results may not be accurate but gives insight about the performance difference.

AOT Support in MAUI

You can now use Native AOT Compilation on iOS-like target frameworks in .NET MAUI. You can enable AOT compilation with the exact same method by adding <PublishAot>true</PublishAot> to your project .csproj file. According to the dotnet team, apps sizes reduced by 35% and startup times reduced by 28% with AOT compilation. And runtime performance is also improved by 50%.

But there are some limitations in MAUI AOT Compilation. A lot of libraries still don't support AOT compilation and some of platform-specific feaetures may not work at the moment.

When to use Native AOT Compilation?

Native AOT Compilation is beneficial when you need to optimize your .NET application for speed and size. It's particularly useful for applications that require quick startup times and efficient runtime performance, such as mobile apps or high-performance computing applications.

However, due to its current limitations, it might not be suitable for all projects. If your project relies heavily on libraries that do not support AOT compilation, or if it uses platform-specific features that are not yet compatible with AOT, you might want to hold off on using Native AOT Compilation until further improvements are made.

Always consider the specific needs and constraints of your project before deciding to use Native AOT Compilation.

Conclusion

Native AOT Compilation is a great feature that improves the performance of .NET applications. It's still in early-stages and not all libraries support it yet. But it's a great beginning for the future of .NET 🚀

Links

• Native AOT deployment overview - .NET | Microsoft Learn. https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/.
• Optimize AOT deployments https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/optimizing
• What's new in .NET 8 | Microsoft Learn. https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-8.

Basic Theme uses plain bootstrap and does not have any custom colors & styles. This article will show you how to add dark mode support to the Basic Theme.

Bootstrap brings the Color Modes feature with version 5.3. This feature allows you to add dark mode support to your website with a single line of code. Adding the data-bs-theme="dark" attribute changes the color mode of the element to dark mode.

Instructions

1. Create a new project with the following command:

   abp new BasicThemeDarkMode -t app --theme basic
   

2. Create a component that toggles the color mode.

   • Create a new file named Components/ChangeTheme/Default.cshtml:

     <div class="text-light mt-1">    
         <button class="btn text-light" href="#" id="ToolbarChangeTheme">
             <i class="fas fa-sun"></i>
         </button>
     </div>
     

   • Create a new file named Components/ChangeTheme/ChangeThemeViewComponent.cs:

     using Microsoft.AspNetCore.Mvc;
     using Volo.Abp.AspNetCore.Mvc;
     
     namespace BasicThemeDarkMode.Web.Components.ChangeTheme;
     
     [Widget(ScriptFiles = new[]{"/Components/ChangeTheme/ChangeTheme.js"})]
     public class ChangeThemeViewComponent : AbpViewComponent
     {
         public IViewComponentResult Invoke()
         {
             return View("~/Components/ChangeTheme/Default.cshtml");
         }
     }
     

   • Create a JavaScript that manages the last selected theme and toggles the color mode. It stores the last selected theme in the local storage. So, you don't need to store it in the database.

     • Create a new file named Components/ChangeTheme/ChangeTheme.js:

       $(function () {
            function changeTheme(theme) {
                window.localStorage.setItem('theme', theme);
                document.getElementsByTagName('body')[0].setAttribute('data-bs-theme', theme);
            }
       
            function toggleTheme(){
                getTheme() == 'light' ? changeTheme('dark') : changeTheme('light');
            }
       
            function getTheme(){
                return window.localStorage.getItem('theme') ?? 'dark';
            }
       
            function init(){
                let theme = getTheme();
                if(theme){
                    changeTheme(theme);
                }
            }
       
            document.getElementById('ToolbarChangeTheme').addEventListener('click', () => {
                toggleTheme();
            });
       
            init();
       });
       

3. Create a new Toolbar Contributor and add a newly created view component to the application toolbar.

   • Create a new class named BasicThemeDarkModeToolbarContributor.cs:

     using BasicThemeDarkMode.Web.Components.ChangeTheme;
     using System.Threading.Tasks;
     using Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared.Toolbars;
     
     namespace BasicThemeDarkMode.Web;
     
     public class BasicThemeDarkModeToolbarContributor : IToolbarContributor
     {
         public Task ConfigureToolbarAsync(IToolbarConfigurationContext context)
         {
             if (context.Toolbar.Name == StandardToolbars.Main)
             {
                 context.Toolbar.Items
                     .Add(new ToolbarItem(typeof(ChangeThemeViewComponent)));
             }
     
             return Task.CompletedTask;
         }
     }
     

   • Configure Toolbar Options and add a newly created contributor:

     Configure<AbpToolbarOptions>(options =>
     {
         options.Contributors.Add(new BasicThemeDarkModeToolbarContributor());
     });
     

That's it! Now, you can toggle the color mode by clicking the sun icon in the toolbar:

• Users Page in Dark Mode:

  

• Settings Page in Dark Mode:

  

• Login Page in Dark Mode:

  

Conclusion

The theme is stored in local storage and it's initialized on the client-side. You can use Cookies to render the page in the last selected theme on server-side to prevent the flash effect while navigating pages. This document shows the concept of adding dark mode support of bootstrap to the Basic Theme.

In this document we will explain how to convert BookStore's Books create & edit modals to regular blazor pages.

Before

After

Books.razor Page

Books.razor page is the main page of the books management. Create & Update operations are done in this page. So we'll remove create & update operations from this page and move a separate blazor component for each operation. Each component will be a page.

• Remove both Create & Update modals.

  

• Replace NewBook button with a link to CreateBook page.

  <Button Color="Color.Primary" Type="ButtonType.Link" To="books/new">
      @L["NewBook"]
  </Button>
  

• Inject NavigationManager to Books.razor page.

  @inject NavigationManager NavigationManager
  

• Replace Edit button with a link to UpdateBook page.

  <Button Color="Color.Primary" Type="ButtonType.Link" OnClick="() => NavigateToEdit(book.Id)">
      @L["Edit"]
  </Button>
  

  private void NavigateToEdit(Guid id)
  {
      NavigationManager.NavigateTo($"books/{id}/edit");
  }
  

• Remove all methods in the Books.razor page except constructor. And add GoToEditPage as below:

  protected void GoToEditPage(BookDto book)
  {
      NavigationManager.NavigateTo($"books/{book.Id}");
  }
  

  

• Change Edit button to a link in the table.

  <EntityAction TItem="BookDto"
              Text="@L["Edit"]"
              Visible=HasUpdatePermission
              Clicked="() => GoToEditPage(context)" />
  

CreateBooks Page

Create new CreateBook.razor and CreateBook.razor.cs files in your project.

• CreateBook.razor

@page "/books/new"
@attribute [Authorize(BookStorePermissions.Books.Create)]
@inherits BookStoreComponentBase

@using Acme.BookStore.Books;
@using Acme.BookStore.Localization;
@using Acme.BookStore.Permissions;
@using Microsoft.Extensions.Localization;
@using Volo.Abp.AspNetCore.Components.Web;

@inject IStringLocalizer<BookStoreResource> L
@inject AbpBlazorMessageLocalizerHelper<BookStoreResource> LH
@inject IBookAppService AppService
@inject NavigationManager NavigationManager

<Card>
    <CardHeader>
        <HeadContent>
            <ModalTitle>@L["NewBook"]</ModalTitle>
        </HeadContent>
    </CardHeader>
    <CardBody>
        <Validations @ref="@CreateValidationsRef" Model="@NewEntity" ValidateOnLoad="false">
            <Validation MessageLocalizer="@LH.Localize">
                <Field>
                    <FieldLabel>@L["Author"]</FieldLabel>
                    <Select TValue="Guid" @bind-SelectedValue="@NewEntity.AuthorId">
                        @foreach (var author in authorList)
                        {
                            <SelectItem TValue="Guid" Value="@author.Id">
                                @author.Name
                            </SelectItem>
                        }
                    </Select>
                </Field>
                <Field>
                    <FieldLabel>@L["Name"]</FieldLabel>
                    <TextEdit @bind-Text="@NewEntity.Name">
                        <Feedback>
                            <ValidationError />
                        </Feedback>
                    </TextEdit>
                </Field>
            </Validation>
            <Field>
                <FieldLabel>@L["Type"]</FieldLabel>
                <Select TValue="BookType" @bind-SelectedValue="@NewEntity.Type">
                    @foreach (int bookTypeValue in Enum.GetValues(typeof(BookType)))
                    {
                        <SelectItem TValue="BookType" Value="@((BookType) bookTypeValue)">
                            @L[$"Enum:BookType.{bookTypeValue}"]
                        </SelectItem>
                    }
                </Select>
            </Field>
            <Field>
                <FieldLabel>@L["PublishDate"]</FieldLabel>
                <DateEdit TValue="DateTime" @bind-Date="NewEntity.PublishDate" />
            </Field>
            <Field>
                <FieldLabel>@L["Price"]</FieldLabel>
                <NumericEdit TValue="float" @bind-Value="NewEntity.Price" />
            </Field>
        </Validations>
    </CardBody>
    <CardFooter>
        <Button Color="Color.Secondary" Type="ButtonType.Link" To="books">
            @L["Cancel"]
        </Button>
        <Button Color="Color.Primary"
                Type="@ButtonType.Submit"
                PreventDefaultOnSubmit="true"
                Clicked="CreateEntityAsync">
            @L["Save"]
        </Button>
    </CardFooter>
</Card>

• CreateBook.razor.cs

using Acme.BookStore.Books;
using Blazorise;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Volo.Abp;

namespace Acme.BookStore.Blazor.Pages;

public partial class CreateBook
{
    protected Validations CreateValidationsRef;
    protected CreateUpdateBookDto NewEntity = new();
    IReadOnlyList<AuthorLookupDto> authorList = Array.Empty<AuthorLookupDto>();

    protected override async Task OnInitializedAsync()
    {
        await base.OnInitializedAsync();
        authorList = (await AppService.GetAuthorLookupAsync()).Items;

        if (!authorList.Any())
        {
            throw new UserFriendlyException(message: L["AnAuthorIsRequiredForCreatingBook"]);
        }

        NewEntity.AuthorId = authorList.First().Id;

        if (CreateValidationsRef != null)
        {
            await CreateValidationsRef.ClearAll();
        }
    }

    protected virtual async Task CreateEntityAsync()
    {
        try
        {
            var validate = true;
            if (CreateValidationsRef != null)
            {
                validate = await CreateValidationsRef.ValidateAll();
            }
            if (validate)
            {
                await AppService.CreateAsync(NewEntity);
                NavigationManager.NavigateTo("books");
            }
        }
        catch (Exception ex)
        {
            await HandleErrorAsync(ex);
        }
    }
}

EditBooks Page

Create new EditBook.razor and EditBook.razor.cs files in your project.

• EditBook.razor

@page "/books/{Id}"
@attribute [Authorize(BookStorePermissions.Books.Edit)]
@inherits BookStoreComponentBase
@using Acme.BookStore.Books;
@using Acme.BookStore.Localization;
@using Acme.BookStore.Permissions;
@using Microsoft.Extensions.Localization;
@using Volo.Abp.AspNetCore.Components.Web;

@inject IStringLocalizer<BookStoreResource> L
@inject AbpBlazorMessageLocalizerHelper<BookStoreResource> LH
@inject IBookAppService AppService
@inject NavigationManager NavigationManager

<Card>
    <CardHeader>
        <HeadContent>
            <ModalTitle>@EditingEntity.Name</ModalTitle>
        </HeadContent>
    </CardHeader>
    <CardBody>
        <Validations @ref="@EditValidationsRef" Model="@EditingEntity" ValidateOnLoad="false">
            <Validation MessageLocalizer="@LH.Localize">
                <Field>
                    <FieldLabel>@L["Author"]</FieldLabel>
                    <Select TValue="Guid" @bind-SelectedValue="@EditingEntity.AuthorId">
                        @foreach (var author in authorList)
                        {
                            <SelectItem TValue="Guid" Value="@author.Id">
                                @author.Name
                            </SelectItem>
                        }
                    </Select>
                </Field>
                <Field>
                    <FieldLabel>@L["Name"]</FieldLabel>
                    <TextEdit @bind-Text="@EditingEntity.Name">
                        <Feedback>
                            <ValidationError />
                        </Feedback>
                    </TextEdit>
                </Field>
            </Validation>
            <Field>
                <FieldLabel>@L["Type"]</FieldLabel>
                <Select TValue="BookType" @bind-SelectedValue="@EditingEntity.Type">
                    @foreach (int bookTypeValue in Enum.GetValues(typeof(BookType)))
                    {
                        <SelectItem TValue="BookType" Value="@((BookType) bookTypeValue)">
                            @L[$"Enum:BookType.{bookTypeValue}"]
                        </SelectItem>
                    }
                </Select>
            </Field>
            <Field>
                <FieldLabel>@L["PublishDate"]</FieldLabel>
                <DateEdit TValue="DateTime" @bind-Date="EditingEntity.PublishDate" />
            </Field>
            <Field>
                <FieldLabel>@L["Price"]</FieldLabel>
                <NumericEdit TValue="float" @bind-Value="EditingEntity.Price" />
            </Field>
        </Validations>
    </CardBody>
    <CardFooter>
        <Button Color="Color.Secondary" Type="ButtonType.Link" To="books">
            @L["Cancel"]
        </Button>
        <Button Color="Color.Primary"
                Type="@ButtonType.Submit"
                PreventDefaultOnSubmit="true"
                Clicked="UpdateEntityAsync">
            @L["Save"]
        </Button>
    </CardFooter>
</Card>

• EditBook.razor.cs

using Acme.BookStore.Books;
using Blazorise;
using Microsoft.AspNetCore.Components;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Volo.Abp;

namespace Acme.BookStore.Blazor.Pages;

public partial class EditBook
{
    protected CreateUpdateBookDto EditingEntity = new();
    protected Validations EditValidationsRef;
    IReadOnlyList<AuthorLookupDto> authorList = Array.Empty<AuthorLookupDto>();

    [Parameter]
    public string Id { get; set; }

    public Guid EditingEntityId { get; set; }

    protected override async Task OnInitializedAsync()
    {
        await base.OnInitializedAsync();

        // Blazor can't parse Guid as route constraint currently.
        // See https://github.com/dotnet/aspnetcore/issues/19008
        EditingEntityId = Guid.Parse(Id);

        authorList = (await AppService.GetAuthorLookupAsync()).Items;

        if (!authorList.Any())
        {
            throw new UserFriendlyException(message: L["AnAuthorIsRequiredForCreatingBook"]);
        }

        var entityDto = await AppService.GetAsync(EditingEntityId);

        EditingEntity = ObjectMapper.Map<BookDto,CreateUpdateBookDto>(entityDto);

        if (EditValidationsRef != null)
        {
            await EditValidationsRef.ClearAll();
        }
    }

    protected virtual async Task UpdateEntityAsync()
    {
        try
        {
            var validate = true;
            if (EditValidationsRef != null)
            {
                validate = await EditValidationsRef.ValidateAll();
            }
            if (validate)
            {
                await AppService.UpdateAsync(EditingEntityId, EditingEntity);

                NavigationManager.NavigateTo("books");
            }
        }
        catch (Exception ex)
        {
            await HandleErrorAsync(ex);
        }
    }
}

You can check the following commit for details: https://github.com/abpframework/abp-samples/commit/aae61ad6d66ebf6191dd4dcfb4e23d30bd680a4e

Entity Framework tracks all the entity changes and applies those changes to the database one by one when the SaveChanges() method is called. There was no way to execute bulk operations in Entity Framework Core without a dependency.

As you know the Entity Framework Extensions library was doing it but it was not free.

There was no other solution until now. Bulk Operations are now available in Entity Framework Core with .NET 7.

With .NET 7, there are two new methods such as ExecuteUpdate and ExecuteDelete available to execute bulk operations. It's a similar usage with the Entity Framework Core Extensions library if you're familiar with it.

You can visit the microsoft example here about how to use it.

It can be easily used with the DbContext.

await context.Tags.Where(t => t.Text.Contains(".NET")).ExecuteDeleteAsync();

Using with ABP Framework

ABP Framework provides an abstraction over database operations and implements generic repository pattern. So, DbContext can't be accessed outside of repositories.

You can use the ExecuteUpdate and ExecuteDelete methods inside a repository.

public class BookEntityFrameworkCoreRepository : EfCoreRepository<BookStoreDbContext, Book, Guid>, IBookRepository
{
    public BookEntityFrameworkCoreRepository(IDbContextProvider<BookStoreDbContext> dbContextProvider) : base(dbContextProvider)
    {
    }

    public async Task UpdateListingAsync()
    {
        var dbSet = await GetDbSetAsync();

        await dbSet
            .Where(x => x.IsListed && x.PublishedOn.Year <= 2022)
            .ExecuteUpdateAsync(s => s.SetProperty(x => x.IsListed, x => false));
    }

    public async Task DeleteOldBooksAsync()
    {
        var dbSet = await GetDbSetAsync();

        await dbSet
            .Where(x => x.PublishedOn.Year <= 2000)
            .ExecuteDeleteAsync();
    }
}

There is no need to take an action for bulk inserting. You can use the InsertManyAsync method of the repository instead of creating a new method for it if you don't have custom logic. It'll use a new bulk inserting feature automatically since it's available in EF Core 7.0.

public class MyDomainService : DomainService
{
    protected IRepository<Book, Guid> BookRepository { get; }

    public MyDomainService(IRepository<Book, Guid> bookRepository)
    {
        BookRepository = bookRepository;
    }

    public async Task CreateBooksAsync(List<Book> books)
    {
        // It'll use bulk inserting automatically.
        await BookRepository.InsertManyAsync(books);
    }
}

If you use ExecuteDeleteAsync or ExecuteUpdateAsync, then ABP's soft delete and auditing features can not work. Because these ABP features work with EF Core's change tracking system and these new methods doesn't work with the change tracking system. So, use them carefully.

Microsoft provides a template named Blazor WebAssembly Asp.NET Core Hosted. This template is an Asp.NET Core Razor Pages application that hosts a Blazor WebAssembly application. Basically, HttpApi.Host and Blazor applications are hosted together. In this case, only one application will be deployed and blazor application will be served by the HttpApi.Host.

Instructions

• Create a new ABP Application with Blazor UI

  abp new BookStore -u blazor -t app -v 6.0.0-rc.2 --no-random-port
  

• Add Blazor project reference and Microsoft.AspNetCore.Components.WebAssembly.Server package reference to the HttpApi.Host project.

  <ItemGroup>
      <ProjectReference Include="..\BookStore.Blazor\BookStore.Blazor.csproj" />
      <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.Server" Version="6.0.8" />
  </ItemGroup>
  

• Add Blazor framework files middleware into OnApplicationInitializaiton method in BookStoreHttpApiHostModule.cs file.

  public override void OnApplicationInitialization(ApplicationInitializationContext context)
  {
      // ...
  
      app.UseBlazorFrameworkFiles(); // 👈 Make sure it's before UseStaticFiles()
  
      app.UseStaticFiles();
  
      // ...
  }
  

• Add a mapping for fallback to index.html file at the end of the OnApplicationInitializaiton method in BookStoreHttpApiHostModule.cs file.

  if (app is WebApplication webApp)
  {
      webApp.MapFallbackToFile("index.html");
  }
  

• Configure your blazor SelfUrl as HttpApi.Host URL in BookStore.Blazor/wwwroot/appsettings.json

  {
      "App": {
          "SelfUrl": "https://localhost:44305"
      },
      "AuthServer": {
          "Authority": "https://localhost:44305",
          "ClientId": "BookStore_Blazor",
          "ResponseType": "code"
      },
      "RemoteServices": {
          "Default": {
          "BaseUrl": "https://localhost:44305"
          }
      },
      "AbpCli": {
          "Bundle": {
          "Mode": "BundleAndMinify", /* Options: None, Bundle, BundleAndMinify */
          "Name": "global",
          "Parameters": {
  
              }
          }
      }
  }
  

• Configure DbMigrator too. Navigate to BookStore.DbMigrator/appsettings.json and change Blazor URL to HttpApi.Host URL.

  {
      "ConnectionStrings": {
          "Default": "XXX"
      },
      "OpenIddict": {
          "Applications": {
          "BookStore_Blazor": {
              "ClientId": "BookStore_Blazor",
              "RootUrl": "https://localhost:44305"
          },
          "BookStore_Swagger": {
              "ClientId": "BookStore_Swagger",
              "RootUrl": "https://localhost:44305"
          }
          }
      }
  }
  

• Run BookStore.DbMigrator once.

• Remove HomeController.cs from HttpApi.Host project to prevent /swagger redirection.

• Run only BookStore.HttpApi.Host project and see the result.

  

  As you can see, URL is localhost:44305 for blazor application and login razor page. MVC application and Blazor WebAssembly works together. As you can see swagger UI is available at localhost:44305/swagger too.

The purpose of this article is to integrate ABP Core into the MAUI project and initialize it as an AbpModule then make able consuming API using ABP IAppServices.

Before we start, I offer my special thanks to @hikalkan because this repository ( hikalkan/maui-abp-playing ) is a fantastic inspiration for the purpose of this article.

Getting Started

In this article, we'll work on an application that was built on the previous article: Integrating MAUI Client via Using OpenID Connect.

Source Code

Source code is available on GitHub: abpframework/abp-samples/MAUI-OpenId

Configuring ABP Core

As a first step, Dependency Injection will be changed with module initialization. We have to initialize our application as an ABP Module first.

• Add the following dependencies to MAUI Client.

  <PackageReference Include="Volo.Abp.Http.Client.IdentityModel" Version="5.1.3" />
  <PackageReference Include="Volo.Abp.Autofac" Version="5.1.3" />
  

• Add HttpApi.Client project reference

  <ProjectReference Include="..\..\aspnet-core\src\Acme.BookStore.HttpApi.Client\Acme.BookStore.HttpApi.Client.csproj" />
  

  And run abp build command under MAUI application folder.

  abp build command is equivalent of dotnet build /graphBuild, it's like a shortcut to graphBuild. The graphBuild finds all dependency tree and build them recursively.

• Create BookStoreMauiClientModule.

  using IdentityModel.OidcClient;
  using Microsoft.Extensions.Configuration;
  using Microsoft.Extensions.Options;
  using Volo.Abp.Autofac;
  using Volo.Abp.Http.Client.IdentityModel;
  using Volo.Abp.Modularity;
  
  namespace Acme.BookStore.MauiClient;
  
  [DependsOn(
      typeof(AbpAutofacModule),
      typeof(AbpHttpClientIdentityModelModule),
      typeof(BookStoreHttpApiClientModule)
      )]
  public class BookStoreMauiClientModule : AbpModule
  {
      public override void ConfigureServices(ServiceConfigurationContext context)
      {
          var configuration = context.Services.GetConfiguration();
  
          Configure<OidcClientOptions>(configuration.GetSection("Oidc:Options"));
  
          context.Services.AddTransient<OidcClient>(sp =>
          {
              var options = sp.GetRequiredService<IOptions<OidcClientOptions>>().Value;
              options.Browser = sp.GetRequiredService<WebAuthenticatorBrowser>();
              return new OidcClient(options);
          });
  
          context.Services.AddTransient<HttpClient>(sp =>
              new HttpClient(sp.GetRequiredService<AccessTokenHttpMessageHandler>())
              {
                  // Temporarily. We'll use ABP's Proxy for sendind requests.
                  BaseAddress = new Uri(configuration.GetValue<string>("RemoteServices:Default:BaseUrl"))
              });
      }
  }
  

• Mark all dependencies with interfaces for registering as services.

  internal class WebAuthenticatorBrowser : IBrowser, ITransientDependency
  

  public partial class MainPage : ContentPage, ITransientDependency
  

  public class AccessTokenHttpMessageHandler : DelegatingHandler, ISingletonDependency
  

• Add appsettings.json file to root path of your application and mark it as Embedded resource.

  {
      "Oidc": {
          "Options": {
              "Authority": "https://46fd-45-156-29-175.ngrok.io",
              "ClientId": "BookStore_Maui",
              "RedirectUri": "bookstore://",
              "Scope": "openid email profile role BookStore offline_access",
              "ClientSecret": "1q2w3E*"
          }
      },
      "RemoteServices": {
          "Default": {
              "BaseUrl": "https://46fd-45-156-29-175.ngrok.io"
          }
      }
  }
  

• Finally, Go back MauiApplication.cs and clear old codes and initialize ABP.

  using Microsoft.Extensions.Configuration;
  using Microsoft.Extensions.FileProviders;
  using System.Reflection;
  using Volo.Abp;
  using Volo.Abp.Autofac;
  
  namespace Acme.BookStore.MauiClient;
  
  public static class MauiProgram
  {
      public static MauiApp CreateMauiApp()
      {
          var builder = MauiApp.CreateBuilder();
          builder.ConfigureContainer(new AbpAutofacServiceProviderFactory(new Autofac.ContainerBuilder()), containerBuilder =>
          {
  
          });
          builder
              .UseMauiApp<App>()
              .ConfigureFonts(fonts =>
              {
                  fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
              });
  
          ConfigureConfiguration(builder);
  
          builder.Services.AddApplication<BookStoreMauiClientModule>(options =>
          {
              options.Services.ReplaceConfiguration(builder.Configuration);
          });
  
          var app = builder.Build();
  
          app.Services.GetRequiredService<IAbpApplicationWithExternalServiceProvider>()
              .Initialize(app.Services);
  
          return app;
      }
  
      private static void ConfigureConfiguration(MauiAppBuilder builder)
      {
          var assembly = typeof(App).GetTypeInfo().Assembly;
          builder.Configuration.AddJsonFile(new EmbeddedFileProvider(assembly), "appsettings.json", optional: false, false);
      }
  }
  

  Now application is runnable and all behaviors are the same with previos state. But it uses power of ABP right now.

  Switching to SecureStorage

  .Net MAUI supports a secure storage by default. Before we go further, we need to switch to secure storage instead of using app properties. Just update login method as below at MainPage.xaml.cs

  private async void OnLoginClicked(object sender, EventArgs e)
  {
      var loginResult = await OidcClient.LoginAsync(new LoginRequest());
      if (loginResult.IsError)
      {
          await DisplayAlert("Error", loginResult.Error, "Close");
          return;
      }
  
      await SecureStorage.SetAsync(OidcConsts.AccessTokenKeyName, loginResult.AccessToken);
      await SecureStorage.SetAsync(OidcConsts.RefreshTokenKeyName, loginResult.RefreshToken);
  }
  

  Additionally, please configure each platform according to Secure Storage documentation

Configuring Client Proxies

ABP Client-Proxies don't use HttpClient directly. They use IHttpClientFactory to activate a new HttpClient instead of injecting it directly. So, we won't need AccessTokenHttpMessageHandler anymore. But still there is a way needed to set access token in requests. No worries, ABP has IRemoteServiceHttpClientAuthenticator to do that operation. Implementing it and registering to container will solve that issue and the client will be able to make authorized request to server.

• Remove AccessTokenHttpMessageHandler.cs from the project.

• Add AccessTokenRemoteServiceHttpClientAuthenticator.cs instead.

  using IdentityModel.Client;
  using IdentityModel.OidcClient;
  using System.IdentityModel.Tokens.Jwt;
  using Volo.Abp.DependencyInjection;
  using Volo.Abp.Http.Client.Authentication;
  using DependencyAttribute = Volo.Abp.DependencyInjection.DependencyAttribute;
  
  namespace Acme.BookStore.MauiClient;
  
  [Dependency(ReplaceServices = true)]
  [ExposeServices(typeof(IRemoteServiceHttpClientAuthenticator))]
  public class AccessTokenRemoteServiceHttpClientAuthenticator : IRemoteServiceHttpClientAuthenticator, ITransientDependency
  {
      protected OidcClient OidcClient { get; }
  
      public AccessTokenRemoteServiceHttpClientAuthenticator(OidcClient oidcClient)
      {
          OidcClient = oidcClient;
      }
  
      public async Task Authenticate(RemoteServiceHttpClientAuthenticateContext context)
      {
          var currentAccessToken = await SecureStorage.GetAsync(OidcConsts.AccessTokenKeyName);
  
          if (!currentAccessToken.IsNullOrEmpty())
          {
              // TODO: Find better way to find if token is expired instead of parsing it.
              var jwtToken = new JwtSecurityTokenHandler().ReadJwtToken(currentAccessToken) as JwtSecurityToken;
              if (jwtToken.ValidTo <= DateTime.UtcNow)
              {
                  var refreshToken = await SecureStorage.GetAsync(OidcConsts.RefreshTokenKeyName);
                  if (!refreshToken.IsNullOrEmpty())
                  {
                      var refreshResult = await OidcClient.RefreshTokenAsync(refreshToken);
  
                      await SecureStorage.SetAsync(OidcConsts.AccessTokenKeyName, refreshResult.AccessToken);
                      await SecureStorage.SetAsync(OidcConsts.RefreshTokenKeyName, refreshResult.RefreshToken);
  
                      context.Request.SetBearerToken(refreshResult.AccessToken);
                  }
                  else
                  {
                      var loginResult = await OidcClient.LoginAsync(new LoginRequest());
  
                      await SecureStorage.SetAsync(OidcConsts.AccessTokenKeyName, loginResult.AccessToken);
                      await SecureStorage.SetAsync(OidcConsts.RefreshTokenKeyName, loginResult.RefreshToken);
  
                      context.Request.SetBearerToken(loginResult.AccessToken);
                  }
              }
  
              context.Request.SetBearerToken(currentAccessToken);
          }
      }
  }
  

• Now we are ready to inject IAppServices to communicate with backend.

Displaying Data in UI

• Go back to Acme.BookStore.Domain project and add a simple data seed contributor to generate some example data for users.

  public class UsersDataSeederContributor : IDataSeedContributor, ITransientDependency
  {
      protected IIdentityUserRepository repository;
  
      protected IGuidGenerator guidGenerator;
      public UsersDataSeederContributor(IIdentityUserRepository repository, IGuidGenerator guidGenerator)
      {
          this.repository = repository;
          this.guidGenerator = guidGenerator;
      }
  
      public async Task SeedAsync(DataSeedContext context)
      {
          var count = await repository.GetCountAsync();
          if(count <= 1) // Not sure 'admin' user was seeded before or not.
          {
              // All the names below were generated by https://www.name-generator.org.uk/quick/
              // The names does not represent real people.
              await repository.InsertManyAsync(new []{
                  new IdentityUser(guidGenerator.Create(), "john.doe", "john.doe@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Zane.Frost", "Zane.Frost@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Oscar.Landry", "Oscar.Landry@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Yasemin.Roberts", "Yasemin.Roberts@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Yasmine.Perez", "Yasmine.Perez@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Tobi.Becker", "Tobi.Becker@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Fox.Gilmore", "Fox.Gilmore@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Benny.Burris", "Benny.Burris@abp.io"),
                  new IdentityUser(guidGenerator.Create(), "Chad.Camacho", "Chad.Camacho@abp.io"),
              });
          }
      }
  }
  

• Run the Acme.BookStore.DbMigrator project.

• Turn back to MAUI app, and create a folder named ViewModels and add a simple UsersViewModel.cs under it.

  public class UsersViewModel : BindableObject, ITransientDependency
  {
      protected IIdentityUserAppService IdentityUserAppService { get; }
  
      public GetIdentityUsersInput Input { get; } = new();
  
      public ObservableCollection<IdentityUserDto> Items { get; } = new();
  
      public Command RefreshCommand { get; }
  
      private bool isBusy;
      public bool IsBusy { get => isBusy; set => SetProperty(ref isBusy, value); }
  
      public UsersViewModel(IIdentityUserAppService identityUserAppService)
      {
          IdentityUserAppService = identityUserAppService;
          GetUsersAsync();
          RefreshCommand = new Command(GetUsersAsync);
      }
  
      protected async void GetUsersAsync()
      {
          if (IsBusy)
          {
              return; // For preventing parallel request while searching.
          }
  
          IsBusy = true;
  
          Items.Clear();
  
          var result = await IdentityUserAppService.GetListAsync(Input);
          foreach (var user in result.Items)
          {
              Items.Add(user);
          }
  
          IsBusy = false;
      }
  
      protected void SetProperty<T>(ref T backField, T value, [CallerMemberName] string propertyName = null)
      {
          backField = value;
          OnPropertyChanged(propertyName);
      }
  }
  

• Create a folder named Pages and add a content page named UsersPage.

  (Make sure you're adding MAUI Content Page)

  

• And inject UsersViewModel into it.

  public partial class UsersPage : ContentPage, ITransientDependency
  {
      public UsersViewModel ViewModel { get; }
  
      public UsersPage(UsersViewModel viewModel)
      {
          ViewModel = viewModel;
          InitializeComponent();
      }
  }
  

• And use that ViewModel in XAML design page.

  <?xml version="1.0" encoding="utf-8" ?>
  <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              x:Class="Acme.BookStore.MauiClient.UsersPage"
              Title="UsersPage"
              x:Name="page"
              BindingContext="{Binding ViewModel, Source={x:Reference page}}">
      <StackLayout>
          <ListView 
              IsPullToRefreshEnabled="True"
              ItemsSource="{Binding Items}"
              IsRefreshing="{Binding IsBusy}"
              RefreshCommand="{Binding RefreshCommand}">
              <ListView.Header>
                  <SearchBar Text="{Binding Input.Filter}" SearchCommand="{Binding RefreshCommand}" />
              </ListView.Header>
              <ListView.ItemTemplate>
                  <DataTemplate>
                      <TextCell 
                          Text="{Binding UserName, StringFormat='@{0}'}"
                          Detail="{Binding Email}"/>
                  </DataTemplate>
              </ListView.ItemTemplate>
          </ListView>
      </StackLayout>
  </ContentPage>
  

  I've used binding while setting BindingContext as ViewModel because of IntelliSense support. With this method, you'll see intellisense will suggest properties from your ViewModel.

  

After a couple of try, I realized, only AppShell supports dependency injection while navigating between pages. So, adding a new AppShell will help to build app menus and navigating with route. We can pass parameters with querystring with this way.

• Add Shell Pagae (MAUI) to root of your application with name AppShell.xaml.

  I've got some help for design of shell page from microsoft's articles.

  Additionally, you might want to put abp_icon.svg file under your Resources/Images folder.

  <?xml version="1.0" encoding="utf-8" ?>
  <Shell x:Class="Acme.BookStore.MauiClient.AppShell"
      xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
      xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
      xmlns:local="clr-namespace:Acme.BookStore.MauiClient">
      <Shell.Resources>
          <ResourceDictionary>
              <Color x:Key="Primary">#512BD4</Color>
              <Style x:Key="BaseStyle" TargetType="Element">
                  <Setter Property="Shell.BackgroundColor" Value="{StaticResource Primary}" />
                  <Setter Property="Shell.ForegroundColor" Value="White" />
                  <Setter Property="Shell.TitleColor" Value="White" />
                  <Setter Property="Shell.DisabledColor" Value="#B4FFFFFF" />
                  <Setter Property="Shell.UnselectedColor" Value="#95FFFFFF" />
                  <Setter Property="Shell.TabBarBackgroundColor" Value="{StaticResource Primary}" />
                  <Setter Property="Shell.TabBarForegroundColor" Value="White"/>
                  <Setter Property="Shell.TabBarUnselectedColor" Value="#95FFFFFF"/>
                  <Setter Property="Shell.TabBarTitleColor" Value="White"/>
              </Style>
              <Style TargetType="TabBar" BasedOn="{StaticResource BaseStyle}" />
              <Style TargetType="FlyoutItem" BasedOn="{StaticResource BaseStyle}" />
              <Style Class="FlyoutItemLabelStyle" TargetType="Label">
                  <Setter Property="TextColor" Value="White"></Setter>
                  <Setter Property="Margin" Value="16"></Setter>
              </Style>
              <Style Class="FlyoutItemLayoutStyle" TargetType="Layout" ApplyToDerivedTypes="True">
                  <Setter Property="VisualStateManager.VisualStateGroups">
                      <VisualStateGroupList>
                          <VisualStateGroup x:Name="CommonStates">
                              <VisualState x:Name="Normal">
                                  <VisualState.Setters>
                                      <Setter Property="BackgroundColor" Value="{x:OnPlatform UWP=Transparent, iOS=White, Android=White}" />
                                      <Setter TargetName="FlyoutItemLabel" Property="Label.TextColor" Value="{StaticResource Primary}" />
                                  </VisualState.Setters>
                              </VisualState>
                              <VisualState x:Name="Selected">
                                  <VisualState.Setters>
                                      <Setter Property="BackgroundColor" Value="{StaticResource Primary}" />
                                  </VisualState.Setters>
                              </VisualState>
                          </VisualStateGroup>
                      </VisualStateGroupList>
                  </Setter>
              </Style>
  
              <Style Class="MenuItemLayoutStyle" TargetType="Layout" ApplyToDerivedTypes="True">
                  <Setter Property="VisualStateManager.VisualStateGroups">
                      <VisualStateGroupList>
                          <VisualStateGroup x:Name="CommonStates">
                              <VisualState x:Name="Normal">
                                  <VisualState.Setters>
                                      <Setter TargetName="FlyoutItemLabel" Property="Label.TextColor" Value="{StaticResource Primary}" />
                                  </VisualState.Setters>
                              </VisualState>
                          </VisualStateGroup>
                      </VisualStateGroupList>
                  </Setter>
              </Style>
          </ResourceDictionary>
      </Shell.Resources>
  
      <FlyoutItem Title="Home">
          <ShellContent ContentTemplate="{DataTemplate local:MainPage}" Route="main" />
      </FlyoutItem>
  
      <FlyoutItem Title="Users">
          <ShellContent ContentTemplate="{DataTemplate local:UsersPage}" Route="UsersPage" />
      </FlyoutItem>
  
      <Shell.FlyoutHeader>
          <StackLayout>
              <Image 
                  Source="abp_logo.svg"
                  HorizontalOptions="Center"
                  Margin="25"/>
          </StackLayout>
      </Shell.FlyoutHeader>
  
  </Shell>
  

• One more step is required. Go to App.xaml.cs and replace MainPage with AppShell.

  public partial class App : Application
  {
      public App()
      {
          InitializeComponent();
  
          MainPage = new AppShell();
      }
  }
  

• Run the application.

• Login once if you haven't done before.

• Navigate to Users page with hamburger menu at the right top.

| Android| iOS| | --- | --- | | | |

| UWP | | --- | | |

| MacCatalyst | | --- | | |

Conclusion

ABP Framework can be implemented any platform that runs on dotnet without suffer. ABP provides reusable abstractions layers and HttpApi Clients. In this article we've used powerful ABP core features such as Dependency Injection, Client Proxies, Validation and more.

This is a demonstration for connecting ABP backend from MAUI app via using openid connect.

In this flow, a web browser will be opened when user tries to log in and user will perform login operation in the browser. Then IdentityServer will redirect user to application with login credentials (state, token etc.) will be handled by application.

This is by intent. The code flow does not allow the user to log in using a native view in the app. The reason being that this flow ensures that the username and password are never seen by the client (except the browser, which is part of the OS system - aka we trust it). You could enable using a native login view with the Resource Owner Password Credentials (ROPC) flow. But this is also an attack vector. Suppose someone makes a fraud duplicate of your application and tricking users into entering their credentials. The fraudulent app could store those credentials in-between. You just got to enjoy those tin-foil-hat moments when doing security. In other words, using the code flow does not give an attacker that opportunity and therefore is the recommended option for mobile clients.

• @Mark Allibone

By the way, my motivation for building this sample is presenting just another way for authentication. Resource Owner Password Credentials authentication is already provided and it's more common way to do. This is yet another way to authenticate users.

Source Code

You can also find source code on GitHub in ABP-Samples.

• abpframework/abp-samples/MAUI-OpenId

Creating projects

• Create an ABP project without UI

abp new Acme.BookStore -t app --no-ui -d mongodb --no-random-ports

• Create a maui application

mkdir maui
cd maui
dotnet new maui -n Acme.BookStore.MauiClient

There is a long way for configuring scopes and callback urls for both server and clients. We'll use WebAuthenticator to perform this operation.

Configuring IdentityServer

• Go to DbMigrator folder and MAUI client in appsettings.json. Add following client code in IdentityServer:Clients path:

    "BookStore_Maui": {
        "ClientId": "BookStore_Maui",
        "ClientSecret": "1q2w3e*",
        "RootUrl": "bookstore://"
    }

• Go to IdentityServerDataSeedContributor in Domain project under IdentityServer folder. Append following code section into CreateClientsAsync() method.

// Maui Client
var mauiClientId = configurationSection["BookStore_Maui:ClientId"];
if (!mauiClientId.IsNullOrWhiteSpace())
{
    var mauiRootUrl = configurationSection["BookStore_Maui:RootUrl"];

    await CreateClientAsync(
        name: mauiClientId,
        scopes: commonScopes,
        grantTypes: new[] { "authorization_code" },
        secret: configurationSection["BookStore_Maui:ClientSecret"]?.Sha256(),
        requireClientSecret: false,
        redirectUri: $"{mauiRootUrl}"
    );
}

• Run DbMigrator

• Then run HttpApi.Host

Configuring NGROK

Client will check configuration from /.well-known/openid-configuration path and it must be a secured connection between client & server. I prefer to use ngrok to open my backend app to entire web.

• Go to getting started page of ngrok (login or register first) and download the ngrok tool.

• Don't forget to login from tool:

  ngrok authtoken XXX
  

  A sample command is being displayed at dashboard where you download ngrok from

• Open your HttpApi.Host with ngrok

  .\ngrok.exe http https://localhost:44350
  

• You'll see a generated xxx.ngrok.io url. Navigate to /.well-known/openid-configuration to check if it's working right.

  You should see something like that: Issuer must be your URL, not localhost! If you see still localhost, try to disable host header rewrite.

• Also, ValidIssuers must be defined to validate tokens.

  • Add ValidIssuers section to your appsettings.json of HttpApi.Host

    "AuthServer": {
        "Authority": "https://localhost:44350",
        "RequireHttpsMetadata": "false",
        "SwaggerClientId": "BookStore_Swagger",
        "SwaggerClientSecret": "1q2w3e*",
        "ValidIssuers": [
            "https://46fd-45-156-29-175.ngrok.io"
        ]
    },
    

  • Then define it in ConfigureAuthentication method in Module class

    private void ConfigureAuthentication(ServiceConfigurationContext context, IConfiguration configuration)
    {
        context.Services.AddAuthentication()
            .AddJwtBearer(options =>
            {
                // ...
                options.TokenValidationParameters.ValidIssuers = configuration.GetSection("AuthServer:ValidIssuers").Get<string[]>();
            });
    }
    

We're done with backend. Let's continue with MAUI app.

Developing MAUI App

Before we go, there is something to do like configuring dependency injection to get rid of unnecessary huge class coupling.

Configuring Dependency Injection

• Go to MauiApplication class and add MainPage in services.

  public static MauiApp CreateMauiApp()
  {
      var builder = MauiApp.CreateBuilder();
      builder
          .UseMauiApp<App>()
          .ConfigureFonts(fonts =>
          {
              fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
          });
  
      builder.Services.AddTransient<MainPage>();
  
      return builder.Build();
  }
  

• And inject MainPage from constructor in App.xaml.cs

  public App(MainPage mainPage)
  {
      InitializeComponent();
  
      MainPage = mainPage;
  }
  

Now MainPage is ready for injecting dependencies to it.

Configuring OIDC

• Add IdentityModel.OidcClient package to project

  <ItemGroup>
      <PackageReference Include="IdentityModel.OidcClient" Version="5.0.0" />
  </ItemGroup>
  

• Create WebAuthenticatorBrowser

  internal class WebAuthenticatorBrowser : IBrowser
  {
      public async Task<BrowserResult> InvokeAsync(BrowserOptions options, CancellationToken cancellationToken = default)
      {
          try
          {
              WebAuthenticatorResult authResult =
                  await WebAuthenticator.AuthenticateAsync(new Uri(options.StartUrl), new Uri(options.EndUrl));
              var authorizeResponse = ToRawIdentityUrl(options.EndUrl, authResult);
  
              return new BrowserResult
              {
                  Response = authorizeResponse
              };
          }
          catch (Exception ex)
          {
              Debug.WriteLine(ex);
              return new BrowserResult()
              {
                  ResultType = BrowserResultType.UnknownError,
                  Error = ex.ToString()
              };
          }
      }
  
      public string ToRawIdentityUrl(string redirectUrl, WebAuthenticatorResult result)
      {
          IEnumerable<string> parameters = result.Properties.Select(pair => $"{pair.Key}={pair.Value}");
          var values = string.Join("&", parameters);
  
          return $"{redirectUrl}#{values}";
      }
  }
  

• Configure OidcClient in MauiProgram

  builder.Services.AddTransient<WebAuthenticatorBrowser>();
  
  builder.Services.AddTransient<OidcClient>(sp =>
      new OidcClient(new OidcClientOptions
      {
          // Use your own ngrok url:
          Authority = "https://46fd-45-156-29-175.ngrok.io",
          ClientId = "BookStore_Maui",
          RedirectUri = "bookstore://",
          Scope = "openid email profile role BookStore",
          ClientSecret = "1q2w3E*",
          Browser = sp.GetRequiredService<WebAuthenticatorBrowser>(),
      })
  );
  

• Go to MainPage.xaml, remove everyting and add a button for login

  <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
              x:Class="MauiApp1.MainPage">
  
      <ScrollView>
          <Grid RowSpacing="25" RowDefinitions="Auto,Auto,Auto,Auto,*"
              Padding="{OnPlatform iOS='30,60,30,30', Default='30'}">
  
              <Button Text="Click to Log In" Clicked="OnLoginClicked" VerticalOptions="CenterAndExpand" HorizontalOptions="Center"/>
  
          </Grid>
      </ScrollView>
  </ContentPage>
  

• Inject OidcClient in MainPage.xaml.cs and make login operation.

  using IdentityModel.OidcClient;
  
  namespace Acme.BookStore.MauiClient;
  
  public partial class MainPage : ContentPage
  {
      protected OidcClient OidcClient { get; }
  
      public MainPage(OidcClient oidcClient)
      {
          InitializeComponent();
          OidcClient = oidcClient;
      }
  
      private async void OnLoginClicked(object sender, EventArgs e)
      {
          try
          {
              var loginResult = await OidcClient.LoginAsync(new LoginRequest());
              await DisplayAlert("Login Result", "Access Token is:\n\n" + loginResult.AccessToken, "Close");
  
          }
          catch (Exception ex)
          {
              await DisplayAlert("Error", ex.ToString(), "ok");
          }
      }
  }
  

It still won't work because there is something more to do for each platform. Check out the next step and configure the platforms that you're using.

Platform Specific Configurations

Each platform (UWP, OSX, iOS and Android) requires some configuration to use authentication from browser. In that step, we'll open a browser and user will login on the browser. After that, as you see in IdentityServer configurations, IdentityServer will redirect 'bookstore://' url that only contains scheme and that scheme is not http. Our application will handle that scheme and will be launched with parameters.

Android

• Start with creating a new Activity named BookStoreWebAuthenticatorCallbackActivity

  using Android.App;
  using Android.Content;
  using Android.Content.PM;
  
  namespace Acme.BookStore.MauiClient.Platforms.Android;
  
  [Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop)]
  [IntentFilter(new[] { Intent.ActionView },
      Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
      DataScheme = CALLBACK_SCHEME)]
  public class BookStoreWebAuthenticatorCallbackActivity : Microsoft.Maui.Essentials.WebAuthenticatorCallbackActivity
  {
      const string CALLBACK_SCHEME = "bookstore";
  }
  

• Add CustomTabsService to AndroidManifest.xml as below. (queries tags only.)

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
      <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="30" />
      <application android:allowBackup="true" android:icon="@mipmap/appicon" android:roundIcon="@mipmap/appicon_round" android:supportsRtl="true"></application>
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <queries>
      <intent>
      <action android:name="android.support.customtabs.action.CustomTabsService" />
      </intent>
  </queries>
  </manifest>
  

  For some reason, an error occurs with my emulator while targeting SDK 31, so I've changed the target SDK to 30.

• Run the Application and perform a login operation. AccessToken will be retrieved.

  

iOS/MacCatalyst

• Add following key to Info.plist

  <key>CFBundleURLTypes</key>
  <array>
      <dict>
          <key>CFBundleURLName</key>
          <string>mauiessentials</string>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>bookstore</string>
          </array>
          <key>CFBundleTypeRole</key>
          <string>Editor</string>
      </dict>
  </array>
  

• Open AppDelegate class and override OpenUrl and ContinueUserActivity methods

  public override bool OpenUrl(UIApplication app, NSUrl url, NSDictionary options)
  {
      if (Microsoft.Maui.Essentials.Platform.OpenUrl(app, url, options))
          return true;
  
      return base.OpenUrl(app, url, options);
  }
  
  public override bool ContinueUserActivity(UIApplication application, NSUserActivity userActivity, UIApplicationRestorationHandler completionHandler)
  {
      if (Microsoft.Maui.Platform.ContinueUserActivity(application, userActivity, completionHandler))
          return true;
      return base.ContinueUserActivity(application, userActivity, completionHandler);
  }
  

• Make all steps for MacCatalyst, too.

Tip: If your IDE struggles while displaying references and namespace suggestions, make sure you're displaying that file with iOS Target Framework.

You'll find it at the top of the editor.

UWP (Windows)

• Add following protocol extension in Package.appxmanifest file.

  <Applications>
      <Application Id="App"
      Executable="$targetnametoken$.exe"
      EntryPoint="$targetentrypoint$">
      <Extensions>
              <uap:Extension Category="windows.protocol">
              <uap:Protocol Name="bookstore">
                  <uap:DisplayName>BookStore</uap:DisplayName>
              </uap:Protocol>
              </uap:Extension>
          </Extensions>
      </Application>
  </Applications>
  

  Currently UWP has a bug in MAUI Essentials, I believe the MAUI team will solve it as soon as possible. You can track the status of issue: https://github.com/dotnet/maui/issues/2702

• That's it on Windows side. Run the application.

Refreshing the access token

IdentityServer doesn't return a refresh token by default. So we have to add offline_access to our scope while sending login request.

• Add offline_access to scope in MauiApplication.cs that we configured before.

  builder.Services.AddTransient<OidcClient>(sp =>
              new OidcClient(new OidcClientOptions
              {
                  // Use your own ngrok url:
                  Authority = "https://46fd-45-156-29-175.ngrok.io",
                  ClientId = "BookStore_Maui",
                  RedirectUri = "bookstore://",
                  Scope = "openid email profile role BookStore offline_access", // <-- Final state must be like this.
                  ClientSecret = "1q2w3E*",
                  Browser = sp.GetRequiredService<WebAuthenticatorBrowser>(),
              })
          );
  

• Then check if it's working or not in MainPage.xaml.cs. Update OnLoginClicked method as below

  private async void OnLoginClicked(object sender, EventArgs e)
  {
      try
      {
          var loginResult = await OidcClient.LoginAsync(new LoginRequest());
          await DisplayAlert("Login Result", "Access Token is:\n\n" + loginResult.AccessToken, "Close");
  
          var refreshResult = await OidcClient.RefreshTokenAsync(loginResult.RefreshToken);
          await DisplayAlert("Refresh Result", "New Access Token is: \n\n" + refreshResult.AccessToken, "Close");
      }
      catch (Exception ex)
      {
          await DisplayAlert("Error", ex.ToString(), "ok");
      }
  }
  

Storing the access token

In this step we have to store access token & refresh token for future requests.

Secure Storage is highly recommended to store this kind of sensitive data. But it's not topic of this article. You can configure and use SecureStorage on your own. I'll go with App Properties.

• Add following class to store key names instead of using magic strings in code.

  namespace Acme.BookStore.MauiClient;
  
  public static class OidcConsts
  {
      internal const string AccessTokenKeyName = "__access_token";
      internal const string RefreshTokenKeyName = "__refresh_token";
  }
  

• Then go back to MainPage.xaml.cs and save our tokens after a successfull login.

  private async void OnLoginClicked(object sender, EventArgs e)
  {
      try
      {
          var loginResult = await OidcClient.LoginAsync(new LoginRequest());
  
          App.Current.Properties[OidcConsts.AccessTokenKeyName] = loginResult.AccessToken;
          App.Current.Properties[OidcConsts.RefreshTokenKeyName] = loginResult.RefreshToken;
  
          await App.Current.SavePropertiesAsync();
  
          // Navigate to an inner page here.
      }
      catch (Exception ex)
      {
          await DisplayAlert("Error", ex.ToString(), "ok");
      }
  }
  

• Add following AccessTokenHttpMessageHandler to append AccessToken to our requests & refresh token when required.

  public class AccessTokenHttpMessageHandler : DelegatingHandler
  {
      protected OidcClient OidcClient { get; }
  
      public AccessTokenHttpMessageHandler(OidcClient oidcClient) : base(new HttpClientHandler())
      {
          OidcClient = oidcClient;
      }
  
      protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
      {
          if (App.Current.Properties.TryGetValue(OidcConsts.AccessTokenKeyName, out object currentTokenValue) && currentTokenValue != null)
          {
              request.SetBearerToken(currentTokenValue?.ToString());
              request.Headers.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
          }
  
          var response = await base.SendAsync(request, cancellationToken);
  
          if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
          {
              if (App.Current.Properties.TryGetValue(OidcConsts.RefreshTokenKeyName, out object refreshTokenValue) && refreshTokenValue != null)
              {
                  var refreshResult = await OidcClient.RefreshTokenAsync(refreshTokenValue?.ToString());
  
                  App.Current.Properties[OidcConsts.AccessTokenKeyName] = refreshResult.AccessToken;
                  App.Current.Properties[OidcConsts.RefreshTokenKeyName] = refreshResult.RefreshToken;
                  await App.Current.SavePropertiesAsync();
  
                  request.SetBearerToken(refreshResult.AccessToken);
  
                  return await base.SendAsync(request, cancellationToken);
              }
              else
              {
                  var result = await OidcClient.LoginAsync(new LoginRequest());
                  request.SetBearerToken(result.AccessToken);
  
                  App.Current.Properties[OidcConsts.AccessTokenKeyName] = result.AccessToken;
                  App.Current.Properties[OidcConsts.RefreshTokenKeyName] = result.RefreshToken;
                  await App.Current.SavePropertiesAsync();
                  request.SetBearerToken(result.AccessToken);
  
                  return await base.SendAsync(request, cancellationToken);
              }
          }
  
          return response;
      }
  }
  

• Then register to dependency injection.

  builder.Services.AddSingleton<AccessTokenHttpMessageHandler>();
  builder.Services.AddTransient<HttpClient>(sp =>
      new HttpClient(sp.GetRequiredService<AccessTokenHttpMessageHandler>())
      {
          BaseAddress = new Uri("https://46fd-45-156-29-175.ngrok.io")
      });
  

• Now make we can send request to backend with authentication. Go to MainPage.xaml.cs and send a request right after authentication.

  private async void OnLoginClicked(object sender, EventArgs e)
  {
      try
      {
          var loginResult = await OidcClient.LoginAsync(new LoginRequest());
  
          App.Current.Properties[OidcConsts.AccessTokenKeyName] = loginResult.AccessToken;
          App.Current.Properties[OidcConsts.RefreshTokenKeyName] = loginResult.RefreshToken;
  
          await App.Current.SavePropertiesAsync();
  
          var json = await httpClient.GetStringAsync("/api/identity/users");
  
          await DisplayAlert("/api/identity/users", json, "close");
      }
      catch (Exception ex)
      {
          await DisplayAlert("Error", ex.ToString(), "ok");
      }
  }
  

• Following result will be returned from API.

  

Recap

The purpose of this article is connecting to ABP backend with access token and it's working properly.

I'm planning to integrate HttpApi.Client library of backend project instead of making requests manually as a second part of this article. I'll get inspired by hikalkan/maui-abp-playing repo to achieve that.

This article is about filtering data automatically without writing any LINQ via using AutoFilterer.

AutoFilterer is a mini filtering framework library for dotnet. The main purpose of the library is to generate LINQ expressions for Entities over DTOs automatically. Creating queries without writing any expression code is the most powerful feature that is provided. The first aim of AutoFilterer is to be compatible with Open API 3.0 Specifications, unlike oData & GraphQL.

Disclaimer: AutoFilterer is the one of my personal projects. It's not supported by ABP Framework or ABP Team officially. This article can be shown as self-promotion, so I needed to explain that.

Initializing a New Project

If you are familiar with application development with ABP Framework, you can skip to the next step "Designing the Application.Contracts Layer".

• Create a new project: (I prefer mongodb as database provider to get rid of Ef migrations. You can go with Ef on your own.)

abp new Acme.BookStore -t app -d mongodb

• Create an entity named Book

using System;
using Volo.Abp.Domain.Entities.Auditing;

namespace Acme.BookStore.Books;

public class Book : FullAuditedAggregateRoot<Guid>
{
    public string Title { get; set; }
    public string Language { get; set; }
    public string Country { get; set; }
    public string Author { get; set; }
    public int TotalPage { get; set; }
    public int Year { get; set; }
    public string Link { get; set; }
}

• Add following property to BookStoreMongoDbContext

public IMongoCollection<Book> Books { get; set; }

• Create a DataSeedContributor
  • Add this initial-books.json file to Acme.BookStore.Domain/Books/ path and make build action as Embedded Resource.

using Newtonsoft.Json;
using System;
using System.IO;
using System.Text;
using System.Threading.Tasks;
using Volo.Abp.Data;
using Volo.Abp.DependencyInjection;
using Volo.Abp.Domain.Repositories;

namespace Acme.BookStore.Books;

public class BookstoreDataSeederContributor : IDataSeedContributor, ITransientDependency
{
    protected readonly IRepository<Book, Guid> _repository;

    public BookstoreDataSeederContributor(IRepository<Book, Guid> repository)
    {
        _repository = repository;
    }

    public async Task SeedAsync(DataSeedContext context)
    {
        if (!await _repository.AnyAsync())
        {
            await _repository.InsertManyAsync(GetInitialBooks());
        }
    }

    private Book[] GetInitialBooks()
    {
        var json = GetEmbeddedResourceAsText("Acme.Bookstore.Books.initial-books.json");

        return JsonConvert.DeserializeObject<Book[]>(json);
    }

    private string GetEmbeddedResourceAsText(string nameWithNamespace)
    {
        using var stream = GetType().Assembly.GetManifestResourceStream(nameWithNamespace);

        return Encoding.UTF8.GetString(stream.GetAllBytes());
    }
}

• Run the DbMigrator and database with existing data is ready!

Designing the Application.Contracts Layer

In this section, We'll implement AutoFilterer package and use it for only filtering data. We'll leave Sorting and Paging to ABP Framework, because it already does it well and works with more than one UI compatible.

• Add AutoFilterer package to your Application.Contracts project.

dotnet add package AutoFilterer

• Let's start coding with creating DTOs.

  • BookDto

  using System;
  using Volo.Abp.Application.Dtos;
  
  namespace Acme.BookStore.Books;
  
  [Serializable]
  public class BookDto : AuditedEntityDto<Guid>
  {
      public string Title { get; set; }
      public string Language { get; set; }
      public string Country { get; set; }
      public string Author { get; set; }
      public int TotalPage { get; set; }
      public int Year { get; set; }
      public string Link { get; set; }
  }
  

  • BookGetListInput

  using AutoFilterer.Attributes;
  using AutoFilterer.Enums;
  using AutoFilterer.Types;
  using System;
  using Volo.Abp.Application.Dtos;
  
  namespace Acme.BookStore.Books;
  
  [Serializable]
  // We'll leave Paging and Sorting to ABP, we'll use only filtering feature of AutoFilterer.
  // So using FilterBase as a base class is enough.
  public class BookGetListInput : FilterBase, IPagedAndSortedResultRequest
  {
      // Configure 'Filter' property for built-in search boxes.
      [CompareTo(
          nameof(BookDto.Title),
          nameof(BookDto.Language),
          nameof(BookDto.Author),
          nameof(BookDto.Country)
          )]
      [StringFilterOptions(StringFilterOption.Contains)]
      public string Filter { get; set; }
  
      // IPagedAndSortedResultRequest implementation below.
      public int SkipCount { get; set; }
  
      public int MaxResultCount { get; set; }
  
      public string Sorting { get; set; }
  }
  

  • IBookAppService

  using System;
  using Volo.Abp.Application.Services;
  
  namespace Acme.BookStore.Books;
  
  public interface IBookAppService : ICrudAppService<BookDto, Guid, BookGetListInput>
  {
  }
  

Implementing Application Layer

I prefer using CrudAppService to skip unrelated CRUD operations.

• Create BookAppService and apply AutoFilterer filtering to queryable via overriding CreateFilteredQueryAsync.

using AutoFilterer.Extensions;
using System;
using System.Linq;
using System.Threading.Tasks;
using Volo.Abp.Application.Services;
using Volo.Abp.Domain.Repositories;

namespace Acme.BookStore.Books;

public class BookAppService : CrudAppService<Book, BookDto, Guid, BookGetListInput>
{
    public BookAppService(IRepository<Book, Guid> repository) : base(repository)
    {
    }

    protected override async Task<IQueryable<Book>> CreateFilteredQueryAsync(BookGetListInput input)
    {
        return (await base.CreateFilteredQueryAsync(input))
            .ApplyFilter(input);
    }
}

• Add following mapping in BookStoreApplicationAutoMapperProfile

CreateMap<Book, BookDto>().ReverseMap();

Displaying on UI

Let's start with creating a page to show data list and filter it with a textbox.

• Create Books/Index.cshtml / Books/Index.cshtml.cs

namespace Acme.BookStore.Web.Pages.Books;

public class IndexModel : BookStorePageModel
{
}

@page
@using Acme.BookStore.Localization
@using Acme.BookStore.Web.Pages.Books
@using Microsoft.Extensions.Localization

@model IndexModel

@inject IStringLocalizer<BookStoreResource> L

<h2>Books</h2>

@section scripts
{
	<abp-script src="/Pages/Books/index.js" />
}

<abp-card>
	<abp-card-header>
		<h2>@L["Books"]</h2>
	</abp-card-header>
	<abp-card-body>
		<abp-table striped-rows="true" id="BooksTable"></abp-table>
	</abp-card-body>
</abp-card>

• Create index.js in the same folder

$(function () {
    var l = abp.localization.getResource('BookStore');

    var dataTable = $('#BooksTable').DataTable(
        abp.libs.datatables.normalizeConfiguration({
            serverSide: true,
            paging: true,
            order: [[1, "asc"]],
            searching: true,
            scrollX: true,
            ajax: abp.libs.datatables.createAjax(acme.bookStore.books.book.getList),
            columnDefs: [
                {
                    title: l('Title'),
                    data: "title"
                },
                {
                    title: l('Language'),
                    data: "language",
                },
                {
                    title: l('Country'),
                    data: "country",
                },
                {
                    title: l('Author'),
                    data: "author"
                },
                {
                    title: l('TotalPage'),
                    data: "totalPage",
                    render: function (data) {
                        return data + ' pages'
                    }
                },
                {
                    title: l('Year'),
                    data: "year"
                },
                {
                    title: l('Link'),
                    data: "link",
                    render: function (data) {
                        return '<a href="' + data + '" target="_blank">Link</a>';
                    }
                },
            ]
        })
    );
});

• Run the project and see how it's working!

Filtering Specific Properties

AutoFilterer supports some different features like Filtering with Range. Let's filter TotalPage and Year properties with range.

• Add following TotalPage and Year properties to BookGetListInput.

public class BookGetListInput : FilterBase, IPagedAndSortedResultRequest
{
    // Configure 'Filter' property for built-in search boxes.
    [CompareTo(
        nameof(BookDto.Title),
        nameof(BookDto.Language),
        nameof(BookDto.Author),
        nameof(BookDto.Country)
        )]
    [StringFilterOptions(StringFilterOption.Contains)]
    public string Filter { get; set; }

    public Range<int> TotalPage { get; set; } // <-- Add this one

    public Range<int> Year { get; set; } // <-- and this

    // IPagedAndSortedResultRequest implementation below.
    public int SkipCount { get; set; }

    public int MaxResultCount { get; set; }

    public string Sorting { get; set; }
}

• Update Index.cshtml too

@page
@using Acme.BookStore.Localization
@using Acme.BookStore.Web.Pages.Books
@using Microsoft.Extensions.Localization

@model IndexModel

@inject IStringLocalizer<BookStoreResource> L

<h2>Books</h2>

@section scripts
{
	<abp-script src="/Pages/Books/index.js" />
}

<abp-card>
	<abp-card-header>
		<h2>@L["Books"]</h2>
	</abp-card-header>
	<abp-card-body>
		<div id="books-filter-wrapper">
			<div class="row">

				<div class="col-6">
					<label class="form-label"> TotalPage </label>
					<div class="row">
						<div class="col-6">
							<label class="form-label">Min</label>
							<input id="TotalPageMin" type="number" class="form-control" />
						</div>
						<div class="col-6">
							<label class="form-label">Max</label>
							<input id="TotalPageMax" type="number" class="form-control" />
						</div>
					</div>
				</div>

				<div class="col-6">
					<label class="form-label"> Year </label>
					<div class="row">
						<div class="col-6">
							<label class="form-label">Min</label>
							<input id="YearMin" type="number" class="form-control" />
						</div>
						<div class="col-6">
							<label class="form-label">Max</label>
							<input id="YearMax" type="number" class="form-control" />
						</div>
					</div>
				</div>

			</div>
		</div>
		<div class="mt-2">
			<abp-table striped-rows="true" id="BooksTable"></abp-table>
		</div>
	</abp-card-body>
</abp-card>

• Update index.js file to send those parameters to API

$(function () {
    var l = abp.localization.getResource('BookStore');

    var getFilter = function () {
        return {
            totalPage: {
                min: $('#TotalPageMin').val(),
                max: $('#TotalPageMax').val()
            },
            year: {
                min: $('#YearMin').val(),
                max: $('#YearMax').val()
            }
        };
    };

    $("#books-filter-wrapper :input").on('input', function () {
        dataTable.ajax.reload();
    });

    var dataTable = $('#BooksTable').DataTable(
        abp.libs.datatables.normalizeConfiguration({
            serverSide: true,
            paging: true,
            order: [[1, "asc"]],
            searching: true,
            scrollX: true,
            ajax: abp.libs.datatables.createAjax(acme.bookStore.books.book.getList, getFilter),
            columnDefs: [
                {
                    title: l('Title'),
                    data: "title"
                },
                {
                    title: l('Language'),
                    data: "language",
                },
                {
                    title: l('Country'),
                    data: "country",
                },
                {
                    title: l('Author'),
                    data: "author"
                },
                {
                    title: l('TotalPage'),
                    data: "totalPage",
                    render: function (data) {
                        return data + ' pages'
                    }
                },
                {
                    title: l('Year'),
                    data: "year"
                },
                {
                    title: l('Link'),
                    data: "link",
                    render: function (data) {
                        return '<a href="' + data + '" target="_blank">Link</a>';
                    }
                },
            ]
        })
    );
});

• Run the Application and see the result

Source-Code

You can find final version of this example on github.

• enisn/abp-autofilterer-sample

Discussion

There is a couple of questions that you can think about. In this "Discussion" section I'll try to answer them.

Is Defining Comparison in Dto ok?

As a first impression, I tough, it's not ok because Application.Contracts can be shipped to clients. It's true, definition of filter is in DTO, but the implementation is in Application layer. So if a developer who implements client-side, can see something like below.

public class BookGetListInput : FilterBase, IPagedAndSortedResultRequest
{
    // Configure 'Filter' property for built-in search boxes.
    [CompareTo(
        nameof(BookDto.Title),
        nameof(BookDto.Language),
        nameof(BookDto.Author),
        nameof(BookDto.Country)
        )]
    [StringFilterOptions(StringFilterOption.Contains)]
    public string Filter { get; set; }
}

I think that's ok, because the developer'll understand what filtering does. It's kind of documentation with attributes.

Why didn't use Sorting & Pagination feature of AutoFilterer

ABP does those features well and UI frameworks(Razor Pages, Angular and Blazor) already implemented sorting and pagination with those existin parameters. Chaning cost is high because if you change, you'll need to implement them for each UI framework.

This is an example project to show how to use Cosmos DB in an ABP application. See the article that explains this project:

https://abp.io/community/articles/using-cosmosdb-with-the-abp-framework-via-mongodb-api-x47bjeik

Project Status: Currently, the project doesn't have any business logic. We've just brought ABP's pre-built modules (Identity, Tenant Management, IdentityServer, etc) together as a base solution. However, it is fully working and you can now take it as a base solution for your microservice project. From now on, we will build the example application functionalities / business logic on top of it.

Source Code

The source code is available on abpframework/eShopOnAbp repository.

The Big Picture

The project follows micro-service architecture and overall structure is presented below.

How to Run?

You can either run in Visual Studio, or using Microsoft Tye. Tye is a developer tool that makes developing, testing, and deploying micro-services and distributed applications easier.

Requirements

• .NET 5.0+
• Docker
• Yarn

Instructions

• Clone the repository ( eShopOnAbp )

• Install Tye (follow these steps)

• Execute run-tye.ps1

• Wait until all applications are up!

  • You can check running application from tye dashboard (localhost:8000)

• After all your backend services are up, start the angular application:

  cd apps/angular
  yarn start
  

What's Next?

We'll work on deployment & CI-CD processes as a next step and build the business logic on. First goal is deploying the entire application on Kubernetes.

Feedback

Your comments and suggestions is important for us. You can ask your questions or post your feedback under this discussion entry.