@ -0,0 +1,173 @@ |
|||
# .NET 10: What You Need to Know (LTS Release, Coming November 2025) |
|||
|
|||
The next version of .NET is .NET 10 and it is coming with **Long-Term Support (LTS)**, scheduled for **November 2025**. |
|||
|
|||
On **September 9, 2025**, Microsoft released **.NET 10 Release Candidate 1 (RC1)**, which supports go-live usage and is compatible with [Visual Studio 2026 Insider](https://visualstudio.microsoft.com/insiders/) and [Visual Studio Code Insider](https://code.visualstudio.com/insiders/) via the [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension. |
|||
|
|||
------ |
|||
|
|||
## .NET 10 Runtime Enhancements |
|||
|
|||
- **JIT Speed-ups**: Enhanced struct argument handling—members now go directly into registers, reducing memory load/store operations. |
|||
- **Advanced Loop Optimization**: New graph-based loop inversion improves precision and boosts further optimizations. |
|||
- **Array Interface De-virtualization**: Critical for performance, now array-based enumerations inline and skip virtual calls including de-abstraction of array enumeration and small-array stack allocation. |
|||
- **General JIT Improvements**: Better code layout and branch reduction support overall efficiency. |
|||
|
|||
------ |
|||
|
|||
## Language & Library Upgrades |
|||
|
|||
### C# 14 Enhancements |
|||
|
|||
- Field-backed properties: easier custom getters/setters. |
|||
- `nameof` for unbound generics like `List<>`. |
|||
- Implicit conversions for `Span<T>` and `ReadOnlySpan<T>`. |
|||
- Lambda parameter modifiers (`ref`, `in`, `out`). |
|||
- Partial constructors/events. |
|||
- `extension` blocks for static extension members. |
|||
- Null-conditional assignment (`?.=`) and custom compound/increment operators. |
|||
|
|||
### F# & Visual Basic Enhancements |
|||
|
|||
- F# improvements via `<LangVersion>preview</LangVersion>`, updated `FSharp.Core`, and compiler fixes. |
|||
- VB compiler supports `unmanaged` generics and respects `OverloadResolutionPriorityAttribute` for performance and overload clarity. |
|||
|
|||
## .NET Libraries & SDK |
|||
|
|||
### Libraries: |
|||
|
|||
- Better ZipArchive performance (lazy entry loading). |
|||
- JSON improvements, including `JsonSourceGenerationOptions` and reference-handling tweaks. |
|||
- Enhanced `OrderedDictionary`, ISOWeek date APIs, PEM data and certificate handling, `CompareOptions.NumericOrdering` |
|||
|
|||
### SDK & CLI: |
|||
|
|||
- No major new SDK features in RC1—you should expect stability fixes rather than additions. |
|||
- Earlier previews brought JSON support improvements (e.g., `PipeReader` for JSON, WebSocketStream, ML-DSA crypto, AES KeyWrap), TLS 1.3 for macOS |
|||
|
|||
------ |
|||
|
|||
## ASP.NET Core & Blazor |
|||
|
|||
### Blazor & Web App Security: |
|||
|
|||
Enhanced OIDC and Microsoft Entra ID integration, including encrypted token caching and Key Vault use. |
|||
|
|||
### UI Enhancements: |
|||
|
|||
- `QuickGrid` gains `RowClass` for conditional styling. |
|||
- Scripts now served as static assets with compression and fingerprinting. |
|||
- NavigationManager no longer scrolls to top for same-page updates. |
|||
|
|||
### API Improvements: |
|||
|
|||
Full support for OpenAPI 3.1 (JSON Schema draft 2020-12), and metrics for authentication/authorization events (e.g., sign-ins, logins) . |
|||
|
|||
------ |
|||
|
|||
## .NET MAUI |
|||
|
|||
Updates include multiple file selection, image compression, WebView request interception, and support for Android API 35/36. |
|||
|
|||
## EF Core |
|||
|
|||
LINQ enhancements, performance boosts, better Azure Cosmos DB support, and more flexible named query filters. |
|||
|
|||
|
|||
|
|||
## Breaking Changes in .NET 10 |
|||
|
|||
### ASP.NET Core - Breaking Changes in .NET 10: |
|||
|
|||
.NET 10 Preview 7 brings **several deprecations + behavior changes**, while **RC1 removes the old WebHost model**. |
|||
|
|||
- **[Cookie login redirects disabled](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/cookie-authentication-api-endpoints)** → Redirects no longer occur for API endpoints; APIs now return `401`/`403`. *(Behavioral change)* |
|||
- **[WithOpenApi deprecated](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/withopenapi-deprecated)** → Extension method removed; use updated OpenAPI generator features. *(Source incompatible)* |
|||
- **[Exception diagnostics suppressed](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/exception-handler-diagnostics-suppressed)** → When `TryHandleAsync` returns true, exception details aren’t logged. *(Behavioral change)* |
|||
- **[IActionContextAccessor obsolete](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/iactioncontextaccessor-obsolete)** → Marked obsolete; may break code depending on it. *(Source/behavioral change)* |
|||
- **[IncludeOpenAPIAnalyzers deprecated](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/openapi-analyzers-deprecated)** → Property and MVC API analyzers removed. *(Source incompatible)* |
|||
- **[IPNetwork & KnownNetworks obsolete](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/ipnetwork-knownnetworks-obsolete)** → Old networking APIs removed in favor of new ones. *(Source incompatible)* |
|||
- **[ApiDescription.Client package deprecated](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/apidescription-client-deprecated)** → No longer maintained; migrate to other tools. *(Source incompatible)* |
|||
- **[Razor run-time compilation obsolete](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete)** → Disabled at runtime; precompilation required. *(Source incompatible)* |
|||
- **[WebHostBuilder, IWebHost, WebHost obsolete](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/webhostbuilder-deprecated)** → Legacy hosting model deprecated; use `WebApplicationBuilder`. *(Source incompatible, RC1)* |
|||
|
|||
### EF Core - Breaking Changes in .NET 10: |
|||
|
|||
You can find the complete list at [Microsoft EF Core 10 Breaking Changes page](https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-10.0/breaking-changes). Here's the brief summary: |
|||
|
|||
#### EF Core - SQL Server |
|||
|
|||
- **JSON column type by default (Azure SQL / compat level ≥170).** Primitive collections and owned types mapped to JSON now use SQL Server’s native `json` type instead of `nvarchar(max)`. A migration may alter existing columns. Mitigate by setting compat level <170 or explicitly forcing `nvarchar(max)`. |
|||
- **`ExecuteUpdateAsync` signature change.** Column setters now take a regular `Func<…>` (not an expression). Dynamic expression-tree code won’t compile; replace with imperative setters inside the lambda. |
|||
|
|||
#### Microsoft.Data.Sqlite |
|||
|
|||
- **`GetDateTimeOffset` (no offset) assumes UTC.** Previously assumed local time. You can temporarily revert via `AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", true)`. |
|||
- **Writing `DateTimeOffset` to REAL stores UTC.** Conversion now happens before writing; revertable with the same switch. |
|||
- **`GetDateTime` (with offset) returns UTC `DateTime` (`DateTimeKind.Utc`).** Was `Local` before. Same temporary switch if needed. |
|||
|
|||
#### Who’s most affected |
|||
|
|||
- Apps on **Azure SQL / SQL Server 2025** using JSON mapping. |
|||
- Codebases building **expression trees** for bulk updates. |
|||
- Apps using **SQLite** with date/time parsing or REAL timestamp storage. |
|||
|
|||
#### Quick mitigations |
|||
|
|||
- Set SQL Server compatibility <170 or force column type. |
|||
- Rewrite `ExecuteUpdateAsync` callers to use the new delegate form. |
|||
- For SQLite, update handling to UTC or use the temporary AppContext switch while transitioning. |
|||
|
|||
### Containers - Breaking Changes in .NET 10: |
|||
|
|||
Default .NET images now use [Ubuntu](https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/10.0/default-images-use-ubuntu). |
|||
|
|||
### Core Libraries - Breaking Changes in .NET 10: |
|||
|
|||
[ActivitySource](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/10.0/activity-sampling) behavior tweaks; [generic math](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/10.0/generic-math) shift behavior aligned; W3C trace context is [default](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/10.0/default-trace-context-propagator); [DriveInfo](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/10.0/driveinfo-driveformat-linux) reports Linux FS types; InlineArray size rules tightened; [System.Linq.AsyncEnumerable](https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/10.0/asyncenumerable) included in core libs... |
|||
|
|||
### Cryptography - Breaking Changes in .NET 10: |
|||
|
|||
[Stricter X500](https://learn.microsoft.com/en-us/dotnet/core/compatibility/cryptography/10.0/x500distinguishedname-validation) name validation; [OpenSSL](https://learn.microsoft.com/en-us/dotnet/core/compatibility/cryptography/10.0/openssl-macos-unsupported) primitives unsupported on macOS; [some key members](https://learn.microsoft.com/en-us/dotnet/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey) nullable/renamed; env var [rename to](https://learn.microsoft.com/en-us/dotnet/core/compatibility/cryptography/10.0/version-override) `DOTNET_OPENSSL_VERSION_OVERRIDE`. |
|||
|
|||
### Extensions - Breaking Changes in .NET 10: |
|||
|
|||
[Config preserves](https://learn.microsoft.com/en-us/dotnet/core/compatibility/extensions/10.0/configuration-null-values-preserved) nulls; [logging](https://learn.microsoft.com/en-us/dotnet/core/compatibility/extensions/10.0/console-json-logging-duplicate-messages)/[package](https://learn.microsoft.com/en-us/dotnet/core/compatibility/extensions/10.0/provideraliasattribute-moved-assembly)/trim annotations changes; some [trim-unsafe](https://learn.microsoft.com/en-us/dotnet/core/compatibility/extensions/10.0/dynamically-accessed-members-configuration) code annotations removed. |
|||
|
|||
### Globalization & Interop - Breaking Changes in .NET 10: |
|||
|
|||
[ICU](https://learn.microsoft.com/en-us/dotnet/core/compatibility/globalization/10.0/version-override) env var renamed; single-file apps stop probing executable dir for native libs; [DllImport](https://learn.microsoft.com/en-us/dotnet/core/compatibility/interop/10.0/search-assembly-directory) search path tightened. |
|||
|
|||
Networking: |
|||
|
|||
[HTTP/3 disabled ](https://learn.microsoft.com/en-us/dotnet/core/compatibility/networking/10.0/http3-disabled-with-publishtrimmed) by default when trimming; [default cert revocation](https://learn.microsoft.com/en-us/dotnet/core/compatibility/networking/10.0/ssl-certificate-revocation-check-default) check now Online; [browser clients](https://learn.microsoft.com/en-us/dotnet/core/compatibility/networking/10.0/default-http-streaming) stream responses by default; [URI length limits](https://learn.microsoft.com/en-us/dotnet/core/compatibility/networking/10.0/uri-length-limits-removed) removed. |
|||
|
|||
### SDK & MSBuild/NuGet - Breaking Changes in .NET 10: |
|||
|
|||
`dotnet --interactive` [defaults to true](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/dotnet-cli-interactive); tool packages are [RID-specific](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/dotnet-tool-pack-publish); [workload](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/default-workload-config) sets default; `dotnet new sln` uses [SLNX](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/dotnet-new-sln-slnx-default); restore audits transitives; [local tool](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest) install creates manifest by default; `project.json` [not supported](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/dotnet-restore-project-json-unsupported); stricter NuGet [validation](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/nuget-packageid-validation)/[errors](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/10.0/http-warnings-to-errors). |
|||
|
|||
WinForms/WPF: |
|||
|
|||
Multiple [API obsoletions](https://learn.microsoft.com/en-us/dotnet/core/compatibility/windows-forms/10.0/obsolete-apis)/parameter [renames](https://learn.microsoft.com/en-us/dotnet/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation); [rendering](https://learn.microsoft.com/en-us/dotnet/core/compatibility/windows-forms/10.0/statusstrip-renderer)/behavior tweaks; stricter XAML rules (e.g., [disallow empty row](https://learn.microsoft.com/en-us/dotnet/core/compatibility/wpf/10.0/empty-grid-definitions)/column definitions or incorrect usage of [DynamicResource](https://learn.microsoft.com/en-us/dotnet/core/compatibility/wpf/10.0/dynamicresource-crash) will crash). |
|||
|
|||
|
|||
|
|||
------ |
|||
|
|||
|
|||
|
|||
## Support Policy for .NET 10 |
|||
As you can see from the picture below, **.NET 10 has long term support** therefore it will be maintained for 3 years **until November 2028**. |
|||
|
|||
[](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core) |
|||
|
|||
|
|||
|
|||
## Download .NET10 |
|||
|
|||
Click 👉 https://dotnet.microsoft.com/en-us/download/dotnet/10.0 to download the latest release candidate (currently RC.1). |
|||
|
|||
[](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) |
|||
|
|||
Also to use the latest features, download/update your Visual Studio to the latest 👉 https://visualstudio.microsoft.com/downloads/ |
|||
|
|||
|
After Width: | Height: | Size: 530 KiB |
|
After Width: | Height: | Size: 48 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 769 KiB |
@ -0,0 +1,191 @@ |
|||
# **Truly Layering a .NET Application Based on DDD Principles** |
|||
|
|||
Okay, so we ALL been there, right? You start new project thinking "this time will be different" - clean code, perfect architecture, everything organized. Fast forward 3 months and your codebase look like someone throw grenade into bowl of spaghetti. Business logic everywhere, your controllers doing database work, and every new feature feel like defusing bomb. |
|||
|
|||
I been there too many times, and honestly, it suck. But here thing - there actually way to build .NET apps that not turn into maintenance nightmare. It called **Layered Architecture** + **Domain-Driven Design (DDD)**, and once you get it, it game changer. |
|||
|
|||
Let me walk you through this step by step, no fluff, just practical stuff that actually work. |
|||
|
|||
### **Layered Architecture 101 (The Foundation)** |
|||
|
|||
So layered architecture basically about keeping your code organized. Instead of having everything mixed together like bad smoothie, you separate concerns into different layers. Think like organizing your room - clothes go in closet, books on shelf, etc. |
|||
|
|||
Here how it typically break down: |
|||
|
|||
* **Presentation Layer (UI):** This what users actually see and click on - your ASP.NET Core MVC stuff, Razor Pages, Blazor, whatever float your boat. |
|||
* **Application Layer:** The conductor of orchestra. It not do heavy lifting itself, but tell everyone else what to do. It like middle manager of your code. |
|||
* **Domain Layer:** The VIP section. This where all your business rules live - entities, value objects, whole nine yards. This layer pure and not give damn about databases or UI. |
|||
* **Infrastructure Layer:** The "how-to" guy. Database stuff, email sending, API calls - basically all technical plumbing that make everything work. |
|||
|
|||
The golden rule? **Dependency Rule**: Layers can only talk to layers below them (or more central). UI talk to Application, Application talk to Domain, but Domain? Domain not talk to anyone. It the cool kid that everyone want to hang out with. |
|||
|
|||
### **DDD: Where Magic Happen** |
|||
|
|||
Alright, so DDD not some fancy framework you install from NuGet. It more like mindset - basically saying "hey, let make our code actually reflect business we building for." Instead of having bunch of random classes, we organize everything around actual business domain. |
|||
|
|||
Think like this: if you building e-commerce app, your code should scream "I'M E-COMMERCE APP" not "I'M BUNCH OF RANDOM CLASSES." |
|||
|
|||
Here toolkit DDD give you (all living in your Domain Layer): |
|||
|
|||
* **Entity:** This something that have identity. Like `Customer` - two customers with same name still different people because they have different IDs. It like having two friends named John - they not same person. |
|||
* **Value Object:** Opposite of entity. It defined by what it contain, not who it is. `Address` perfect for this - if two addresses have same street, city, and zip code, they same address. Usually immutable too. |
|||
* **Aggregate & Aggregate Root:** This where it get interesting. Aggregate like family of related objects that stick together. **Aggregate Root** head of family - only one you talk to when you want change something. Like `Order` that contain `OrderItem`s. You not mess with `OrderItem` directly, you tell `Order` to handle it. |
|||
* **Repository (Interface):** Think like your data access contract. It say "here how you can get and save stuff" without caring about whether it SQL Server, MongoDB, or file on your desktop. Interface live in Domain, implementation go in Infrastructure. |
|||
* **Domain Service:** When business logic too complex for single entity or value object, this your go-to. It like utility class but for business rules. |
|||
|
|||
### **Putting It All Together: Real C# Code** |
|||
|
|||
Alright, enough theory. Let see what this actually look like in real .NET solution. You typically have projects like: |
|||
|
|||
* `MyProject.Domain` (or `.Core`) - The VIP section |
|||
* `MyProject.Application` - The middle manager |
|||
* `MyProject.Infrastructure` - The technical guy |
|||
* `MyProject.Web` (or whatever UI you using) - The pretty face |
|||
|
|||
**1. The Domain Layer (`MyProject.Domain`) - The Heart** |
|||
|
|||
This where magic happen. Zero dependencies on other projects (maybe some basic utility libraries, but that it). Pure business logic, no database nonsense, no UI concerns. |
|||
|
|||
```csharp |
|||
// In MyProject.Domain/Orders/Order.cs |
|||
public class Order : AggregateRoot<Guid> |
|||
{ |
|||
public Address ShippingAddress { get; private set; } |
|||
private readonly List<OrderItem> _orderItems = new(); |
|||
public IReadOnlyCollection<OrderItem> OrderItems => _orderItems.AsReadOnly(); |
|||
|
|||
// Private constructor for ORM |
|||
private Order() { } |
|||
|
|||
public Order(Guid id, Address shippingAddress) : base(id) |
|||
{ |
|||
ShippingAddress = shippingAddress; |
|||
} |
|||
|
|||
public void AddOrderItem(Guid productId, int quantity, decimal price) |
|||
{ |
|||
if (quantity <= 0) |
|||
{ |
|||
throw new BusinessException("Quantity must be greater than zero."); |
|||
} |
|||
// More business rules... |
|||
_orderItems.Add(new OrderItem(productId, quantity, price)); |
|||
} |
|||
} |
|||
|
|||
// In MyProject.Domain/Orders/IOrderRepository.cs |
|||
public interface IOrderRepository |
|||
{ |
|||
Task<Order> GetAsync(Guid id); |
|||
Task AddAsync(Order order); |
|||
Task UpdateAsync(Order order); |
|||
} |
|||
``` |
|||
|
|||
See what I mean? The `Order` class all about business rules (`AddOrderItem` with validation and all that jazz). It not give damn about databases or how it get saved. That someone else problem. |
|||
|
|||
**2. The Application Layer (`MyProject.Application`) - The Conductor** |
|||
|
|||
This where we orchestrate everything. It talk to domain objects and use repositories to get/save data. Think like middle manager that coordinate work but not do heavy lifting. |
|||
|
|||
```csharp |
|||
// In MyProject.Application/Orders/OrderAppService.cs |
|||
public class OrderAppService |
|||
{ |
|||
private readonly IOrderRepository _orderRepository; |
|||
|
|||
public OrderAppService(IOrderRepository orderRepository) |
|||
{ |
|||
_orderRepository = orderRepository; |
|||
} |
|||
|
|||
public async Task CreateOrderAsync(CreateOrderDto input) |
|||
{ |
|||
var shippingAddress = new Address(input.Street, input.City, input.ZipCode); |
|||
var order = new Order(Guid.NewGuid(), shippingAddress); |
|||
|
|||
foreach (var item in input.Items) |
|||
{ |
|||
order.AddOrderItem(item.ProductId, item.Quantity, item.Price); |
|||
} |
|||
|
|||
await _orderRepository.AddAsync(order); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The application service coordinate everything but let domain objects handle actual business rules. Clean separation! |
|||
|
|||
**3. The Infrastructure Layer (`MyProject.Infrastructure`) - The Technical Guy** |
|||
|
|||
This where we implement all interfaces we defined in domain. Entity Framework Core, email services, API clients - all technical plumbing live here. |
|||
|
|||
```csharp |
|||
// In MyProject.Infrastructure/Orders/EfCoreOrderRepository.cs |
|||
public class EfCoreOrderRepository : IOrderRepository |
|||
{ |
|||
private readonly MyDbContext _dbContext; |
|||
|
|||
public EfCoreOrderRepository(MyDbContext dbContext) |
|||
{ |
|||
_dbContext = dbContext; |
|||
} |
|||
|
|||
public async Task<Order> GetAsync(Guid id) |
|||
{ |
|||
// EF Core logic to get the order |
|||
return await _dbContext.Orders.FindAsync(id); |
|||
} |
|||
|
|||
public async Task AddAsync(Order order) |
|||
{ |
|||
await _dbContext.Orders.AddAsync(order); |
|||
} |
|||
|
|||
// ... other implementations |
|||
} |
|||
``` |
|||
|
|||
### **ABP Framework: The Shortcut (Because We Lazy)** |
|||
|
|||
Look, setting all this up from scratch pain. That where **ABP Framework** come in clutch. It basically DDD and layered architecture on steroids, and it do all boring setup work for you. |
|||
|
|||
ABP not just talk talk - it walk walk. When you create new ABP solution, boom! Perfect project structure, all layered and DDD-compliant, ready to go. |
|||
|
|||
Here what you get out of box: |
|||
|
|||
* **Base Classes:** `AggregateRoot`, `Entity`, `ValueObject` - all with good stuff like optimistic concurrency and domain events. No more writing boilerplate. |
|||
* **Generic Repositories:** No more writing `IRepository` interfaces for every single entity. ABP give you `IRepository<TEntity, TKey>` with all standard CRUD methods. Just inject it and go. |
|||
* **Application Services:** Inherit from `ApplicationService` and boom - you done. It handle validation, authorization, exception handling, all that cross-cutting concern stuff without cluttering your actual business logic. |
|||
|
|||
With ABP, our `OrderAppService` become way cleaner: |
|||
|
|||
```csharp |
|||
// In ABP project, this much cleaner |
|||
public class OrderAppService : ApplicationService, IOrderAppService |
|||
{ |
|||
private readonly IRepository<Order, Guid> _orderRepository; |
|||
|
|||
public OrderAppService(IRepository<Order, Guid> orderRepository) |
|||
{ |
|||
_orderRepository = orderRepository; |
|||
} |
|||
|
|||
public async Task CreateAsync(CreateOrderDto input) |
|||
{ |
|||
// ... same logic as before, but using ABP generic repository |
|||
var order = new Order(...); |
|||
await _orderRepository.InsertAsync(order); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### **Wrapping Up** |
|||
|
|||
Look, I get it - this stuff take discipline and it not always fastest way to get features out door. But here thing: when you actually layer your app properly and put solid Domain Model at center, you end up with software that not suck to maintain. |
|||
|
|||
Your code start speaking language of business instead of some random technical jargon. That whole point of DDD - make your code reflect what you actually building for. |
|||
|
|||
Yeah, it take work upfront, but payoff huge. And frameworks like ABP make journey way less painful. Trust me, your future self will thank you when you not debugging spaghetti code at 2 AM. |
|||
|
|||
What you think? You try this approach before, or you still stuck in spaghetti code phase? Let me know in comments! |
|||
@ -0,0 +1,333 @@ |
|||
# Best Practices Guide for REST API Design |
|||
|
|||
This guide compiles best practices for building robust, scalable, and sustainable RESTful APIs, based on information gathered from various sources. |
|||
|
|||
## 1. Fundamentals of REST Architecture |
|||
|
|||
REST is based on specific constraints and principles that support features like simplicity, scalability, and statelessness. The six core principles of RESTful architecture are: |
|||
|
|||
- **Uniform Interface**: This is about consistency. You use standard HTTP methods (GET, POST, PUT, DELETE) and URIs to interact with resources. The client knows how to talk to the server without needing some custom instruction manual. |
|||
|
|||
- **Client-Server**: The client (e.g., a frontend app) and the server are separate. The server handles data and logic, the client handles the user interface. They can evolve independently as long as the API contract doesn't change. |
|||
|
|||
- **Stateless**: This is a big one. The server doesn't remember anything about the client between requests. Every single request must contain all the info needed to process it (like an auth token). This is key for scalability. |
|||
|
|||
- **Cacheable**: Responses should declare whether they can be cached or not. Good caching can massively improve performance and reduce server load. |
|||
|
|||
- **Layered System**: You can have things like proxies or load balancers between the client and the server without the client knowing. It just talks to one endpoint, and the layers in between handle the rest. |
|||
|
|||
- **Code on Demand (Optional)**: This is the only optional one. It means the server can send back executable code (like JavaScript) to the client. Less common in the world of modern SPAs, but it's part of the spec. |
|||
|
|||
## 2. URI Design and Naming Conventions |
|||
|
|||
The URI structure is critical for making your API understandable and intuitive. |
|||
|
|||
### Use Nouns Instead of Verbs |
|||
|
|||
Your URIs should represent things (resources), not actions. The HTTP method already tells you what the action is. |
|||
|
|||
- **Good:** `/api/users` |
|||
|
|||
- **Bad:** `/api/getUsers` |
|||
|
|||
### Use Plural Nouns for Resource Names |
|||
|
|||
Stick with plural nouns for collections. It keeps things consistent, even when you're accessing a single item from that collection. |
|||
|
|||
- **Get all users:** `GET /api/users` |
|||
|
|||
- **Get a single user:** `GET /api/users/{id}` |
|||
|
|||
### Use Nested Routes to Show Relationships |
|||
|
|||
If a resource only exists in the context of another (like a user's orders), reflect that in the URL. |
|||
|
|||
- **Good:** `/api/users/{userId}/orders` (All orders for a user) |
|||
|
|||
- **Bad:** `/api/orders?userId={userId}` |
|||
|
|||
- **Good:** `/api/users/{userId}/orders/{orderId}` (A specific order for a user) |
|||
|
|||
**Note:** Use this structure only if the child resource is tightly coupled to the parent. Avoid nesting deeper than two or three levels, as this can complicate the URIs. |
|||
|
|||
### Path Parameters vs. Query Parameters |
|||
|
|||
Use the correct parameter type based on its function. |
|||
|
|||
- **Path Parameters (`/users/{id}`):** Use these to identify a specific resource or a collection. They are mandatory for the endpoint to resolve. |
|||
|
|||
- *Example:* `GET /api/users/123` uniquely identifies user 123. |
|||
|
|||
- **Query Parameters (`?key=value`):** Use these for optional actions like filtering, sorting, or pagination on a collection. |
|||
|
|||
- *Example:* `GET /api/users?role=admin&sort=lastName` filters the user collection. |
|||
|
|||
### Keep the URL Structure Consistent |
|||
|
|||
- **Use lowercase letters:** Since some systems are case-sensitive, always use lowercase in URIs for consistency. |
|||
|
|||
- *Example:* Use `/api/product-offers` instead of `/api/Product-Offers`. |
|||
|
|||
- **Use special characters correctly:** Use characters like `/`, `?`, and `#` only for their defined purposes. |
|||
|
|||
- *Example:* To get comments for a specific post, use the path `/posts/123/comments`. To filter those comments, use a query parameter: `/posts/123/comments?authorId=45`. |
|||
|
|||
## 3. Correct Usage of HTTP Methods |
|||
|
|||
Each HTTP method has a specific purpose. Sticking to these standards makes your API predictable. |
|||
|
|||
| **HTTP Method** | **Description** | **Idempotent*** | **Safe**** | |
|||
| --------------- | --------------------------------------------------------------------------- | --------------- | ---------- | |
|||
| **GET** | Retrieves a resource or a collection of resources. | Yes | Yes | |
|||
| **POST** | Creates a new resource. | No | No | |
|||
| **PUT** | Updates an existing resource completely or creates it if it does not exist. | Yes | No | |
|||
| **PATCH** | Partially updates an existing resource. | No | No | |
|||
| **DELETE** | Deletes a resource. | Yes | No | |
|||
|
|||
- **Idempotent:** Doing it once has the same effect as doing it 100 times. Deleting a user is idempotent; once it's gone, it's gone. |
|||
|
|||
- **Safe:** The request doesn't change anything on the server. GET is safe. |
|||
|
|||
**Example in practice:** |
|||
|
|||
Let's consider a resource endpoint for a collection of articles: `/api/articles`. |
|||
|
|||
- **`GET /api/articles`**: Retrieves a list of all articles. |
|||
|
|||
- **`GET /api/articles/123`**: Retrieves the specific article with ID 123. |
|||
|
|||
- **`POST /api/articles`**: Creates a new article. The data for the new article is sent in the request body. |
|||
|
|||
- **`PUT /api/articles/123`**: Replaces the entire article with ID 123 using the new data sent in the request body. |
|||
|
|||
- **`PATCH /api/articles/123`**: Partially updates the article with ID 123. For example, you could send only the `{"title": "New Title"}` in the request body to update just the title. |
|||
|
|||
- **`DELETE /api/articles/123`**: Deletes the article with ID 123. |
|||
|
|||
## 4. Data Exchange and Responses |
|||
|
|||
### Prefer the JSON Format |
|||
|
|||
It's the standard. It's lightweight, human-readable, and every language can parse it easily. Send and receive your data as JSON. |
|||
|
|||
- *Example Request Body:* |
|||
|
|||
``` |
|||
{ |
|||
"title": "Best Practices for APIs", |
|||
"authorId": 5, |
|||
"content": "An article about designing great APIs..." |
|||
} |
|||
``` |
|||
|
|||
### Use Appropriate HTTP Status Codes |
|||
|
|||
Use standard HTTP status codes to provide clear information to the client about the outcome of their request. |
|||
|
|||
- **2xx (Success):** |
|||
|
|||
- `200 OK`: The request was successful. (For GET, PUT, PATCH) |
|||
|
|||
- `201 Created`: The resource was successfully created. (For POST) The response should include a `Location` header with the URI of the new resource. |
|||
|
|||
- *Example:* `POST /api/articles` responds with `201 Created` and the header `Location: /api/articles/124`. |
|||
|
|||
- `204 No Content`: The request was successful, but there is no response body. (For DELETE) |
|||
|
|||
- **4xx (Client Error):** |
|||
|
|||
- `400 Bad Request`: Invalid request (e.g., missing or incorrect data). |
|||
|
|||
- `401 Unauthorized`: Authentication is required. |
|||
|
|||
- `403 Forbidden`: No permission. |
|||
|
|||
- `404 Not Found`: The requested resource could not be found. |
|||
|
|||
- **5xx (Server Error):** |
|||
|
|||
- `500 Internal Server Error`: An unexpected error occurred on the server. |
|||
|
|||
### Provide Clear and Consistent Error Responses |
|||
|
|||
When something goes wrong, give back a useful JSON error message. Your future self and any developer using your API will thank you. |
|||
|
|||
- *Example of a detailed error response:* |
|||
|
|||
``` |
|||
{ |
|||
"type": "[https://---.com/probs/validation-error](https://example.com/probs/validation-error)", |
|||
"title": "Your request parameters didn't validate.", |
|||
"status": 400, |
|||
"detail": "The 'email' field must be a valid email address.", |
|||
"instance": "/api/users" |
|||
} |
|||
``` |
|||
|
|||
## 5. Performance Optimization |
|||
|
|||
Optimizing API performance is crucial for providing a good user experience and ensuring the scalability of your service. Key strategies include caching, efficient data retrieval, and controlling traffic. |
|||
|
|||
### Caching |
|||
|
|||
Caching is one of the most effective ways to improve performance. By storing and reusing frequently accessed data, you can significantly reduce latency and server load. |
|||
|
|||
- **How it works:** Caching can be implemented at various levels (client-side, CDN, server-side). REST APIs can facilitate this by using standard HTTP caching headers. |
|||
|
|||
- **Key Headers:** |
|||
|
|||
- `Cache-Control`: Tells the client how long to cache something (e.g., `public, max-age=600`). |
|||
|
|||
- `ETag`: A unique version identifier for a resource. The client can send this back in an `If-None-Match` header. If the data hasn't changed, you can just return `304 Not Modified` with an empty body, saving bandwidth. |
|||
|
|||
- `Last-Modified`: Indicates when the resource was last changed. Similar to `ETag`, it can be used for conditional requests with the `If-Modified-Since` header. |
|||
|
|||
- *Example Response Header for Caching:* |
|||
|
|||
``` |
|||
Cache-Control: public, max-age=600 |
|||
ETag: "x234dff" |
|||
``` |
|||
|
|||
### Filtering, Sorting, and Pagination |
|||
|
|||
For endpoints that return lists of resources, it's inefficient to return the entire dataset at once, especially if it's large. Implementing these features gives clients more control over the data they receive. |
|||
|
|||
- **Filtering:** Allows clients to narrow down the result set based on specific criteria. This reduces the amount of data transferred and makes it easier for the client to find what it needs. |
|||
|
|||
- *Example:* `GET /api/orders?status=shipped&customer_id=123` |
|||
|
|||
- **Sorting:** Enables clients to request the data in a specific order. A common convention is to specify the field to sort by and the direction (ascending or descending). |
|||
|
|||
- *Example:* `GET /api/users?sort=lastName_asc` or `GET /api/products?sort=-price` (the `-` indicates descending order). |
|||
|
|||
- **Pagination:** Breaks down a large result set into smaller, manageable chunks called "pages". This prevents overloading the server and client with massive amounts of data in a single response. |
|||
|
|||
- *Example:* `GET /api/articles?page=2&pageSize=20` (retrieves the second page, with 20 articles per page). |
|||
|
|||
### Rate Limiting |
|||
|
|||
Protect your API from abuse by limiting how many requests a client can make in a given time. If they exceed the limit, return a `429 Too Many Requests`. |
|||
It's also super helpful to return these headers so the client knows what's going on: |
|||
|
|||
- `X-RateLimit-Limit`: Total requests allowed. |
|||
|
|||
- `X-RateLimit-Remaining`: How many requests they have left. |
|||
|
|||
- `Retry-After`: How many seconds they should wait before trying again. |
|||
|
|||
## 6. Security |
|||
|
|||
Security is not an optional feature; it must be a core part of your API design. |
|||
|
|||
- **Always Use HTTPS (TLS):** Encrypt all traffic to prevent man-in-the-middle attacks. There are no exceptions to this rule for production APIs. |
|||
|
|||
- **Authentication & Authorization:** |
|||
|
|||
- **Authentication** (Who are you?): Use a standard like OAuth 2.0 or JWT Bearer Tokens. |
|||
|
|||
- **Authorization** (What are you allowed to do?): Check permissions for every request. Just because a user is logged in doesn't mean they can delete another user's data. |
|||
|
|||
- **Input Validation**: Always validate and sanitize data coming from the client to prevent injection attacks. If the data is bad, reject it with a `400 Bad Request`. |
|||
|
|||
- **Use Security Headers**: Add headers like `Strict-Transport-Security` and `Content-Security-Policy` to add extra layers of browser-level protection. |
|||
|
|||
## 7. API Lifecycle Management |
|||
|
|||
### Versioning |
|||
|
|||
Your API will change. Versioning lets you make breaking changes without messing up existing clients. The most common way is in the URI. |
|||
|
|||
- **URI Versioning (Most Common):** `https://api.example.com/v1/users` |
|||
|
|||
- **Pros:** Simple, explicit, and easy to explore in a browser. |
|||
|
|||
- **Header Versioning:** The client requests a version via a custom HTTP header. |
|||
|
|||
- *Example:* `Accept-Version: v1` |
|||
|
|||
- **Pros:** Keeps the URI clean. |
|||
|
|||
- **Media Type Versioning (Content Negotiation):** The version is included in the `Accept` header. |
|||
|
|||
- *Example:* `Accept: application/vnd.example.v1+json` |
|||
|
|||
- **Pros:** Technically the "purest" REST approach. |
|||
|
|||
### Backward Compatibility & Deprecation |
|||
|
|||
When you release v2, don't just kill v1. Keep it running for a while and communicate a clear shutdown schedule to your users. |
|||
|
|||
### Documentation |
|||
|
|||
An API is only as good as its documentation. Use tools like the **OpenAPI Specification (formerly Swagger)** to generate interactive, machine-readable documentation. Good docs should include: |
|||
|
|||
- Authentication instructions. |
|||
|
|||
- Clear explanations of each endpoint. |
|||
|
|||
- Request/response examples. |
|||
|
|||
- Error code definitions. |
|||
|
|||
## 8. Monitoring and Testing |
|||
|
|||
### Monitoring and Logging |
|||
|
|||
To ensure your API is reliable, you must monitor its health and log important events. |
|||
|
|||
- **Structured Logging:** Log in a machine-readable format like JSON. Include a `correlationId` to track a single request across multiple services. |
|||
|
|||
- **Monitoring:** Track key metrics like latency (response time), error rate, and requests per second. Use tools like Prometheus, Grafana, or Datadog to visualize these metrics and set up alerts. |
|||
|
|||
### API Testing |
|||
|
|||
Thorough testing is essential to prevent bugs and regressions. |
|||
|
|||
- **Unit Tests:** Test individual components and business logic in isolation. |
|||
|
|||
- **Integration Tests:** Test the interaction between different parts of your API, including the database. |
|||
|
|||
- **Contract Tests:** Verify that your API adheres to its documented contract (e.g., the OpenAPI spec). |
|||
|
|||
## 9. Advanced Level: HATEOAS |
|||
|
|||
**HATEOAS (Hypermedia as the Engine of Application State)** is a REST principle that allows your API to be self-documenting and more discoverable. It involves including hyperlinks in responses for actions that can be performed on the relevant resource. |
|||
|
|||
For example, a response for a user resource might look like this: |
|||
|
|||
``` |
|||
{ |
|||
"id": 1, |
|||
"name": "Deo Steel", |
|||
"links": [ |
|||
{ "rel": "self", "href": "/users/1", "method": "GET" }, |
|||
{ "rel": "update", "href": "/users/1", "method": "PUT" }, |
|||
{ "rel": "delete", "href": "/users/1", "method": "DELETE" } |
|||
] |
|||
} |
|||
``` |
|||
|
|||
This way, the client can follow the links in the response to take the next step, rather than manually constructing the URIs. |
|||
|
|||
## 10. A Practical Shortcut: Leveraging Frameworks like ABP.IO |
|||
|
|||
Okay, that was a lot. While it's crucial to understand all these principles, you don't have to build everything from scratch. Modern frameworks can handle a ton of this for you. I work a lot in the .NET space, and **ABP Framework** is a great example of this. |
|||
|
|||
Here’s how it automates many of the things we just talked about: |
|||
|
|||
- **Automatic API Controllers**: You write your business logic in an "Application Service," and ABP automatically creates the REST API endpoints for you, following all the correct naming and HTTP method conventions. (Covers sections 2 & 3). |
|||
|
|||
- **Built-in Best Practices**: |
|||
|
|||
- **Standardized Error Responses**: It has a built-in exception handling system that automatically generates clean, consistent JSON error responses. (Covers section 4). |
|||
|
|||
- **Input Validation**: It has automatic validation for your DTOs. If a request is invalid, it returns a detailed `400 Bad Request` without you writing a single line of code for it. (Covers section 6). |
|||
|
|||
- **Paging, Sorting, Filtering**: You get these out of the box by just using their predefined interfaces. (Covers section 5). |
|||
|
|||
- **Integrated Security**: It comes with a full auth system. You just add an `[Authorize]` attribute to a method, and it handles the rest. It also automatically manages database transactions per API request (Unit of Work) to ensure data consistency. (Covers section 6). |
|||
|
|||
- **Automatic Documentation**: It automatically generates an OpenAPI/Swagger UI for your API, which is a massive help for anyone who needs to use it. (Covers section 7). |
|||
|
|||
Using a framework like this lets you focus on your core business logic, confident that the foundation is built on solid, established best practices. |
|||
|
After Width: | Height: | Size: 759 KiB |
|
After Width: | Height: | Size: 91 KiB |
|
After Width: | Height: | Size: 37 KiB |
|
After Width: | Height: | Size: 48 KiB |
|
After Width: | Height: | Size: 38 KiB |
@ -0,0 +1,157 @@ |
|||
# High-Performance .NET Libraries You Didn’t Know You Needed |
|||
|
|||
Whether you’re building enterprise apps, microservices, or SaaS platforms, using the right libraries can help you ship faster and scale effortlessly. |
|||
Here are some **high-performance .NET libraries** you might not know but definitely should. |
|||
|
|||
|
|||
|
|||
## 1. BenchmarkDotNet – Measure before you optimize |
|||
|
|||
 |
|||
|
|||
BenchmarkDotNet makes it simple to **benchmark .NET code with precision**. |
|||
|
|||
- Easy setup with `[Benchmark]` attributes |
|||
- Generates detailed performance reports |
|||
- Works with .NET Core, .NET Framework, and Mono |
|||
|
|||
Perfect for spotting bottlenecks in APIs, background services, or CPU-bound operations. |
|||
|
|||
- **NuGet** (40M downloads) 🔗 https://www.nuget.org/packages/BenchmarkDotNet |
|||
- **GitHub** (11k stars) 🔗 https://github.com/dotnet/BenchmarkDotNet |
|||
|
|||
|
|||
|
|||
## 2. MessagePack – Fastest JSON serializer |
|||
|
|||
Need speed beyond System.Text.Json or Newtonsoft.Json? MessagePack is the fastest serializer for C# (.NET, .NET Core, Unity, Xamarin). MessagePack has a compact binary size and a full set of general-purpose expressive data types. Ideal for high-traffic APIs, IoT data processing, and microservices. |
|||
|
|||
 |
|||
|
|||
- **NuGet** (204M downloads) 🔗 https://www.nuget.org/packages/messagepack |
|||
- **GitHub** (6.4K stars) 🔗 https://github.com/MessagePack-CSharp/MessagePack-CSharp |
|||
|
|||
|
|||
|
|||
## 3. Polly – Resilience at scale |
|||
|
|||
 |
|||
|
|||
In distributed systems, failures are inevitable. **Polly** provides a fluent way to add **retry, circuit-breaker, and fallback** strategies. |
|||
|
|||
- Handle transient faults gracefully |
|||
- Improve uptime and user experience |
|||
- Works seamlessly with HttpClient and gRPC |
|||
|
|||
A must-have for cloud-native .NET applications. |
|||
|
|||
- **NuGet** (1B downloads) 🔗 https://www.nuget.org/packages/polly/ |
|||
- **GitHub** (14K stars) 🔗 https://github.com/App-vNext/Polly |
|||
|
|||
|
|||
|
|||
## 4. MemoryPack – Zero-cost binary serialization |
|||
|
|||
If you need **blazing-fast serialization** for in-memory caching or network transport, **MemoryPack** is a game-changer. |
|||
|
|||
- Zero-copy, zero-alloc serialization |
|||
- Perfect for high-performance caching or game servers |
|||
- Strongly typed and version-tolerant |
|||
|
|||
 |
|||
|
|||
Great for real-time multiplayer games, chat apps, or financial systems. |
|||
|
|||
- **NuGet** (5.3M downloads) 🔗 https://www.nuget.org/packages/MemoryPack |
|||
- **GitHub** (4K stars) 🔗 https://github.com/Cysharp/MemoryPack |
|||
|
|||
|
|||
|
|||
## 5. WolverineFx – Ultra-low latency messaging |
|||
|
|||
 |
|||
|
|||
MediatR was one of the best mediator libraries, but now it's a paid library. Wolverine is a toolset for command execution and message handling within .NET applications. The killer feature of Wolverine is its very efficient command execution pipeline that can be used as: |
|||
|
|||
- An [inline "mediator" pipeline](https://wolverinefx.net/tutorials/mediator.html) for executing commands |
|||
- A [local message bus](https://wolverinefx.net/guide/messaging/transports/local.html) for in-application communication |
|||
- A full-fledged [asynchronous messaging framework](https://wolverinefx.net/guide/messaging/introduction.html) for robust communication and interaction between services when used in conjunction with low-level messaging infrastructure tools like RabbitMQ |
|||
- With the [WolverineFx.Http](https://wolverinefx.net/guide/http/) library, Wolverine's execution pipeline can be used directly as an alternative ASP.NET Core Endpoint provider |
|||
|
|||
*image below is from [codecrash.net](https://www.codecrash.net/2024/02/06/Mediatr-versus-Wolverine-performance.html)* |
|||
 |
|||
|
|||
WolverineFx is great for cleanly separating business logic from controllers while unifying in-process mediator patterns with powerful distributed messaging in a single, high-performance .NET library. |
|||
|
|||
- **NuGet** (1.5M downloads) 🔗 https://www.nuget.org/packages/WolverineFx |
|||
- **GitHub** (1.7K stars) 🔗 https://github.com/JasperFx/wolverine |
|||
|
|||
|
|||
## 6. Disruptor-net – Next generation free .NET mediator |
|||
|
|||
The Disruptor is a high-performance inter-thread message passing framework. A lock-free ring buffer for ultra-low latency messaging. |
|||
Features are: |
|||
|
|||
- Zero memory allocation after initial setup (the events are pre-allocated). |
|||
|
|||
- Push-based consumers. |
|||
|
|||
- Optionally lock-free. |
|||
|
|||
- Configurable wait strategies. |
|||
|
|||
 |
|||
|
|||
- **NuGet** (1.2M downloads) 🔗 https://www.nuget.org/packages/Disruptor/ |
|||
- **GitHub** (1.3K stars) 🔗 https://github.com/disruptor-net/Disruptor-net |
|||
|
|||
|
|||
## 7. CliWrap - Running command-line processes |
|||
|
|||
 |
|||
|
|||
CliWrap makes it easy to **run and manage external CLI processes in .NET**. |
|||
|
|||
- Fluent, task-based API for starting commands |
|||
- Streams standard input/output and error in real time |
|||
- Supports cancellation, timeouts, and piping between processes |
|||
|
|||
Ideal for automation, build tools, and integrating external executables. |
|||
|
|||
- **NuGet** (14.1M downloads) 🔗 https://www.nuget.org/packages/CliWrap |
|||
- **GitHub** (4.7K stars) 🔗 https://github.com/Tyrrrz/CliWrap |
|||
|
|||
|
|||
--- |
|||
|
|||
|
|||
## Hidden Libs from the Community |
|||
|
|||
### Sylvan.Csv & **Sep** |
|||
|
|||
- **Sylvan.Csv**: Up to *10× faster* and *100× less memory allocations* than `CsvHelper`, making CSV processing lightning-fast. ([Reddit](https://www.reddit.com/r/csharp/comments/191rwgt/extremely_highperformance_libraries_for_common/?utm_source=chatgpt.com)) |
|||
- **Sep**: Even faster than Sylvan, but trades off some flexibility. Great when performance matters more than API richness. ([Reddit](https://www.reddit.com/r/csharp/comments/191rwgt/extremely_highperformance_libraries_for_common/?utm_source=chatgpt.com)) |
|||
|
|||
### String Parsing: **csFastFloat** |
|||
|
|||
- Parses `float` and `double` around *8–9× faster* than `.Parse` methods—perfect for high-volume parsing tasks. ([Reddit](https://www.reddit.com/r/csharp/comments/191rwgt/extremely_highperformance_libraries_for_common/?utm_source=chatgpt.com)) |
|||
|
|||
### CySharp’s Suite: MemoryPack, MasterMemory, SimdLinq |
|||
|
|||
- **MemoryPack**: One of the fastest serializers available, with low allocations and high throughput. Ideal for Web APIs or microservices. ([Reddit](https://www.reddit.com/r/csharp/comments/191rwgt/extremely_highperformance_libraries_for_common/?utm_source=chatgpt.com)) |
|||
- **MasterMemory**: Designed for databases or config storage. Claims *4,700× faster than SQLite* with zero-allocations per query. ([Reddit](https://www.reddit.com/r/csharp/comments/191rwgt/extremely_highperformance_libraries_for_common/?utm_source=chatgpt.com)) |
|||
- **SimdLinq**: SIMD-accelerated LINQ operations supporting a broader set of methods than .NET's built-in SIMD. Works when slight floating-point differences are acceptable. ([Reddit](https://www.reddit.com/r/csharp/comments/191rwgt/extremely_highperformance_libraries_for_common/?utm_source=chatgpt.com)) |
|||
|
|||
### Jil – JSON Deserializer |
|||
|
|||
- Ultra-fast JSON (de)serializer with low memory overhead, used in high-scale systems. ([Performance is a Feature!](https://www.mattwarren.org/2014/09/05/stack-overflow-performance-lessons-part-2/?utm_source=chatgpt.com)) |
|||
|
|||
### StackExchange.NetGain – WebSocket Efficiency |
|||
|
|||
- High-performance WebSocket server library designed for low-latency IO scenarios. (Now mostly replaced by Kestrel's built-in support, but worth knowing.) ([GitHub](https://github.com/StackExchange/NetGain?utm_source=chatgpt.com)) |
|||
|
|||
### Math Libraries: Math.NET Numerics & ILNumerics |
|||
|
|||
- **Math.NET Numerics**: Core numerical methods and matrix math, similar to BLAS/LAPACK. ([Wikipedia](https://en.wikipedia.org/wiki/Math.NET_Numerics?utm_source=chatgpt.com)) |
|||
- **ILNumerics**: Efficient numerical arrays with parallelized processing, loop unrolling and cache optimizations. Great for scientific computing. ([Wikipedia](https://en.wikipedia.org/wiki/ILNumerics?utm_source=chatgpt.com)) |
|||
|
|||
|
After Width: | Height: | Size: 46 KiB |
|
After Width: | Height: | Size: 568 KiB |
|
After Width: | Height: | Size: 263 KiB |
|
After Width: | Height: | Size: 167 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 545 KiB |
|
After Width: | Height: | Size: 8.6 KiB |
|
After Width: | Height: | Size: 85 KiB |
|
After Width: | Height: | Size: 114 KiB |
|
After Width: | Height: | Size: 85 KiB |
|
After Width: | Height: | Size: 137 KiB |
|
After Width: | Height: | Size: 77 KiB |
|
After Width: | Height: | Size: 336 KiB |
@ -0,0 +1,282 @@ |
|||
# Web Design Basics for Graphic Designers Who Don't Code |
|||
|
|||
## Introduction |
|||
|
|||
As a **designer**, I have been working on **logos**, **posters**, and **social media announcement** **visuals** for years. However, when it comes to the web, I used to hold back saying “I **don’t know how to code**.” We have all thought about this at some point and unfortunately, we still think about it from time to time. |
|||
|
|||
🚀 **Good news**: We can learn **web design** without writing code and design **user-friendly**, **aesthetic, and functional web interfaces** using basic knowledge. |
|||
|
|||
In this article, we will talk about the **basics of web design**, its **differences from graphic design**, and whether it is possible to do **web design without knowing how to code**. |
|||
|
|||
## Differences Between Graphic Design & Web Design |
|||
|
|||
 |
|||
|
|||
### What is Graphic Design? |
|||
|
|||
Graphic design is creating **visual content** that conveys a message to a **specific audience**. Graphic designers use various **visual elements** such as **color**, **typography**, **imagery**, and **layout** to communicate a message effectively. They work on a wide range of projects, including **logos**, **websites**, **packaging**, **advertisements, and branding**. |
|||
|
|||
### What is Web Design? |
|||
|
|||
Web design is the process of creating a website that can be viewed on computers or mobile devices. Like graphic design, web design also involves creating **graphics**, **typography**, **and visuals**, but they use the **internet** as the communication channel. |
|||
|
|||
### Graphic Design |
|||
|
|||
* Graphic Design is concerned with **visuals** and **appearance**. |
|||
* Graphic design focuses on visually conveying specific messages or ideas through **typography**, **visuals**, **colors**, and i**llustrations**. |
|||
* Graphic design focuses on how objects **look**. |
|||
* Graphic designers **do not need coding knowledge**. |
|||
* Graphic design is **static**. |
|||
|
|||
### Web Design |
|||
|
|||
* Web design is user experience–focused. |
|||
* Web design aims to create **functional** and **user-friendly** **websites** that provide the **best experience** for users. |
|||
* Web design considers **search engine optimization** when creating websites. |
|||
* Web designers need to have **knowledge of HTML**, **CSS**, and other web development languages to create **functional and responsive designs**. |
|||
* Web design is **dynamic**. |
|||
|
|||
## Fundamental Principles of Web Design (Applicable Without Coding) |
|||
|
|||
Companies and **brands** from almost every sector request the **creation of their own websites**. This way, they gain the opportunity to introduce their **services**, **prices**, and themselves to their **target audiences**. However, for this to have the desired effect, the website must be **designed properly**. What are the **fundamental principles** to pay attention to when designing a website? Now, it’s time to answer this question by introducing the basics. Here are the **indispensable principles in web design**. |
|||
|
|||
### 1\) User-Centered Designs: |
|||
|
|||
Users always value **ease and practicality** when receiving a service. For this reason, it is important for websites to be designed in a user-centered way. **Easy to find menus**, **fast usage**, and the **easy to locate any information** are very important. With **user centered design**, it is possible to create websites that are **easy to use** and also **satisfy users**. |
|||
|
|||
|
|||
### 2\) Responsive Designs: |
|||
|
|||
It is very important for the website and its design to be **usable on every digital platform**. Therefore, the designed sites must have a **responsive design**. This means easy access to the site on a **phone**, **tablet**, or **computer**. This also ensures that users continue to prefer the site. |
|||
|
|||
### 3\) Visual Hierarchy: |
|||
|
|||
The page must have **visuals related to itself**, and **product content** should be matched with the **correct visuals**. It is also very important for visual elements to be placed according to their order of importance. On web pages, content compatible with visuals must be provided with **sufficient and accurate information**. |
|||
|
|||
### 4\) Color and Typography Selection: |
|||
|
|||
Color and typography selection is very important for handling visuals, colors, and text in a certain **harmony**. For the site to **attract attention** or for the relevant pages to achieve the expected interaction, the use of color and the chosen font style and font color must be harmonious. A design that is both **easy to read** and **eye catching** without causing any disturbance should be preferred. |
|||
|
|||
### 5\) Content and Layout Structure: |
|||
|
|||
One of the most desired features on web pages is **content organization**. Content that is **unrelated to the pages, creates confusion while reading**, or **lacks simplicity**, such as overly frequent paragraphs, incorrect fonts, and similar factors, causes web pages to have less impact. **Content structure** also includes **placing related topics sequentially** and **adding them to the menu**. For example, on a website created for shoes, if shoe types are grouped separately, users find it easier. Options like high heels, sandals, and sneakers help users find what they are looking for more easily, which in turn ensures positive site feedback. |
|||
|
|||
### 6\) Speed Optimization: |
|||
|
|||
As with every type of service, speed is very important for services provided through web pages. Easy navigation between pages, error-free performance, and ease of use are very important for users. No one wants to shop or use a service on a website that takes a long time to load, because everyone prefers websites to save time. |
|||
|
|||
### 7\) Consistency: |
|||
|
|||
For a service to be preferred, it must first be reliable. This is directly related to the information, visuals, and everything on the website. The information in the content, visuals, and content details must be consistent and should not raise any questions in visitors’ minds. Otherwise, negative feedback can later affect customer preferences and damage the brand image. |
|||
|
|||
## Is It Possible to Do Web Design Without Coding? |
|||
|
|||
In the past, it was not possible to create a website without at least some basic coding knowledge. However, today, almost anyone can build a website. Even if you have not written a **single line of code**. |
|||
|
|||
The biggest helpers for those who want to do **web development without coding** are **No-Code** and **Low-Code** platforms. These tools help users **design websites** without dealing with **technical details**. |
|||
|
|||
Systems like **Wix**, **Webflow**, **Shopify**, and **WordPress** are very common in this area. |
|||
|
|||
 |
|||
|
|||
The web development process on these platforms is carried out through practical methods such as **drag-and-drop**, selecting **ready-made templates**, and filling out forms. |
|||
|
|||
### **No Code** |
|||
|
|||
As the name suggests, it allows you to create websites, mobile applications, automations, and workflows **without writing a single line of code**. |
|||
|
|||
* **How Does It Work**? They usually have a visual editor. You create the skeleton of your application by dragging and dropping ready “building blocks” such as buttons, forms, and visuals onto your canvas. Then, you determine what these elements will do (for example, “go to this page when this button is clicked”) by selecting options from the menus. |
|||
* **Who Uses It**? It is perfect for entrepreneurs, marketers, product managers, designers, and anyone who wants to quickly test an idea. |
|||
* **Examples**: Platforms like Webflow, Bubble, Adalo, and Glide allow you to create a wide range of products, from complex web applications to mobile apps. |
|||
|
|||
### **Low Code** |
|||
|
|||
Low-Code systems require a bit more **technical knowledge** but still **do not require learning full-scale programming**. |
|||
|
|||
* **How Does It Work**? You handle 80% of the work with drag-and-drop, and for the remaining 20% that requires customization, you add small code snippets. |
|||
* **Who Uses It**? It is generally preferred by IT departments of corporate companies and technical teams that want to develop more complex, scalable applications. |
|||
* **Examples**: Platforms like OutSystems and Mendix are used to build large, integrated systems that manage a company’s internal processes. |
|||
|
|||
## What Should the Web Design Process be Like? |
|||
|
|||
 |
|||
|
|||
**Web design** is a passionate field but can be **overwhelming** at times. When starting out, coming up with a plan on how to tackle your website or a web app idea often feels daunting: Where should you begin?Web designers often think about the **web design process** with a focus on **technical matters** such as wireframes, code, and content management. But great |
|||
|
|||
design isn’t about how you integrate the social media buttons or even slick visuals. **Great design** is actually about having **a website creation process** that aligns with an **overarching strategy.** |
|||
|
|||
Doing all the thinking beforehand ensures that you don’t forget anything crucial. It also frees up headspace for doing the actual work, avoids overwhelm, improves efficiency, and allows you to build better websites on repeat. |
|||
|
|||
But how do you achieve that harmonious synthesis of elements? Through a **holistic web design** process that takes both **form and function** into account. |
|||
|
|||
We have already covered the fundamentals, now, I'll share the steps to an **effective web design process.** |
|||
|
|||
Let's get started. |
|||
|
|||
### 1\) Goal Identification |
|||
|
|||
In this **initial stage**, the designer needs to identify the end goal of the website design, usually in close collaboration with the client or other stakeholders. Questions to explore and answer in this stage of the design and website development process include: |
|||
|
|||
* Who is the site for? |
|||
* What do they hope to find or do there? |
|||
* Is the main purpose of this website to inform, to sell (e-commerce, for everyone?), or to entertain? |
|||
* Does the website need to clearly convey the **brand's core message**, or is it part of a broader **brand strategy** with its own unique focus? |
|||
* If there are any, which **competitor sites** exist, and how should this site be **inspired by them** / how should it differ from them? |
|||
|
|||
To have clear answers to above questions will lead to the **successful execution** of the project. |
|||
|
|||
### What Purpose Will the Website Serve? |
|||
|
|||
Whatever the project you’re taking on, you always want each and every initiative you take to achieve the goals you’ve set for it. **Goal setting is critical** because it will be key in making decisions throughout the project by asking yourself the right questions and **prioritizing tasks and efforts**. |
|||
|
|||
As basic as it may seem, following the **SMART framework** is always a great idea when setting your goals, to **ensure effectiveness:** |
|||
|
|||
**S \- SPECIFIC** |
|||
Your goal is direct, detailed, and meaningful. |
|||
|
|||
**M \- MEASURABLE** |
|||
Your goal is quantifiable to track progress or success. |
|||
|
|||
**A \- ATTAINABLE** |
|||
Your goal is realistic and you have the tools and/or resources to attain it. |
|||
|
|||
**R \- RELEVANT** |
|||
Your goal aligns with your company mission. |
|||
|
|||
**T \- TIME-BASED** |
|||
Your goal has a deadline. |
|||
|
|||
### 2\) Scope Definition |
|||
|
|||
This is easier said than done when starting out, so it is best to approach it with caution : Everyone has once been guilty of saying a project “will be done by next week” before realizing they dramatically **underestimated** how hard it would be. |
|||
|
|||
Nevertheless, **setting** a timeline will help a lot with **accountability**, both internal and external, and will help **break down the project in distinct stages**. |
|||
|
|||
You don’t have to reinvent anything from scratch, as a lot of tools such as Airtable’s timeline view will help you put the timeline together. |
|||
|
|||
 |
|||
|
|||
Source: [Airtable](https://blog.airtable.com/introducing-airtables-new-timeline-view/) |
|||
|
|||
### 3\) Sitemap and Wireframe Creation |
|||
|
|||
The site map forms the foundation of a well-designed website. It gives web designers a clear idea of the **information architecture** of the website and explains the **relationships** between various **pages and content elements**. |
|||
|
|||
 |
|||
|
|||
Building a web site without a site map is like building a house without a plan. And it rarely ends well. |
|||
|
|||
Time to start building the first iteration of your project\! To put it shortly, **wireframes** serve as a blueprint, a visual guide representing the skeletal framework of a website or application. It will be a raw version of your project, a great way to get your **initial idea down** in its first “physical” form. |
|||
|
|||
 |
|||
|
|||
Source: [Afolayan Daniel](https://medium.com/fbdevclagos/4-reasons-why-wire-frame-is-important-during-website-or-mobile-app-development-46fabdf47190) |
|||
|
|||
While it won’t be functional yet, it’ll be a major web design step to share with your team, potential leads or even investors, and will highlight issues that you might not have thought about previously. Wireframes are a great opportunity to move fast, once they’re ready, you’ll be able to: |
|||
|
|||
* Gather early feedback; |
|||
* Run UX testing groups; |
|||
* Iterate on your timeline if necessary; |
|||
* Get concept validation. |
|||
|
|||
There are different ways to create wireframes. You can of course sketch them out on paper to start with, but creating a digital version will eventually be much more practical to share them. |
|||
|
|||
#### Tools for sitemapping and wireframing; |
|||
|
|||
* Pen/pencil and paper. |
|||
* Balsamiq. |
|||
* Moqups. |
|||
* Sketch. |
|||
* Axure. |
|||
* Webflow. |
|||
* Slickplan. |
|||
* Writemaps. |
|||
* Mindnode. |
|||
* Figma. |
|||
* Sketch. |
|||
|
|||
### 4\) Content Creation |
|||
A website should offer more than just a simple design and attractive graphics. An effective content strategy is essential to capture users’ interest and to make the site stand out in search engines. |
|||
|
|||
 |
|||
When it comes to content, search engine optimization is only |
|||
half of the battle. |
|||
|
|||
There are two main goals that you need to focus on while creating content. |
|||
|
|||
#### **Goal 1 Content encourages engagement and action:** |
|||
|
|||
First of all, content drives readers to take action and encourages them to perform the actions necessary to achieve a site's goals. This is influenced both by the content itself (writing) and by the way it is presented (typography and structural elements). |
|||
|
|||
Boring, lifeless, and lengthy writing rarely holds visitors' attention for long enough. Short, fluent, and engaging content captures them and makes them click through to other pages. Even if your pages need a lot of content (which they often do), properly "breaking it up" into short paragraphs supported by visuals can help create a light and engaging feel. |
|||
|
|||
#### **Goal 2 Search Engine Optimization**: |
|||
|
|||
Content also increases a site's visibility in the eyes of search engines. The practice of creating and developing content to achieve a good ranking in search results is called search engine optimization or SEO. |
|||
|
|||
Identifying your keywords and key phrases correctly is very important for the success of any website. |
|||
|
|||
### 5\) Visual Elements |
|||
|
|||
 |
|||
|
|||
Style Tile: a free style tile / moodboard template built by Mat Vogels. |
|||
|
|||
It is time to create the **visual style** of the site. This part of the design process is usually shaped by **existing brand elements, color choices**, and **logos** specified by the client. However, it is also the stage of the web design process where a **good web designer can truly shine**. |
|||
|
|||
**Visuals play a more important** **role** in web design than ever before. High quality visuals not only give a website a professional look and feel, but also convey a message, are mobile friendly, and help build trust. |
|||
|
|||
**Visual design is a way of communicating** with the web site users to make the site as **appealing to them** as possible. When done right, it can determine the site’s being one of the major successes amongst competitors. On the other hand, any mistake might put it in risk of becoming just another ordinary web site. |
|||
|
|||
**Tools for visual elements**: |
|||
|
|||
* (Sketch, Illustrator, Photoshop, Figma, vb.) |
|||
* Visual Style Guides. |
|||
|
|||
|
|||
|
|||
### 6\) Development & Platforms |
|||
|
|||
**Front-End Development**: The parts that users interact with (HTML, CSS, JavaScript). |
|||
|
|||
**Back-End Developmen**t: Database and server-side processes (PHP, Python, Node.js). |
|||
|
|||
**No-Code Platforms**: Publishing on platforms like Webflow, Bubble, Adalo, Glide. |
|||
|
|||
### 7\) Testing |
|||
|
|||
When your site has all the visuals and content, you are ready to test. |
|||
Once the **first iteration** of your website/web app is ready, it’s time for some **testing** to make sure it **runs smoothly**. |
|||
|
|||
A website should undergo a detailed testing process before going live. |
|||
Items to check during the testing process: |
|||
|
|||
* Mobile Compatibility. |
|||
* Functionality across different browsers. |
|||
* Functionality of forms and buttons. |
|||
|
|||
Alongside these steps, setting up website uptime monitoring is essential to ensure the site remains functional after launch, providing immediate alerts if any downtime occurs. Ultimately, while testing is an important part of the web design process, it’s not worth losing sleep over. **Done is always better than perfect** and when in doubt, keep this quote in mind. |
|||
|
|||
*“If you are not embarrassed by the first version of your product, you've launched too late.” \- Reid Hoffman, founder of LinkedIn* |
|||
|
|||
### 8\) Website Launch |
|||
|
|||
Now it’s time for everyone’s favorite part of the website design process: When everything has been thoroughly tested and you’re happy with the site, you can start. |
|||
|
|||
Don’t expect this to go perfectly. There may still be some elements that need fixing. Web design is a fluid and ongoing process that requires constant maintenance. |
|||
|
|||
Web design and design in general is about finding the right balance between form and function. You need to use the right fonts, colors, and design motifs. But the way users navigate and experience your site is just as important. |
|||
|
|||
## Conclusion |
|||
|
|||
Previously, when we wanted to turn our designs into reality, the barrier of learning and using a programming language tool stood in our way. This barrier has now been removed thanks to **No-Code tools**. With these tools, even without coding knowledge, there is now a way to bring your designs to life. |
|||
|
|||
## Resources |
|||
|
|||
* Bulut, B. (2025, July 20). *Kod yazmayı bilmeden yazılımcı olmak nasıl mümkün oldu?* Webtekno. [https://www.webtekno.com/kod-bilmeden-yazilimci-olmak-nasil-mumkun-oldu-h159799.html](https://www.webtekno.com/kod-bilmeden-yazilimci-olmak-nasil-mumkun-oldu-h159799.html) |
|||
|
|||
* Ectasarim. (2024, Kasım 10). *Web tasarım ilkeleri nelerdir? Önemli hususlar*. [https://www.ectasarim.com/web-tasarim-ilkeleri/](https://www.ectasarim.com/web-tasarim-ilkeleri/?utm_source=chatgpt.com) |
|||
|
|||
* Meazey, M. (2020, February 12). *The web design process in 7 simple steps*. *Webflow Blog*. [https://webflow.com/blog/the-web-design-process-in-7-simple-steps](https://webflow.com/blog/the-web-design-process-in-7-simple-steps) |
|||
|
|||
* University of California Office of the President. (2016). *How to write SMART goals: A how-to guide.* University of California. [https://www.ucop.edu/local-human-resources/\_files/performance-appraisal/How+to+write+SMART+Goals+v2.pdf](https://www.ucop.edu/local-human-resources/_files/performance-appraisal/How+to+write+SMART+Goals+v2.pdf) |
|||
@ -0,0 +1,803 @@ |
|||
# Step-by-Step AWS Secrets Manager Integration in ABP Framework Projects |
|||
|
|||
## Introduction |
|||
In this article, we are going to discuss how to secure sensitive data in ABP Framework projects using AWS Secrets Manager and explain various aspects and concepts of _secret_ data management. We will explain step-by-step AWS Secrets Manager integration. |
|||
|
|||
|
|||
## What is the Problem? |
|||
Modern applications must store sensitive data such as API keys, database connection strings, OAuth client credentials, and other similar sensitive data. These are at the center of functionality but if stored in the wrong place can be massive security issues. |
|||
|
|||
At build time, the first place that comes to mind is usually **appsettings.json**. This is a configuration file; it is not a secure place to store secret information, especially in production. |
|||
|
|||
### Common Security Risks: |
|||
- **Plain text storage**: Plain text storage of passwords |
|||
- **Exposure to version control**: Secrets are rendered encrypted in Git repositories |
|||
- **No access control**: Anyone who has file access can see the secrets |
|||
- **No rotation**: We must change them manually |
|||
- **No audit trail**: Who accessed which secret when is not known |
|||
|
|||
## .NET User Secrets Tool vs AWS Secrets Manager |
|||
|
|||
**User Secrets (.NET Secret Manager Tools)** is a dev environment only, local file-based solution that keeps sensitive information out of the repository. |
|||
|
|||
**AWS Secrets Manager** is production. It's a centralized, encrypted, and audited secret management service. |
|||
|
|||
| Feature | User Secrets (Dev) | AWS Secrets Manager (Prod) | |
|||
| ---------------------- | ---------------------------- | ------------------------------ | |
|||
| Scope | Local developer machine | All environments (dev/stage/prod) | |
|||
| Storage | JSON in user profile | Managed service (centralized) | |
|||
| Encryption | None (plain text file) | Encrypted with KMS | |
|||
| Access Control | OS file permissions | IAM policies | |
|||
| Rotation | None | Yes (automatic) | |
|||
| Audit / Traceability | None | Yes (CloudTrail) | |
|||
| Typical Usage | Quick dev outside repo | Production secret management | |
|||
|
|||
--- |
|||
|
|||
## AWS Secrets Manager |
|||
Especially designed to securely store and handle sensitive and confidential data for our applications. It even supports features such as secret rotation, replication, and many more. |
|||
|
|||
AWS Secrets Manager offers a trial of 30 days. After that, there is a $0.40 USD/month charge per stored secret. There is also a $0.05 USD fee per 10,000 API requests. |
|||
|
|||
### Key Features: |
|||
- **Automatic encryption**: KMS automatic encryption |
|||
- **Automatic rotation**: Scheduled secret rotation |
|||
- **Fine-grained access control**: IAM fine-grained access control |
|||
- **Audit logging**: Full audit logging with CloudTrail |
|||
- **Cross-region replication**: Cross-region replication |
|||
- **API integration**: Programmatic access support |
|||
|
|||
--- |
|||
|
|||
## Step 1: AWS Secrets Manager Setup |
|||
|
|||
### 1.1 Creating a Secret in AWS Console |
|||
First, search for the Secrets Manager service in the AWS Management Console. |
|||
|
|||
1. **AWS Console** → **Secrets Manager** → **Store a new secret** |
|||
2. Select **Secret type**: |
|||
- **Other type of secret** (For custom key-value pairs) |
|||
- **Credentials for RDS database** (For databases) |
|||
- **Credentials for DocumentDB database** |
|||
- **Credentials for Redshift cluster** |
|||
|
|||
|
|||
|
|||
3. Enter **Secret value**: |
|||
```json |
|||
{ |
|||
"ConnectionString": "Server=myserver;Database=mydb;User Id=myuser;Password=mypassword;" |
|||
} |
|||
``` |
|||
|
|||
4. Set **Secret name**: `prod/ABPAWSTest/ConnectionString` |
|||
5. Add **Description**: "ABP Framework connection string for production" |
|||
6. Choose **Encryption key** (default KMS key is sufficient) |
|||
7. Configure **Automatic rotation** settings (optional) |
|||
|
|||
### 1.2 IAM Permissions |
|||
Create an IAM policy for secret access: |
|||
|
|||
```json |
|||
{ |
|||
"Version": "2012-10-17", |
|||
"Statement": [ |
|||
{ |
|||
"Effect": "Allow", |
|||
"Action": [ |
|||
"secretsmanager:GetSecretValue", |
|||
"secretsmanager:DescribeSecret" |
|||
], |
|||
"Resource": "arn:aws:secretsmanager:eu-north-1:588118819172:secret:prod/ABPAWSTest/ConnectionString-*" |
|||
} |
|||
] |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Step 2: ABP Framework Project Setup |
|||
|
|||
### 2.1 NuGet Packages |
|||
Add the required AWS packages to your project: |
|||
|
|||
```bash |
|||
dotnet add package AWSSDK.SecretsManager |
|||
dotnet add package AWSSDK.Extensions.NETCore.Setup |
|||
``` |
|||
|
|||
### 2.2 Configuration Files |
|||
|
|||
**appsettings.json** (Development): |
|||
```json |
|||
{ |
|||
"AWS": { |
|||
"Profile": "default", |
|||
"Region": "eu-north-1", |
|||
"AccessKey": "YOUR_ACCESS_KEY", |
|||
"SecretKey": "YOUR_SECRET_KEY" |
|||
}, |
|||
"SecretsManager": { |
|||
"SecretName": "prod/ABPAWSTest/ConnectionString", |
|||
"SecretArn": "arn:aws:secretsmanager:eu-north-1:588118819172:secret:prod/ABPAWSTest/ConnectionString-xtYQxv" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**appsettings.Production.json** (Production): |
|||
```json |
|||
{ |
|||
"AWS": { |
|||
"Region": "eu-north-1" |
|||
// Use environment variables or IAM roles in production |
|||
}, |
|||
"SecretsManager": { |
|||
"SecretName": "prod/ABPAWSTest/ConnectionString" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 2.3 Environment Variables (Production) |
|||
```bash |
|||
export AWS_ACCESS_KEY_ID=your_access_key |
|||
export AWS_SECRET_ACCESS_KEY=your_secret_key |
|||
export AWS_DEFAULT_REGION=eu-north-1 |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Step 3: AWS Integration Implementation |
|||
|
|||
### 3.1 Program.cs Configuration |
|||
|
|||
```csharp |
|||
using Amazon; |
|||
using Amazon.SecretsManager; |
|||
|
|||
public class Program |
|||
{ |
|||
public async static Task<int> Main(string[] args) |
|||
{ |
|||
var builder = WebApplication.CreateBuilder(args); |
|||
|
|||
// AWS Secrets Manager configuration |
|||
var awsOptions = builder.Configuration.GetAWSOptions(); |
|||
|
|||
// Read AWS credentials from appsettings |
|||
var accessKey = builder.Configuration["AWS:AccessKey"]; |
|||
var secretKey = builder.Configuration["AWS:SecretKey"]; |
|||
var region = builder.Configuration["AWS:Region"]; |
|||
|
|||
if (!string.IsNullOrEmpty(accessKey) && !string.IsNullOrEmpty(secretKey)) |
|||
{ |
|||
awsOptions.Credentials = new Amazon.Runtime.BasicAWSCredentials(accessKey, secretKey); |
|||
} |
|||
|
|||
if (!string.IsNullOrEmpty(region)) |
|||
{ |
|||
awsOptions.Region = RegionEndpoint.GetBySystemName(region); |
|||
} |
|||
|
|||
builder.Services.AddDefaultAWSOptions(awsOptions); |
|||
builder.Services.AddAWSService<IAmazonSecretsManager>(); |
|||
|
|||
// ... ABP configuration |
|||
await builder.AddApplicationAsync<YourAppModule>(); |
|||
var app = builder.Build(); |
|||
|
|||
await app.InitializeApplicationAsync(); |
|||
await app.RunAsync(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 3.2 Secrets Manager Service |
|||
|
|||
**Interface:** |
|||
```csharp |
|||
public interface ISecretsManagerService |
|||
{ |
|||
Task<string> GetSecretAsync(string secretName); |
|||
Task<T> GetSecretAsync<T>(string secretName) where T : class; |
|||
Task<string> GetConnectionStringAsync(); |
|||
} |
|||
``` |
|||
|
|||
**Implementation:** |
|||
```csharp |
|||
using Amazon.SecretsManager; |
|||
using Amazon.SecretsManager.Model; |
|||
using Volo.Abp.DependencyInjection; |
|||
using System.Text.Json; |
|||
|
|||
public class SecretsManagerService : ISecretsManagerService, IScopedDependency |
|||
{ |
|||
private readonly IAmazonSecretsManager _secretsManager; |
|||
private readonly IConfiguration _configuration; |
|||
private readonly ILogger<SecretsManagerService> _logger; |
|||
|
|||
public SecretsManagerService( |
|||
IAmazonSecretsManager secretsManager, |
|||
IConfiguration configuration, |
|||
ILogger<SecretsManagerService> logger) |
|||
{ |
|||
_secretsManager = secretsManager; |
|||
_configuration = configuration; |
|||
_logger = logger; |
|||
} |
|||
|
|||
public async Task<string> GetSecretAsync(string secretName) |
|||
{ |
|||
try |
|||
{ |
|||
var request = new GetSecretValueRequest |
|||
{ |
|||
SecretId = secretName |
|||
}; |
|||
|
|||
var response = await _secretsManager.GetSecretValueAsync(request); |
|||
|
|||
_logger.LogInformation("Successfully retrieved secret: {SecretName}", secretName); |
|||
|
|||
return response.SecretString; |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
_logger.LogError(ex, "Failed to retrieve secret: {SecretName}", secretName); |
|||
throw; |
|||
} |
|||
} |
|||
|
|||
public async Task<T> GetSecretAsync<T>(string secretName) where T : class |
|||
{ |
|||
var secretValue = await GetSecretAsync(secretName); |
|||
|
|||
try |
|||
{ |
|||
return JsonSerializer.Deserialize<T>(secretValue) |
|||
?? throw new InvalidOperationException($"Failed to deserialize secret {secretName}"); |
|||
} |
|||
catch (JsonException ex) |
|||
{ |
|||
_logger.LogError(ex, "Failed to deserialize secret {SecretName}", secretName); |
|||
throw; |
|||
} |
|||
} |
|||
|
|||
public async Task<string> GetConnectionStringAsync() |
|||
{ |
|||
var secretName = _configuration["SecretsManager:SecretName"] |
|||
?? throw new InvalidOperationException("SecretsManager:SecretName configuration is missing"); |
|||
|
|||
return await GetSecretAsync(secretName); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Step 4: Usage Examples |
|||
|
|||
### 4.1 Using in Application Service |
|||
|
|||
```csharp |
|||
[RemoteService(false)] |
|||
public class DatabaseService : ApplicationService |
|||
{ |
|||
private readonly ISecretsManagerService _secretsManager; |
|||
|
|||
public DatabaseService(ISecretsManagerService secretsManager) |
|||
{ |
|||
_secretsManager = secretsManager; |
|||
} |
|||
|
|||
public async Task<string> GetDatabaseConnectionAsync() |
|||
{ |
|||
// Get connection string from AWS Secrets Manager |
|||
var connectionString = await _secretsManager.GetConnectionStringAsync(); |
|||
|
|||
// Use the connection string |
|||
return connectionString; |
|||
} |
|||
|
|||
public async Task<ApiConfiguration> GetApiConfigAsync() |
|||
{ |
|||
// Deserialize JSON secret |
|||
var config = await _secretsManager.GetSecretAsync<ApiConfiguration>("prod/MyApp/ApiConfig"); |
|||
|
|||
return config; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 4.2 DbContext Configuration |
|||
|
|||
```csharp |
|||
public class YourDbContextConfigurer |
|||
{ |
|||
public static void Configure(DbContextOptionsBuilder<YourDbContext> builder, string connectionString) |
|||
{ |
|||
builder.UseSqlServer(connectionString); |
|||
} |
|||
|
|||
public static void Configure(DbContextOptionsBuilder<YourDbContext> builder, DbConnection connection) |
|||
{ |
|||
builder.UseSqlServer(connection); |
|||
} |
|||
} |
|||
|
|||
// Usage in Module |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
var configuration = context.Services.GetConfiguration(); |
|||
var secretsManager = context.Services.GetRequiredService<ISecretsManagerService>(); |
|||
|
|||
// Get secret at startup and pass to DbContext |
|||
var connectionString = await secretsManager.GetConnectionStringAsync(); |
|||
|
|||
context.Services.AddAbpDbContext<YourDbContext>(options => |
|||
{ |
|||
options.AddDefaultRepositories(includeAllEntities: true); |
|||
options.DbContextOptions.UseSqlServer(connectionString); |
|||
}); |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Step 5: Best Practices & Security |
|||
|
|||
### 5.1 Security Best Practices |
|||
|
|||
1. **Environment-based Configuration:** |
|||
- Development: appsettings.json |
|||
- Production: Environment variables or IAM roles |
|||
|
|||
2. **Principle of Least Privilege:** |
|||
```json |
|||
{ |
|||
"Effect": "Allow", |
|||
"Action": "secretsmanager:GetSecretValue", |
|||
"Resource": "arn:aws:secretsmanager:region:account:secret:specific-secret-*" |
|||
} |
|||
``` |
|||
|
|||
3. **Secret Rotation:** |
|||
- Set up automatic rotation |
|||
- Custom rotation logic with Lambda functions |
|||
|
|||
4. **Caching Strategy:** |
|||
```csharp |
|||
public class CachedSecretsManagerService : ISecretsManagerService |
|||
{ |
|||
private readonly IMemoryCache _cache; |
|||
private readonly SecretsManagerService _secretsManager; |
|||
|
|||
public async Task<string> GetSecretAsync(string secretName) |
|||
{ |
|||
var cacheKey = $"secret:{secretName}"; |
|||
|
|||
if (_cache.TryGetValue(cacheKey, out string cachedValue)) |
|||
{ |
|||
return cachedValue; |
|||
} |
|||
|
|||
var value = await _secretsManager.GetSecretAsync(secretName); |
|||
|
|||
_cache.Set(cacheKey, value, TimeSpan.FromMinutes(30)); |
|||
|
|||
return value; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 5.2 Error Handling |
|||
|
|||
```csharp |
|||
public async Task<string> GetSecretWithRetryAsync(string secretName) |
|||
{ |
|||
const int maxRetries = 3; |
|||
var delay = TimeSpan.FromSeconds(1); |
|||
|
|||
for (int i = 0; i < maxRetries; i++) |
|||
{ |
|||
try |
|||
{ |
|||
return await GetSecretAsync(secretName); |
|||
} |
|||
catch (AmazonSecretsManagerException ex) when (i < maxRetries - 1) |
|||
{ |
|||
_logger.LogWarning(ex, "Retry {Attempt} for secret {SecretName}", i + 1, secretName); |
|||
await Task.Delay(delay); |
|||
delay = TimeSpan.FromMilliseconds(delay.TotalMilliseconds * 2); // Exponential backoff |
|||
} |
|||
} |
|||
|
|||
throw new InvalidOperationException($"Failed to retrieve secret {secretName} after {maxRetries} attempts"); |
|||
} |
|||
``` |
|||
|
|||
### 5.3 Performance Optimization |
|||
|
|||
```csharp |
|||
public class PerformantSecretsManagerService : ISecretsManagerService |
|||
{ |
|||
private readonly IAmazonSecretsManager _secretsManager; |
|||
private readonly IMemoryCache _cache; |
|||
private readonly ILogger<PerformantSecretsManagerService> _logger; |
|||
private readonly SemaphoreSlim _semaphore = new(1, 1); |
|||
|
|||
public async Task<string> GetSecretAsync(string secretName) |
|||
{ |
|||
var cacheKey = $"secret:{secretName}"; |
|||
|
|||
// Try to get from cache first |
|||
if (_cache.TryGetValue(cacheKey, out string cachedValue)) |
|||
{ |
|||
return cachedValue; |
|||
} |
|||
|
|||
// Use semaphore to prevent multiple concurrent requests for the same secret |
|||
await _semaphore.WaitAsync(); |
|||
try |
|||
{ |
|||
// Double-check pattern |
|||
if (_cache.TryGetValue(cacheKey, out cachedValue)) |
|||
{ |
|||
return cachedValue; |
|||
} |
|||
|
|||
// Fetch from AWS |
|||
var value = await GetSecretFromAwsAsync(secretName); |
|||
|
|||
// Cache for 30 minutes |
|||
_cache.Set(cacheKey, value, TimeSpan.FromMinutes(30)); |
|||
|
|||
return value; |
|||
} |
|||
finally |
|||
{ |
|||
_semaphore.Release(); |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Step 6: Testing & Debugging |
|||
|
|||
### 6.1 Unit Testing |
|||
|
|||
```csharp |
|||
public class SecretsManagerServiceTests : AbpIntegratedTest<TestModule> |
|||
{ |
|||
private readonly ISecretsManagerService _secretsManager; |
|||
|
|||
public SecretsManagerServiceTests() |
|||
{ |
|||
_secretsManager = GetRequiredService<ISecretsManagerService>(); |
|||
} |
|||
|
|||
[Fact] |
|||
public async Task Should_Get_Connection_String() |
|||
{ |
|||
// Act |
|||
var connectionString = await _secretsManager.GetConnectionStringAsync(); |
|||
|
|||
// Assert |
|||
connectionString.ShouldNotBeNullOrEmpty(); |
|||
connectionString.ShouldContain("Server="); |
|||
} |
|||
|
|||
[Fact] |
|||
public async Task Should_Deserialize_Json_Secret() |
|||
{ |
|||
// Arrange |
|||
var secretName = "test/json/config"; |
|||
|
|||
// Act |
|||
var config = await _secretsManager.GetSecretAsync<TestConfig>(secretName); |
|||
|
|||
// Assert |
|||
config.ShouldNotBeNull(); |
|||
config.ApiKey.ShouldNotBeNullOrEmpty(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 6.2 Mock Implementation for Testing |
|||
|
|||
```csharp |
|||
public class MockSecretsManagerService : ISecretsManagerService, ISingletonDependency |
|||
{ |
|||
private readonly Dictionary<string, string> _secrets = new() |
|||
{ |
|||
["prod/ABPAWSTest/ConnectionString"] = "Server=localhost;Database=TestDb;Trusted_Connection=true;", |
|||
["prod/MyApp/ApiKey"] = "test-api-key", |
|||
["prod/MyApp/Config"] = """{"ApiUrl": "https://api.test.com", "Timeout": 30}""" |
|||
}; |
|||
|
|||
public Task<string> GetSecretAsync(string secretName) |
|||
{ |
|||
if (_secrets.TryGetValue(secretName, out var secret)) |
|||
{ |
|||
return Task.FromResult(secret); |
|||
} |
|||
|
|||
throw new ArgumentException($"Unknown secret: {secretName}"); |
|||
} |
|||
|
|||
public async Task<T> GetSecretAsync<T>(string secretName) where T : class |
|||
{ |
|||
var json = await GetSecretAsync(secretName); |
|||
return JsonSerializer.Deserialize<T>(json) |
|||
?? throw new InvalidOperationException($"Failed to deserialize {secretName}"); |
|||
} |
|||
|
|||
public Task<string> GetConnectionStringAsync() |
|||
{ |
|||
return GetSecretAsync("prod/ABPAWSTest/ConnectionString"); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 6.3 Integration Testing |
|||
|
|||
```csharp |
|||
public class SecretsManagerIntegrationTests : IClassFixture<WebApplicationFactory<Program>> |
|||
{ |
|||
private readonly WebApplicationFactory<Program> _factory; |
|||
private readonly HttpClient _client; |
|||
|
|||
public SecretsManagerIntegrationTests(WebApplicationFactory<Program> factory) |
|||
{ |
|||
_factory = factory; |
|||
_client = _factory.CreateClient(); |
|||
} |
|||
|
|||
[Fact] |
|||
public async Task Should_Connect_To_Database_With_Secret() |
|||
{ |
|||
// Arrange & Act |
|||
var response = await _client.GetAsync("/api/health"); |
|||
|
|||
// Assert |
|||
response.EnsureSuccessStatusCode(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Step 7: Monitoring & Observability |
|||
|
|||
### 7.1 CloudWatch Metrics |
|||
|
|||
```csharp |
|||
public class MonitoredSecretsManagerService : ISecretsManagerService |
|||
{ |
|||
private readonly ISecretsManagerService _inner; |
|||
private readonly IMetrics _metrics; |
|||
private readonly ILogger<MonitoredSecretsManagerService> _logger; |
|||
|
|||
public async Task<string> GetSecretAsync(string secretName) |
|||
{ |
|||
using var activity = Activity.StartActivity("SecretsManager.GetSecret"); |
|||
activity?.SetTag("secret.name", secretName); |
|||
|
|||
var stopwatch = Stopwatch.StartNew(); |
|||
|
|||
try |
|||
{ |
|||
var result = await _inner.GetSecretAsync(secretName); |
|||
|
|||
_metrics.Counter("secrets_manager.requests") |
|||
.WithTag("secret_name", secretName) |
|||
.WithTag("status", "success") |
|||
.Increment(); |
|||
|
|||
_metrics.Timer("secrets_manager.duration") |
|||
.WithTag("secret_name", secretName) |
|||
.Record(stopwatch.ElapsedMilliseconds); |
|||
|
|||
return result; |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
_metrics.Counter("secrets_manager.requests") |
|||
.WithTag("secret_name", secretName) |
|||
.WithTag("status", "error") |
|||
.WithTag("error_type", ex.GetType().Name) |
|||
.Increment(); |
|||
|
|||
_logger.LogError(ex, "Failed to retrieve secret {SecretName}", secretName); |
|||
throw; |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 7.2 Health Checks |
|||
|
|||
```csharp |
|||
public class SecretsManagerHealthCheck : IHealthCheck |
|||
{ |
|||
private readonly IAmazonSecretsManager _secretsManager; |
|||
private readonly ILogger<SecretsManagerHealthCheck> _logger; |
|||
|
|||
public SecretsManagerHealthCheck( |
|||
IAmazonSecretsManager secretsManager, |
|||
ILogger<SecretsManagerHealthCheck> logger) |
|||
{ |
|||
_secretsManager = secretsManager; |
|||
_logger = logger; |
|||
} |
|||
|
|||
public async Task<HealthCheckResult> CheckHealthAsync( |
|||
HealthCheckContext context, |
|||
CancellationToken cancellationToken = default) |
|||
{ |
|||
try |
|||
{ |
|||
// Try to list secrets to verify connection |
|||
var request = new ListSecretsRequest { MaxResults = 1 }; |
|||
await _secretsManager.ListSecretsAsync(request, cancellationToken); |
|||
|
|||
return HealthCheckResult.Healthy("AWS Secrets Manager is accessible"); |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
_logger.LogError(ex, "AWS Secrets Manager health check failed"); |
|||
return HealthCheckResult.Unhealthy("AWS Secrets Manager is not accessible", ex); |
|||
} |
|||
} |
|||
} |
|||
|
|||
// Register in Program.cs |
|||
builder.Services.AddHealthChecks() |
|||
.AddCheck<SecretsManagerHealthCheck>("secrets-manager"); |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Step 8: Advanced Scenarios |
|||
|
|||
### 8.1 Dynamic Configuration Reload |
|||
|
|||
```csharp |
|||
public class DynamicSecretsConfigurationProvider : ConfigurationProvider, IDisposable |
|||
{ |
|||
private readonly ISecretsManagerService _secretsManager; |
|||
private readonly Timer _reloadTimer; |
|||
private readonly string _secretName; |
|||
|
|||
public DynamicSecretsConfigurationProvider( |
|||
ISecretsManagerService secretsManager, |
|||
string secretName) |
|||
{ |
|||
_secretsManager = secretsManager; |
|||
_secretName = secretName; |
|||
|
|||
// Reload every 5 minutes |
|||
_reloadTimer = new Timer(ReloadSecrets, null, TimeSpan.Zero, TimeSpan.FromMinutes(5)); |
|||
} |
|||
|
|||
private async void ReloadSecrets(object state) |
|||
{ |
|||
try |
|||
{ |
|||
var secretValue = await _secretsManager.GetSecretAsync(_secretName); |
|||
var config = JsonSerializer.Deserialize<Dictionary<string, string>>(secretValue); |
|||
|
|||
Data.Clear(); |
|||
foreach (var kvp in config) |
|||
{ |
|||
Data[kvp.Key] = kvp.Value; |
|||
} |
|||
|
|||
OnReload(); |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
// Log error but don't throw to avoid crashing the timer |
|||
Console.WriteLine($"Failed to reload secrets: {ex.Message}"); |
|||
} |
|||
} |
|||
|
|||
public void Dispose() |
|||
{ |
|||
_reloadTimer?.Dispose(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 8.2 Multi-Region Failover |
|||
|
|||
```csharp |
|||
public class MultiRegionSecretsManagerService : ISecretsManagerService |
|||
{ |
|||
private readonly List<IAmazonSecretsManager> _clients; |
|||
private readonly ILogger<MultiRegionSecretsManagerService> _logger; |
|||
|
|||
public MultiRegionSecretsManagerService( |
|||
IConfiguration configuration, |
|||
ILogger<MultiRegionSecretsManagerService> logger) |
|||
{ |
|||
_logger = logger; |
|||
_clients = new List<IAmazonSecretsManager>(); |
|||
|
|||
// Create clients for multiple regions |
|||
var regions = new[] { "us-east-1", "us-west-2", "eu-west-1" }; |
|||
foreach (var region in regions) |
|||
{ |
|||
var config = new AmazonSecretsManagerConfig |
|||
{ |
|||
RegionEndpoint = RegionEndpoint.GetBySystemName(region) |
|||
}; |
|||
_clients.Add(new AmazonSecretsManagerClient(config)); |
|||
} |
|||
} |
|||
|
|||
public async Task<string> GetSecretAsync(string secretName) |
|||
{ |
|||
Exception lastException = null; |
|||
|
|||
foreach (var client in _clients) |
|||
{ |
|||
try |
|||
{ |
|||
var request = new GetSecretValueRequest { SecretId = secretName }; |
|||
var response = await client.GetSecretValueAsync(request); |
|||
|
|||
_logger.LogInformation("Retrieved secret from region {Region}", |
|||
client.Config.RegionEndpoint.SystemName); |
|||
|
|||
return response.SecretString; |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
lastException = ex; |
|||
_logger.LogWarning(ex, "Failed to retrieve secret from region {Region}", |
|||
client.Config.RegionEndpoint.SystemName); |
|||
} |
|||
} |
|||
|
|||
throw new InvalidOperationException( |
|||
"Failed to retrieve secret from all regions", lastException); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## Conclusion |
|||
|
|||
AWS Secrets Manager integration with ABP Framework significantly enhances the security of your applications. With this integration: |
|||
|
|||
**Centralized Secret Management**: All secrets are managed centrally |
|||
**Better Security**: Encryption through KMS and access control through IAM |
|||
**Audit Trail**: Complete recording of who accessed which secret when |
|||
**Automatic Rotation**: Secrets can be rotated automatically |
|||
**High Availability**: AWS high availability guarantee |
|||
**Easy Integration**: Native integration with ABP Framework |
|||
**Cost Effective**: Pay only for what you use |
|||
**Scalable**: Scales with your application needs |
|||
|
|||
With this post, you can securely utilize AWS Secrets Manager in your ABP Framework applications and bid farewell to secret management concerns in production. |
|||
|
|||
### Key Benefits: |
|||
- **Developer Productivity**: No hardcoded secrets in config files |
|||
- **Operational Excellence**: Automation of rotation and monitoring |
|||
- **Security Compliance**: Meet enterprise security requirements |
|||
- **Peace of Mind**: Professional-grade secret management |
|||
|
|||
--- |
|||
|
|||
## Additional Resources |
|||
|
|||
- [AWS Secrets Manager Documentation](https://docs.aws.amazon.com/secretsmanager/) |
|||
- [ABP Framework Documentation](https://docs.abp.io/) |
|||
- [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/) |
|||
- [AWS Security Best Practices](https://aws.amazon.com/architecture/security-identity-compliance/) |
|||
- [Sample Project Repository](https://github.com/fahrigedik/AWSIntegrationABP) |
|||
|
After Width: | Height: | Size: 396 KiB |
@ -0,0 +1,316 @@ |
|||
|
|||
# Demystified Aggregates in DDD & .NET: From Theory to Practice |
|||
|
|||
## Introduction |
|||
|
|||
Domain-Driven Design (DDD) is one of the key foundations of modern software architecture and has taken a strong place in the .NET world. At the center of DDD are Aggregates, which protect the consistency of business rules. While they are one of DDD’s biggest strengths, they’re also one of the most commonly misunderstood ideas. Trying to follow “pure” DDD rules to the letter often clashes with the complexity and performance needs of real-world projects, leaving developers in tough situations. The goal of this article is to take a fresh, practical look at Aggregates and show how they can be applied in a way that works in real life. |
|||
|
|||
---------- |
|||
|
|||
### **Chapter 1: Laying the Groundwork: What Is a Classic Aggregate?** |
|||
|
|||
Before jumping into pragmatic shortcuts, let’s make sure we’re all on the same page. To do that, we’ll start with the classic “by the book” definition of an Aggregate and the rules that make it tick. |
|||
|
|||
#### **What Exactly Is an Aggregate?** |
|||
|
|||
At its simplest, an **Aggregate** is a group of related objects (Entities and Value Objects) that are treated as **one unit of change**. And this group has a leader: the **Aggregate Root**. |
|||
|
|||
- **Aggregate Root** → Think of it as the gatekeeper. All outside commands (like “add a product to the order”) must go through the root. You can’t just poke around and change stuff inside. |
|||
|
|||
- **Entity** → Objects within the Aggregate that have their own identity (ID). Example: an `OrderLine` inside an `Order`. |
|||
|
|||
- **Value Object** → Objects without an identity. They’re defined entirely by their values, like an `Address` or `Money`. |
|||
|
|||
|
|||
The Aggregate’s main purpose isn’t just grouping things together—it’s about **protecting business rules (invariants).** For example: _“an order’s total amount can never be negative.”_ The Aggregate Root makes sure rules like this are never broken. |
|||
|
|||
|
|||
#### **The Role of Aggregates: Transaction Boundaries** |
|||
|
|||
The most important job of an Aggregate is defining the **transactional consistency boundary**. In other words: |
|||
|
|||
👉 Any change you make inside an Aggregate either **fully succeeds** or **fully fails**. There’s no half-done state. |
|||
|
|||
From a database perspective, when you call `SaveChanges()` or `Commit()`, everything within one Aggregate gets saved in a single transaction. If you add a product and update the total price, those two actions are atomic—they succeed together. Thanks to Aggregates, you’ll never end up in weird states like _“product was added but total wasn’t updated.”_ |
|||
|
|||
|
|||
#### **The Golden Rules of Aggregates** |
|||
|
|||
Classic DDD lays out three golden rules for working with Aggregates: |
|||
|
|||
1. **Talk Only to the Root** |
|||
You can’t directly update something like an `OrderLine`. You must go through the root: `Order.AddOrderLine(...)` or `Order.RemoveOrderLine(...)`. That way, the root always enforces the rules. |
|||
|
|||
2. **Reference Other Aggregates by ID Only** |
|||
An `Order` shouldn’t hold a `Customer` object directly. Instead, it should just store `CustomerId`. This keeps Aggregates independent and avoids loading massive object graphs. |
|||
|
|||
3. **Change Only One Aggregate per Transaction** |
|||
Need to create an order _and_ update loyalty points? Classic DDD says: do it in two steps. First, save the `Order`. Then publish a **domain event** to update the `Customer`. This enables scalability but introduces **eventual consistency**. |
|||
|
|||
|
|||
|
|||
#### **A Classic Example: The Order Aggregate in .NET** |
|||
|
|||
Here’s a simple example showing an `Order` Aggregate that enforces a business rule: |
|||
|
|||
```csharp |
|||
// Aggregate Root: The entry point and rule enforcer |
|||
public class Order |
|||
{ |
|||
public Guid Id { get; private set; } |
|||
public Guid CustomerId { get; private set; } |
|||
|
|||
private readonly List<OrderLine> _orderLines = new(); |
|||
public IReadOnlyCollection<OrderLine> OrderLines => _orderLines.AsReadOnly(); |
|||
|
|||
public decimal TotalPrice { get; private set; } |
|||
|
|||
public Order(Guid id, Guid customerId) |
|||
{ |
|||
Id = id; |
|||
CustomerId = customerId; |
|||
} |
|||
|
|||
public void AddOrderLine(Guid productId, int quantity, decimal price) |
|||
{ |
|||
// Rule 1: Max 10 order lines |
|||
if (_orderLines.Count >= 10) |
|||
throw new InvalidOperationException("An order can contain at most 10 products."); |
|||
|
|||
// Rule 2: No duplicate products |
|||
var existingLine = _orderLines.FirstOrDefault(ol => ol.ProductId == productId); |
|||
if (existingLine != null) |
|||
throw new InvalidOperationException("This product is already in the order."); |
|||
|
|||
var orderLine = new OrderLine(productId, quantity, price); |
|||
_orderLines.Add(orderLine); |
|||
|
|||
RecalculateTotalPrice(); |
|||
} |
|||
|
|||
private void RecalculateTotalPrice() |
|||
{ |
|||
TotalPrice = _orderLines.Sum(ol => ol.TotalPrice); |
|||
} |
|||
} |
|||
|
|||
public class OrderLine |
|||
{ |
|||
public Guid Id { get; private set; } |
|||
public Guid ProductId { get; private set; } |
|||
public int Quantity { get; private set; } |
|||
public decimal UnitPrice { get; private set; } |
|||
public decimal TotalPrice => Quantity * UnitPrice; |
|||
|
|||
public OrderLine(Guid productId, int quantity, decimal unitPrice) |
|||
{ |
|||
Id = Guid.NewGuid(); |
|||
ProductId = productId; |
|||
Quantity = quantity; |
|||
UnitPrice = unitPrice; |
|||
} |
|||
} |
|||
|
|||
``` |
|||
|
|||
Here, the `Order` enforces the rule _“an order can have at most 10 items”_ inside its `AddOrderLine` method. Nobody outside the class can bypass this, because `_orderLines` is private. |
|||
|
|||
👉 That’s the real strength of a classic Aggregate: **business rules are always protected at the boundary.** |
|||
|
|||
---------- |
|||
|
|||
### **Chapter 2: Theory in Books vs. Reality in Code — Why Classic Aggregates Struggle** |
|||
|
|||
In Chapter 1, we painted the “ideal” world of DDD. Aggregates were like fortresses guarding our business rules… |
|||
But what happens when we try to build that fortress in a real project with tools like Entity Framework Core? That’s when the gap between theory and practice starts to show up. |
|||
|
|||
#### **1. That `.Include()` Chain — Do We Really Need It? The Performance Trap** |
|||
|
|||
DDD books tell us: _“To validate a business rule, you must load the entire aggregate into memory.”_ |
|||
Sounds reasonable if consistency is the goal. |
|||
|
|||
But let’s picture a scenario: we have an `Order` aggregate with **500 order lines** inside it. And all we want to do is change its status to `Confirmed`. |
|||
|
|||
```csharp |
|||
// Just to update a single field... |
|||
var order = await _context.Orders |
|||
.Include(o => o.OrderLines) // <-- 500 rows pulled in! |
|||
.SingleOrDefaultAsync(o => o.Id == orderId); |
|||
|
|||
order.Confirm(); // Just sets order.Status = "Confirmed"; |
|||
|
|||
await _context.SaveChangesAsync(); |
|||
|
|||
``` |
|||
|
|||
This query pulls **all 500 order lines into memory** just so we can flip a single `Status` field. Even in small projects, this is a silent performance killer. As the system grows, it will drag your app down. |
|||
|
|||
|
|||
#### **2. The Abandoned Fortress — Sliding into Anemic Domain Models** |
|||
|
|||
Now, what’s a developer’s natural reaction to this? Something like: |
|||
|
|||
_“Pulling this much data is expensive. Maybe I should strip down the aggregate into a plain POCO with properties only, and move the logic into an `OrderService` class.”_ |
|||
|
|||
This is how we slip straight into the **Anemic Domain Model** trap. Our classes lose their behavior, becoming nothing more than data bags. |
|||
The whole DDD principle of _“keep behavior close to data”_ evaporates. Business logic leaks out of the aggregate and spreads across services. We think we’re doing DDD, but in reality, we’ve fallen back into classic transaction-script style coding. |
|||
|
|||
|
|||
#### **3. One Model Doesn’t Fit All — The Clash of Command and Query** |
|||
|
|||
Aggregates are designed for **commands** — write operations where business rules must be enforced. |
|||
|
|||
But what about **queries**? Imagine a dashboard where we just want to list the last 10 orders. All we need is `OrderId`, `CustomerName`, and `TotalAmount`. |
|||
|
|||
Loading 10 fully-hydrated `Order` aggregates (with all their order lines) just for that list? That’s like using a cannon to hunt a sparrow. Wasteful, slow, and clumsy. |
|||
Aggregates simply aren’t built for reporting or read-heavy scenarios. |
|||
|
|||
|
|||
And there you have it — the three usual suspects that make developers doubt DDD in real life: |
|||
|
|||
- Performance headaches |
|||
|
|||
- The risk of falling into an Anemic Model |
|||
|
|||
- Aggregates being too heavy for read operations |
|||
|
|||
|
|||
So, should we give up on DDD? Absolutely not! |
|||
The key is to stop following the rules blindly and instead focus on their **real intent**. In the next chapter, we’ll explore the pragmatic approach — **Demystified Aggregates** — and how they can actually help us solve these problems. |
|||
|
|||
---------- |
|||
|
|||
### **Chapter 3: Enter the Solution — What Exactly Is a "Demystified Aggregate"?** |
|||
|
|||
The issues we listed in the last chapter don’t mean DDD is bad. They just show that blindly applying textbook rules without considering the realities of your project creates friction. |
|||
|
|||
A **Demystified Aggregate** isn’t a library or a framework. It’s a **way of thinking**. Its philosophy is simple: focus on the Aggregate’s real job, and make sure it does that job **as efficiently as possible.** |
|||
|
|||
|
|||
#### **1. Philosophy: Focus on Purpose, Not Rules** |
|||
|
|||
What’s the Aggregate’s most sacred duty? |
|||
**To protect business rules (invariants) during a data change (command).** |
|||
|
|||
Here’s the key: an Aggregate’s job isn’t to always hold all data in memory. Its job is to **ensure consistency while performing an operation**. |
|||
|
|||
Think of it like a security guard at a bank vault. Their job is to make sure transfers are done correctly. They don’t need to memorize the serial number of every single banknote. They just need the critical info for the current operation: the balance and the transfer amount. |
|||
|
|||
The Demystified Aggregate says the same thing: when running a method, you **only load the data that method actually needs**, not the entire Aggregate. |
|||
|
|||
|
|||
#### **2. The Core Idea: What “State” Does a Behavior Actually Need?** |
|||
|
|||
To apply this idea in code, ask yourself: |
|||
_“What data does the `Confirm()` method on my `Order` Aggregate actually need?”_ |
|||
|
|||
- Maybe just the order’s current `Status`. (`"Pending"` can become `"Confirmed"`, `"Cancelled"` throws an error.) |
|||
|
|||
- What about `AddItem(product, quantity)`? |
|||
|
|||
- It needs the `Status` (can’t add items to a cancelled order). |
|||
|
|||
- And maybe the existing `OrderLines` (to increase quantity if the item already exists). |
|||
|
|||
|
|||
See the pattern? Each behavior needs different data. So why load everything every single time? |
|||
|
|||
|
|||
#### **3. How Do We Do This in .NET & EF Core? Practical Solutions** |
|||
|
|||
Putting this philosophy into code is easier than you might think. |
|||
|
|||
**The Approach: Purpose-Built Repository Methods** |
|||
|
|||
Instead of a generic `GetByIdAsync()`, create methods tailored to the operation at hand. Let’s revisit our classic **Order Confirmation** scenario in a “Before & After” style. |
|||
|
|||
**BEFORE (Classic & Inefficient Approach)** |
|||
|
|||
```csharp |
|||
// Repository Layer |
|||
public async Task<Order> GetByIdAsync(Guid id) |
|||
{ |
|||
// LOAD EVERYTHING! |
|||
return await _context.Orders |
|||
.Include(o => o.OrderLines) |
|||
.SingleOrDefaultAsync(o => o.Id == id); |
|||
} |
|||
|
|||
// Application Service Layer |
|||
public async Task ConfirmOrderAsync(Guid orderId) |
|||
{ |
|||
var order = await _orderRepository.GetByIdAsync(orderId); |
|||
order.Confirm(); // This method might not even care about OrderLines! |
|||
await _unitOfWork.SaveChangesAsync(); |
|||
} |
|||
|
|||
``` |
|||
|
|||
**AFTER (Demystified & Focused Approach)** |
|||
|
|||
```csharp |
|||
// Repository Layer |
|||
public async Task<Order> GetForConfirmationAsync(Guid id) |
|||
{ |
|||
// LOAD ONLY WHAT WE NEED! (No OrderLines needed) |
|||
return await _context.Orders |
|||
.SingleOrDefaultAsync(o => o.Id == id); |
|||
} |
|||
|
|||
// Application Service Layer |
|||
public async Task ConfirmOrderAsync(Guid orderId) |
|||
{ |
|||
// Intent is crystal clear in the code! |
|||
var order = await _orderRepository.GetForConfirmationAsync(orderId); |
|||
|
|||
// Aggregate still protects the business rule. |
|||
// Confirm() checks status, etc. |
|||
order.Confirm(); |
|||
|
|||
await _unitOfWork.SaveChangesAsync(); |
|||
} |
|||
|
|||
``` |
|||
|
|||
**What Do We Gain?** |
|||
|
|||
1. **Awesome Performance:** We avoid unnecessary JOINs and data transfer. |
|||
|
|||
2. **Clear Intent:** Anyone reading `GetForConfirmationAsync` immediately knows this operation only cares about the order itself, not its items. Code documents itself. |
|||
|
|||
3. **No Compromise:** Our Aggregate still enforces the business rules via `Confirm()`. DDD’s spirit remains intact. |
|||
|
|||
|
|||
For **read/query operations**, the answer is even simpler: skip Aggregates altogether! Use optimized queries that return DTOs via `Select` projections, or even raw SQL with Dapper. |
|||
|
|||
That’s the essence of a Demystified Aggregate: **using the right tool for the right job.** |
|||
|
|||
In the next chapter, we’ll wrap everything up and tie all the concepts together. |
|||
|
|||
---------- |
|||
|
|||
### **Conclusion: Pragmatism Beats Dogmatism in DDD** |
|||
|
|||
We’ve reached the finish line. We started with the “pure” textbook definition of Aggregates in the ideal world of Domain-Driven Design. Then we hit the real-world walls of performance and complexity. Finally, we learned how to break through those walls. |
|||
|
|||
The biggest lesson from the **Demystified Aggregates** approach is simple: |
|||
|
|||
**DDD isn’t a rigid rulebook — it’s a way of thinking.** |
|||
|
|||
Our goal isn’t to implement the “most pure DDD ever written in a book.” It’s to make our domain logic clean, solid, understandable, and performant. In this journey, patterns and rules should serve us, not the other way around. |
|||
|
|||
|
|||
### **Key Takeaways** |
|||
|
|||
1. **Focus on the Core Purpose:** |
|||
The primary reason an Aggregate exists is to enforce business rules (invariants) and ensure consistency while handling a command. Every design decision should revolve around this purpose. |
|||
|
|||
2. **Load Only What You Need:** |
|||
You don’t have to load the entire Aggregate to execute a behavior. Use purpose-built repository methods (`GetForX()`) to fetch just the data needed for the operation. This can drastically improve both performance and readability. |
|||
|
|||
3. **Separate Writing from Reading:** |
|||
Use rich, protected Aggregates for commands (write operations). For queries (read operations), don’t burden your Aggregates. Instead, rely on projections, DTOs, or optimized queries. This is one of the simplest, most practical ways to embrace CQRS principles. |
|||
|
|||
Don’t be afraid to shape your Aggregates based on your project and the realities of your tools (like Entity Framework Core). The power of DDD lies in its **flexibility and pragmatism**. |
|||
|
|||
|
|||
@ -1,7 +0,0 @@ |
|||
# Dynamic Proxying / Interceptors |
|||
|
|||
This document is planned to be written later. |
|||
|
|||
## See Also |
|||
|
|||
* [Video tutorial](https://abp.io/video-courses/essentials/interception) |
|||
@ -0,0 +1,213 @@ |
|||
# Interceptors |
|||
|
|||
ABP provides a powerful interception system that allows you to execute custom logic before and after method calls without modifying the original method code. This is achieved through **dynamic proxying** and is extensively used throughout the ABP framework to implement cross-cutting concerns. ABP's interception is implemented on top of the [Castle DynamicProxy](https://www.castleproject.org/projects/dynamicproxy/) library. |
|||
|
|||
## What is Dynamic Proxying / Interception? |
|||
|
|||
**Interception** is a technique that allows executing additional logic before or after a method call without directly modifying the method's code. This is achieved through **dynamic proxying**, where the runtime generates proxy classes that wrap the original class. |
|||
|
|||
When a method is called on a proxied object: |
|||
1. The call is intercepted by the proxy |
|||
2. Custom behaviors (like logging, validation, or authorization) can be executed |
|||
3. The original method is called |
|||
4. Additional logic can be executed after the method completes |
|||
|
|||
This enables **cross-cutting concerns** (logic that applies across many parts of an application) to be handled in a clean, reusable way without code duplication. |
|||
|
|||
## Similarities and Differences with MVC Action/Page Filters |
|||
|
|||
If you are familiar with ASP.NET Core MVC, you've likely used **action filters** or **page filters**. Interceptors are conceptually similar but have some key differences: |
|||
|
|||
### Similarities |
|||
|
|||
* Both allow executing code before and after method execution |
|||
* Both are used to implement cross-cutting concerns like validation, logging, caching, or exception handling |
|||
* Both support asynchronous operations |
|||
|
|||
### Differences |
|||
|
|||
* **Scope**: Filters are tied to MVC's request pipeline, while interceptors can be applied to **any class or service** in the application |
|||
* **Configuration**: Filters are configured via attributes or middleware in MVC, while interceptors in ABP are applied through **dependency injection and dynamic proxies** |
|||
* **Target**: Interceptors can target application services, domain services, repositories, and virtually any service resolved from the IoC container—not just web controllers |
|||
|
|||
## How ABP Uses Interceptors |
|||
|
|||
ABP Framework extensively leverages interception to provide built-in features without requiring boilerplate code. Here are some key examples: |
|||
|
|||
### [Unit of Work (UOW)](../architecture/domain-driven-design/unit-of-work.md) |
|||
|
|||
Automatically begins and commits/rolls back a database transaction when entering or exiting an application service method. This ensures data consistency without manual transaction management. |
|||
|
|||
### [Input Validation](../fundamentals/validation.md) |
|||
|
|||
Input DTOs are automatically validated against data annotation attributes and custom validation rules before executing the service logic, providing consistent validation behavior across all services. |
|||
|
|||
### [Authorization](../fundamentals/authorization.md) |
|||
|
|||
Checks user permissions before allowing the execution of application service methods, ensuring security policies are enforced consistently. |
|||
|
|||
### [Feature](./features.md) & [Global Feature](./global-features.md) Checking |
|||
|
|||
Checks if a feature is enabled before executing the service logic, allowing you to conditionally enable or restrict functionality for tenants or the application. |
|||
|
|||
### [Auditing](./audit-logging.md) |
|||
|
|||
Automatically logs who performed an action, when it happened, what parameters were used, and what data was involved, providing comprehensive audit trails. |
|||
|
|||
## Building Your Own Interceptor |
|||
|
|||
You can create custom interceptors in ABP to implement your own cross-cutting concerns. |
|||
|
|||
### Creating an Interceptor |
|||
|
|||
Create a class that inherits from `AbpInterceptor`: |
|||
|
|||
````csharp |
|||
using System.Threading.Tasks; |
|||
using Volo.Abp.Aspects; |
|||
using Volo.Abp.DependencyInjection; |
|||
using Volo.Abp.DynamicProxy; |
|||
|
|||
public class ExecutionTimeLogInterceptor : AbpInterceptor, ITransientDependency |
|||
{ |
|||
private readonly ILogger<ExecutionTimeLogInterceptor> _logger; |
|||
|
|||
public ExecutionTimeLogInterceptor(ILogger<ExecutionTimeLogInterceptor> logger) |
|||
{ |
|||
_logger = logger; |
|||
} |
|||
|
|||
public override async Task InterceptAsync(IAbpMethodInvocation invocation) |
|||
{ |
|||
var sw = Stopwatch.StartNew(); |
|||
|
|||
_logger.LogInformation($"Executing {invocation.TargetObject.GetType().Name}.{invocation.Method.Name}"); |
|||
|
|||
// Proceed to the actual target method |
|||
await invocation.ProceedAsync(); |
|||
|
|||
sw.Stop(); |
|||
|
|||
_logger.LogInformation($"Executed {invocation.TargetObject.GetType().Name}.{invocation.Method.Name} in {sw.ElapsedMilliseconds} ms"); |
|||
} |
|||
} |
|||
```` |
|||
|
|||
### Register Interceptors |
|||
|
|||
Create a static class that contains the `RegisterIfNeeded` method and register the interceptor in the `PreConfigureServices` method of your module. |
|||
|
|||
The `ShouldIntercept` method is used to determine if the interceptor should be registered for the given type. You can add an `IExecutionTimeLogEnabled` interface and implement it in the classes that you want to intercept. |
|||
|
|||
> `DynamicProxyIgnoreTypes` is static class that contains the types that should be ignored by the interceptor. See [Performance Considerations](#performance-considerations) for more information. |
|||
|
|||
````csharp |
|||
// Define an interface to mark the classes that should be intercepted |
|||
public interface IExecutionTimeLogEnabled |
|||
{ |
|||
} |
|||
```` |
|||
|
|||
````csharp |
|||
using System.Threading.Tasks; |
|||
using Volo.Abp.DependencyInjection; |
|||
|
|||
// A simple service that added to the DI container and will be intercepted since it implements the `IExecutionTimeLogEnabled` interface |
|||
public class SampleExecutionTimeService : IExecutionTimeLogEnabled, ITransientDependency |
|||
{ |
|||
public virtual async Task DoWorkAsync() |
|||
{ |
|||
// Simulate a long-running task to test the interceptor |
|||
await Task.Delay(1000); |
|||
} |
|||
} |
|||
```` |
|||
|
|||
````csharp |
|||
using System; |
|||
using Volo.Abp.DependencyInjection; |
|||
using Volo.Abp.DynamicProxy; |
|||
|
|||
public static class ExecutionTimeLogInterceptorRegistrar |
|||
{ |
|||
public static void RegisterIfNeeded(IOnServiceRegistredContext context) |
|||
{ |
|||
if (ShouldIntercept(context.ImplementationType)) |
|||
{ |
|||
context.Interceptors.TryAdd<ExecutionTimeLogInterceptor>(); |
|||
} |
|||
} |
|||
|
|||
private static bool ShouldIntercept(Type type) |
|||
{ |
|||
return !DynamicProxyIgnoreTypes.Contains(type) && typeof(IExecutionTimeLogEnabled).IsAssignableFrom(type); |
|||
} |
|||
} |
|||
```` |
|||
|
|||
````csharp |
|||
public override void PreConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
context.Services.OnRegistered(ExecutionTimeLogInterceptorRegistrar.RegisterIfNeeded); |
|||
} |
|||
```` |
|||
|
|||
## Restrictions and Important Notes |
|||
|
|||
### Always use asynchronous methods |
|||
|
|||
For best performance and reliability, implement your service methods as asynchronous to avoid **async over sync**, that can cause unexpected problems, For more information, see [Should I expose synchronous wrappers for asynchronous methods?](https://devblogs.microsoft.com/dotnet/should-i-expose-synchronous-wrappers-for-asynchronous-methods/) |
|||
|
|||
### Virtual Methods Requirement |
|||
|
|||
For **class proxies**, methods need to be marked as `virtual` so that they can be overridden by the proxy. Otherwise, interception will not occur. |
|||
|
|||
````csharp |
|||
public class MyService : IExecutionTimeLogEnabled, ITransientDependency |
|||
{ |
|||
// This method CANNOT be intercepted (not virtual) |
|||
public void CannotBeIntercepted() |
|||
{ |
|||
} |
|||
|
|||
// This method CAN be intercepted (virtual) |
|||
public virtual void CanBeIntercepted() |
|||
{ |
|||
} |
|||
} |
|||
```` |
|||
|
|||
> This restriction does **not** apply to interface-based proxies. If your service implements an interface and is injected via that interface, all methods can be intercepted regardless of the `virtual` keyword. |
|||
|
|||
### Dependency Injection Scope |
|||
|
|||
Interceptors only work when services are resolved from the dependency injection container. Direct instantiation with `new` bypasses interception: |
|||
|
|||
````csharp |
|||
// This will NOT be intercepted |
|||
var service = new MyService(); |
|||
service.CannotBeIntercepted(); |
|||
|
|||
// This WILL be intercepted (if MyService is registered with DI) |
|||
var service = serviceProvider.GetService<MyService>(); |
|||
service.CanBeIntercepted(); |
|||
```` |
|||
|
|||
### Performance Considerations |
|||
|
|||
Interceptors are generally efficient, but each one adds method-call overhead. Keep the number of interceptors minimal on hot paths. |
|||
|
|||
Castle DynamicProxy can negatively impact performance for certain components, notably ASP.NET Core MVC controllers. See the discussions in [castleproject/Core#486](https://github.com/castleproject/Core/issues/486) and [abpframework/abp#3180](https://github.com/abpframework/abp/issues/3180). |
|||
|
|||
ABP uses interceptors for features like UOW, auditing, and authorization, which rely on dynamic proxy classes. For controllers, prefer implementing cross-cutting concerns with middleware or MVC/Page filters instead of dynamic proxies. |
|||
|
|||
To avoid generating dynamic proxies for specific types, use the static class `DynamicProxyIgnoreTypes` and add the base classes of the types to the list. Subclasses of any listed base class are also ignored. ABP framework already adds some base classes to the list (`ComponentBase, ControllerBase, PageModel, ViewComponent`); you can add more base classes if needed. |
|||
|
|||
> Always use interface-based proxies instead of class-based proxies for better performance. |
|||
|
|||
## See Also |
|||
|
|||
* [Video tutorial: Interceptors in ABP Framework](https://abp.io/video-courses/essentials/interception) |
|||
* [Castle DynamicProxy](https://www.castleproject.org/projects/dynamicproxy/) |
|||
* [Castle.Core.AsyncInterceptor](https://github.com/JSkimming/Castle.Core.AsyncInterceptor) |
|||
* [ASP.NET Core Filters](https://learn.microsoft.com/en-us/aspnet/core/mvc/controllers/filters) |
|||
@ -0,0 +1,10 @@ |
|||
namespace Volo.Abp.EventBus.Distributed; |
|||
|
|||
public enum IncomingEventStatus |
|||
{ |
|||
Pending = 0, |
|||
|
|||
Discarded = 1, |
|||
|
|||
Processed = 2 |
|||
} |
|||
@ -0,0 +1,22 @@ |
|||
namespace Volo.Abp.EventBus.Distributed; |
|||
|
|||
public enum InboxProcessorFailurePolicy |
|||
{ |
|||
/// <summary>
|
|||
/// Default behavior, retry the following event in next period time.
|
|||
/// </summary>
|
|||
Retry, |
|||
|
|||
/// <summary>
|
|||
/// Skip the failed event and retry it after a delay.
|
|||
/// The delay doubles with each retry, starting from the configured InboxProcessorRetryBackoffFactor
|
|||
/// (e.g., 10, 20, 40, 80 seconds, etc.).
|
|||
/// The event is discarded if it still fails after reaching the maximum retry count.
|
|||
/// </summary>
|
|||
RetryLater, |
|||
|
|||
/// <summary>
|
|||
/// Skip the event and do not retry it.
|
|||
/// </summary>
|
|||
Discard, |
|||
} |
|||
@ -0,0 +1,31 @@ |
|||
using System; |
|||
using System.Collections.Concurrent; |
|||
|
|||
using System.Reflection; |
|||
using MongoDB.Bson.Serialization; |
|||
|
|||
namespace Volo.Abp.MongoDB; |
|||
|
|||
public static class AbpBsonSerializer |
|||
{ |
|||
private static readonly ConcurrentDictionary<Type, IBsonSerializer> Cache; |
|||
|
|||
static AbpBsonSerializer() |
|||
{ |
|||
var registry = BsonSerializer.SerializerRegistry; |
|||
var type = typeof(BsonSerializerRegistry); |
|||
var cacheField = type.GetField("_cache", BindingFlags.NonPublic | BindingFlags.Instance) ?? |
|||
throw new AbpException($"Cannot find _cache field of {type.FullName}."); |
|||
Cache = (ConcurrentDictionary<Type, IBsonSerializer>)cacheField.GetValue(registry)!; |
|||
} |
|||
|
|||
public static void RemoveSerializer<T>() |
|||
{ |
|||
Cache.TryRemove(typeof(T), out _); |
|||
} |
|||
|
|||
public static ConcurrentDictionary<Type, IBsonSerializer> GetSerializerCache() |
|||
{ |
|||
return Cache; |
|||
} |
|||
} |
|||
@ -0,0 +1,54 @@ |
|||
using System.Text.Json; |
|||
using Shouldly; |
|||
using Xunit; |
|||
|
|||
namespace Volo.Abp.Json; |
|||
|
|||
public class ObjectToInferredTypesConverter_Tests : AbpJsonSystemTextJsonTestBase |
|||
{ |
|||
private readonly IJsonSerializer _jsonSerializer; |
|||
|
|||
public ObjectToInferredTypesConverter_Tests() |
|||
{ |
|||
_jsonSerializer = GetRequiredService<IJsonSerializer>(); |
|||
} |
|||
|
|||
[Fact] |
|||
public void Test() |
|||
{ |
|||
var objString = _jsonSerializer.Serialize(new object()); |
|||
objString.ShouldBe("{}"); |
|||
var obj = _jsonSerializer.Deserialize<object>(objString); |
|||
obj.ShouldBeOfType<JsonElement>(); |
|||
|
|||
var booleanString = _jsonSerializer.Serialize(true); |
|||
booleanString.ShouldBe("true"); |
|||
var boolean = _jsonSerializer.Deserialize<bool>(booleanString); |
|||
boolean.ShouldBe(true); |
|||
|
|||
var booleanString2 = _jsonSerializer.Serialize(false); |
|||
booleanString2.ShouldBe("false"); |
|||
var boolean2 = _jsonSerializer.Deserialize<bool>(booleanString2); |
|||
boolean2.ShouldBe(false); |
|||
|
|||
var numberString = _jsonSerializer.Serialize(1); |
|||
numberString.ShouldBe("1"); |
|||
var number = _jsonSerializer.Deserialize<long>(numberString); |
|||
number.ShouldBe(1); |
|||
|
|||
var numberString2 = _jsonSerializer.Serialize(1.1); |
|||
numberString2.ShouldBe("1.1"); |
|||
var number2 = _jsonSerializer.Deserialize<double>(numberString2); |
|||
number2.ShouldBe(1.1); |
|||
|
|||
var dateString = _jsonSerializer.Serialize(System.DateTime.Parse("2024-01-01")); |
|||
dateString.ShouldBe("\"2024-01-01T00:00:00\""); |
|||
var date = _jsonSerializer.Deserialize<System.DateTime>(dateString); |
|||
date.ShouldBe(System.DateTime.Parse("2024-01-01")); |
|||
|
|||
var textString = _jsonSerializer.Serialize("text"); |
|||
textString.ShouldBe("\"text\""); |
|||
var text = _jsonSerializer.Deserialize<string>(textString); |
|||
text.ShouldBe("text"); |
|||
} |
|||
} |
|||
@ -1,6 +1,26 @@ |
|||
{ |
|||
"culture": "en", |
|||
"texts": { |
|||
"SeeYou": "See you" |
|||
"SeeYou": "See you", |
|||
"MyNestedTranslation": { |
|||
"SomeKey": "Some nested value", |
|||
"SomeOtherKey": "Some other nested value", |
|||
"DeeplyNested": { |
|||
"DeepKey": "A deeply nested value" |
|||
}, |
|||
"DeeplyNestedArray": [ |
|||
"First value in array", |
|||
"Second value in array", |
|||
{ |
|||
"InnerDeepKey": "Inner deeply nested value" |
|||
}, |
|||
{ |
|||
"InnerDeepArray": [ |
|||
"First inner deep array value", |
|||
"Second inner deep array value" |
|||
] |
|||
} |
|||
] |
|||
} |
|||
} |
|||
} |
|||
} |
|||
|
|||
@ -0,0 +1,158 @@ |
|||
using System; |
|||
using Microsoft.Extensions.DependencyInjection; |
|||
using Riok.Mapperly.Abstractions; |
|||
using Shouldly; |
|||
using Volo.Abp.Data; |
|||
using Volo.Abp.Mapperly.SampleClasses; |
|||
using Volo.Abp.ObjectExtending; |
|||
using Volo.Abp.ObjectMapping; |
|||
using Volo.Abp.Testing; |
|||
using Xunit; |
|||
|
|||
namespace Volo.Abp.Mapperly; |
|||
|
|||
public class ExtraProperties_Dictionary_Reference_Tests : AbpIntegratedTest<MapperlyTestModule> |
|||
{ |
|||
private readonly IObjectMapper _objectMapper; |
|||
|
|||
public ExtraProperties_Dictionary_Reference_Tests() |
|||
{ |
|||
_objectMapper = ServiceProvider.GetRequiredService<IObjectMapper>(); |
|||
} |
|||
|
|||
[Fact] |
|||
public void Should_Create_New_ExtraProperties_Dictionary_When_Same_Reference() |
|||
{ |
|||
// Arrange: Create a shared ExtraProperties dictionary
|
|||
var sharedExtraProperties = new ExtraPropertyDictionary |
|||
{ |
|||
{"TestProperty", "TestValue"}, |
|||
{"NumberProperty", 42} |
|||
}; |
|||
|
|||
var source = new TestEntityWithExtraProperties |
|||
{ |
|||
Id = Guid.NewGuid(), |
|||
Name = "Source Entity" |
|||
}; |
|||
|
|||
var destination = new TestEntityDtoWithExtraProperties |
|||
{ |
|||
Id = Guid.NewGuid(), |
|||
Name = "Destination DTO" |
|||
}; |
|||
|
|||
// Make both source and destination reference the same ExtraProperties dictionary
|
|||
SetExtraPropertiesReference(source, sharedExtraProperties); |
|||
SetExtraPropertiesReference(destination, sharedExtraProperties); |
|||
|
|||
// Verify they have the same reference before mapping
|
|||
ReferenceEquals(source.ExtraProperties, destination.ExtraProperties).ShouldBeTrue(); |
|||
source.ExtraProperties.Count.ShouldBe(2); |
|||
destination.ExtraProperties.Count.ShouldBe(2); |
|||
|
|||
// Act: Perform mapping
|
|||
_objectMapper.Map(source, destination); |
|||
|
|||
// Assert: After mapping, they should have different references
|
|||
// This is the key fix: when ExtraProperties references are the same,
|
|||
// a new dictionary should be created for the destination
|
|||
ReferenceEquals(source.ExtraProperties, destination.ExtraProperties).ShouldBeFalse(); |
|||
|
|||
// But content should be preserved
|
|||
destination.ExtraProperties["TestProperty"].ShouldBe("TestValue"); |
|||
destination.ExtraProperties["NumberProperty"].ShouldBe(42); |
|||
destination.ExtraProperties.Count.ShouldBe(source.ExtraProperties.Count); |
|||
} |
|||
|
|||
[Fact] |
|||
public void Should_Not_Create_New_Dictionary_When_Different_References() |
|||
{ |
|||
// Arrange: Create source and destination with different ExtraProperties references
|
|||
var source = new TestEntityWithExtraProperties |
|||
{ |
|||
Id = Guid.NewGuid(), |
|||
Name = "Source Entity" |
|||
}; |
|||
source.SetProperty("SourceProperty", "SourceValue"); |
|||
|
|||
var destination = new TestEntityDtoWithExtraProperties |
|||
{ |
|||
Id = Guid.NewGuid(), |
|||
Name = "Destination DTO" |
|||
}; |
|||
destination.SetProperty("DestinationProperty", "DestinationValue"); |
|||
|
|||
var originalSourceReference = source.ExtraProperties; |
|||
|
|||
// Verify they have different references before mapping
|
|||
ReferenceEquals(source.ExtraProperties, destination.ExtraProperties).ShouldBeFalse(); |
|||
|
|||
// Act: Perform mapping
|
|||
_objectMapper.Map(source, destination); |
|||
|
|||
// Assert: Source reference should remain unchanged
|
|||
ReferenceEquals(source.ExtraProperties, originalSourceReference).ShouldBeTrue(); |
|||
|
|||
// Destination reference may change due to normal mapping process, but should not be same as source
|
|||
ReferenceEquals(source.ExtraProperties, destination.ExtraProperties).ShouldBeFalse(); |
|||
|
|||
destination.ExtraProperties["SourceProperty"].ShouldBe("SourceValue"); |
|||
destination.ExtraProperties["DestinationProperty"].ShouldBe("DestinationValue"); |
|||
} |
|||
|
|||
[Fact] |
|||
public void Should_Handle_Readonly_ExtraProperties_Gracefully() |
|||
{ |
|||
// Arrange: Create entities with readonly ExtraProperties
|
|||
var source = new TestEntityWithReadonlyExtraProperties |
|||
{ |
|||
Id = Guid.NewGuid(), |
|||
Name = "Source Entity" |
|||
}; |
|||
source.ExtraProperties.Add("TestProperty", "TestValue"); |
|||
|
|||
var destination = new TestEntityWithReadonlyExtraProperties |
|||
{ |
|||
Id = Guid.NewGuid(), |
|||
Name = "Destination Entity" |
|||
}; |
|||
|
|||
// Make them reference the same ExtraProperties
|
|||
var sharedExtraProperties = new ExtraPropertyDictionary |
|||
{ |
|||
{"SharedProperty", "SharedValue"} |
|||
}; |
|||
SetReadonlyExtraPropertiesReference(source, sharedExtraProperties); |
|||
SetReadonlyExtraPropertiesReference(destination, sharedExtraProperties); |
|||
|
|||
// Verify they have the same reference
|
|||
ReferenceEquals(source.ExtraProperties, destination.ExtraProperties).ShouldBeTrue(); |
|||
|
|||
// Act & Assert: Should not throw exception even if setter is not available
|
|||
Should.NotThrow(() => _objectMapper.Map(source, destination)); |
|||
} |
|||
|
|||
private static void SetExtraPropertiesReference(TestEntityWithExtraProperties entity, ExtraPropertyDictionary extraProperties) |
|||
{ |
|||
// Use reflection to set the protected setter from ExtensibleObject
|
|||
var propertyInfo = typeof(ExtensibleObject).GetProperty(nameof(ExtensibleObject.ExtraProperties)); |
|||
propertyInfo?.SetValue(entity, extraProperties); |
|||
} |
|||
|
|||
private static void SetExtraPropertiesReference(TestEntityDtoWithExtraProperties entity, ExtraPropertyDictionary extraProperties) |
|||
{ |
|||
// Use reflection to set the protected setter from ExtensibleObject
|
|||
var propertyInfo = typeof(ExtensibleObject).GetProperty(nameof(ExtensibleObject.ExtraProperties)); |
|||
propertyInfo?.SetValue(entity, extraProperties); |
|||
} |
|||
|
|||
private static void SetReadonlyExtraPropertiesReference(TestEntityWithReadonlyExtraProperties entity, ExtraPropertyDictionary extraProperties) |
|||
{ |
|||
// Use reflection to set the private field
|
|||
var fieldInfo = typeof(TestEntityWithReadonlyExtraProperties).GetField("_extraProperties", |
|||
System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance); |
|||
fieldInfo?.SetValue(entity, extraProperties); |
|||
} |
|||
} |
|||
|
|||
@ -0,0 +1 @@ |
|||
@import url('https://fonts.googleapis.com/css2?family=Lexend:wght@100..900&family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap'); |
|||