ByteAether

The Architecture of Obsession: Why ByteAether.Ulid is the Last Identifier Library You Will Ever Need

2026-04-02T00:00:00Z

Most developers treat unique identifiers like plumbing. You want them to work, you want them to be out of sight, and you certainly do not want to spend your Friday nights thinking about them. For the average CRUD application, Guid.NewGuid() is a perfectly acceptable choice. However, if you are reading this, you are likely not an average developer. You are an architect or a senior engineer who understands that at scale, "good enough" is a ticking time bomb of index fragmentation and out-of-order writes.

I have spent an unreasonable amount of time obsessing over Universally Unique Lexicographically Sortable Identifiers (ULIDs). While the rest of the world moved on to other things, I stayed behind to build ByteAether.Ulid, a library that is, quite frankly, over-engineered to the point of insanity. But in a world of "lazy" implementations and optional monotonicity, perhaps a bit of insanity is exactly what your distributed system needs.

The Sortability: Why UUIDv7 Isn't the Hero We Expected

For a long time, the industry waited for a standardized, sortable replacement for the legacy GUID (UUIDv4). When UUIDv7 arrived via RFC 9562, it seemed like the answer. Even .NET introduced a native provider for it. However, if you dig into the implementation details (specifically how the native .NET provider implements the generation of UUIDv7), you find a compromise.

The specification for UUIDv7 makes monotonicity optional. This means that during a high-concurrency burst within the same millisecond, the native provider may sacrifice strict ordering to maintain performance. To a database architect, this is heresy. Out-of-order identifiers lead to page splits in B-Tree indexes, which leads to physical disk fragmentation and degraded insert performance.

ULIDs solve this by design. By mandating lexicographical sortability and strict monotonic increments, ULID ensures that your primary keys are always appended to the end of the index. ByteAether.Ulid doubles down on this by providing a robust, fully compliant .NET implementation that refuses to take the "lazy" path.

Eliminating the Overflow Exception

One of the darker corners of the ULID specification involves what happens when the 80-bit random component overflows during a monotonic increment within the same millisecond. Many libraries simply throw an OverflowException (as specification dictates), effectively crashing your ingestion pipeline because you were "too fast" for the generator. This isn't just a theoretical concern for high-volume systems as the initial random component is cryptographically generated and it could start near its maximum value, causing the very next increment to fail.

In ByteAether.Ulid, we have implemented a more elegant solution. When the random part overflows, the library automatically increments the timestamp component. This ensures that unique ULID generation continues without interruption while maintaining the sort order. This behavior ensures that your system remains resilient even under extreme throughput. For a deep dive into the engineering rationale and why this is more likely than you think, check out our dedicated article on Handling ULID Overflows Gracefully.

High-Performance, Lock-Free Concurrency

In high-concurrency environments, locks are the enemy of throughput. If every thread in your web farm has to wait for a global lock just to generate an ID, you have created a bottleneck.

ByteAether.Ulid utilizes a lock-free compare-and-exchange (CAS) approach for monotonic generation. This allows multiple threads to attempt to increment the state simultaneously without traditional locking overhead. If a collision occurs, the CAS operation retries until it succeeds, ensuring thread safety with maximum performance.

In terms of raw speed, ByteAether.Ulid stands as one of the most performant implementations available, often matching or exceeding the most optimized competitors in the .NET ecosystem while maintaining a zero-allocation footprint for standard generation. Detailed performance metrics and environment-specific results are maintained on our GitHub page.

Preventing Enumeration Attacks with Random Increments

Standard monotonic ULIDs can be predictable. If an attacker knows one ULID, they can often guess the next one by simply adding 1 to the random component. This is a significant security risk for public-facing APIs.

To mitigate this, I have implemented configurable random increments. Instead of adding a static 1 to the random component, you can configure the library to use a random increment ranging from 1 byte up to 4 bytes. This significantly increases the entropy between sequential IDs, making enumeration attacks computationally expensive while still preserving the lexicographical sortability required for your database indexes.

The Developer Experience: Frictionless Integration

A library should feel like a native part of your stack, not an obstacle. I've focused on ensuring that ByteAether.Ulid integrates seamlessly with modern .NET defaults while providing clear pathways for specialized tooling. The library includes native, built-in support for:

System.Text.Json: Includes a high-performance JsonConverter for effortless serialization to canonical Base32 strings.
ASP.NET Core: Built-in TypeConverter support allows you to use Ulid directly as a route or query parameter in your controllers and Minimal APIs.

For the rest of the ecosystem, I've ensured the implementation is as "plug-and-play" as possible. Whether you are using Entity Framework Core, Dapper, Newtonsoft.Json, or MessagePack, the library's architecture makes integration trivial. I've documented the exact, low-boilerplate snippets required for these tools in the GitHub README, so you can drop them into your project and get back to building your core logic.

Advanced Filtering with LINQ

One of the most powerful features of ULIDs is the ability to perform time-range queries without a separate CreatedAt column. Because the timestamp is embedded in the ID, you can generate boundary ULIDs:

var start = Ulid.MinAt(DateTimeOffset.UtcNow.AddDays(-7)); var end = Ulid.MaxAt(DateTimeOffset.UtcNow); // EF Core translates this into an efficient range comparison on the Primary Key var reports = await context.Reports .Where(r => r.Id >= start && r.Id <= end) .ToListAsync();

This approach allows you to leverage the primary key index for high-performance temporal queries, reducing the need for additional composite indexes.

Embracing the Over-Engineered

The development of ByteAether.Ulid represents a commitment to refining edge cases, ensuring AOT (Ahead-of-Time) compilation compatibility, and hardening logic against the weirdest distributed system failures.

Is it overkill? Probably. Do you need a library that handles sub-millisecond random overflows via timestamp carry-over using lock-free CAS? Maybe not today. But when your system scales to millions of events per second and your database starts choking on index fragmentation, you will be glad someone was "insane" enough to build this.

Stop settling for "lazy" identifiers. Give your architecture the precision it deserves by checking out the project on GitHub.

The Weight of Decisions: Solving Weighted Random Sorting at Scale

2026-01-07T00:00:00Z

Several years ago at Microsoft, I worked on a back-end service responsible for routing high volumes of traffic. The service functioned as a traffic dispatcher: we received an incoming request, determined the most appropriate downstream destination, and forwarded the payload.

Our routing decisions relied on a pool of destination services. To ensure reliability, we tracked ongoing statistics regarding the success rates of these partners. When a destination consistently processed requests successfully, we increased its traffic share. Conversely, if we observed frequent errors, we reduced its allocation.

The Requirement for Ordered Fail-over

Routing in a distributed environment requires more than just selecting a single destination. Downstream partners occasionally fail to process specific items due to transient internal errors or malformed data. Because of this, we needed a "fail-over" list for every request. If the primary choice failed, the system needed an immediate second and third option ready to go.

This meant our routing logic had to produce a fully sorted list of all available destination services. We would attempt to send the request to the first service in the list; if that service returned an error, we moved to the second, and continued until the request succeeded or we exhausted the list.

Balancing Traffic via Weighted Randomization

A simple deterministic sort based on quality scores would create a "starvation" problem. If Service A had the highest success rate, a standard sort would consistently place it at the top. This would result in Service A receiving 100% of the initial traffic, leaving services B and C with no data points. Without ongoing "exploration" traffic to lower-ranked services, we could never observe if their performance had recovered or improved.

To maintain fresh statistics across the entire pool, we needed a weighted random sort, effectively a weighted permutation. Consider a scenario with three services and the following target distributions:

Service A: 50%
Service B: 30%
Service C: 20%

The sorted list needed to respect these probabilities at every rank. For the first position, the chances are exactly as defined (50%, 30%, 20%). However, if Service A is selected for the first slot, the second slot must be filled by B or C based on their remaining relative weights. In this case, Service B should appear in the second position with a probability of 0.3 / (0.3 + 0.2) = 60%, while Service C takes the spot 40% of the time.

Implementation Logic

Both the initial and the improved versions of our code use the following data structure to represent a destination:

public class Item { public string Name { get; set; } public double Weight { get; set; } }

The Intuition and the Initial O(N² log N) Approach

I suspected a mathematical shortcut existed to calculate a single value for each item that, when sorted, would result in this exact distribution. This thought surfaced repeatedly over the years and never truly gave me peace. I felt certain a single-pass solution was possible, yet the specific formula remained out of reach. At the time, we settled on an iterative approach that picked items one by one.

In C#, the implementation relied on a "weighted pick and remove" loop. The computational cost was actually O(N² log N) in the version below because a full sort is performed inside a loop to pick just one item. While N = 10 renders this inefficiency invisible in production, the logic scales poorly for larger pools or high-throughput middleware.

public static List<T> InefficientWeightedRandomize<T>(IEnumerable<T> source) where T : Item { var remainingItems = source.ToList(); var result = new List<T>(); while (remainingItems.Any()) { // Sort the source list by a random factor modified by weight var nextItem = remainingItems .Select(item => new { Item = item, SortKey = Random.Shared.NextDouble() * item.Weight }) .OrderByDescending(x => x.SortKey) .First(); result.Add(nextItem.Item); remainingItems.Remove(nextItem.Item); } return result; }

The Efraimidis-Spirakis Algorithm

Recently, I came across the Efraimidis-Spirakis Weighted Random Sampling paper, which provides the mathematical proof for the "one-pass sort" I had originally envisioned. The paper demonstrates that calculating a key k_i = u_i^1/w_i (where u is a random value and w is the weight) and sorting by that key produces a mathematically perfect weighted random sample.

This technique is a specialized form of Reservoir Sampling. It allows us to process the list in O(N log N) time with a much cleaner implementation:

public static List<T> WeightedRandomize<T>(IEnumerable<T> source) where T : Item { return source .Select(item => new { Item = item, SortKey = Math.Pow( Random.Shared.NextDouble(), 1.0 / item.Weight ) }) .OrderByDescending(x => x.SortKey) .Select(x => x.Item) .ToList(); }

Applications for Streaming Data

The Efraimidis-Spirakis algorithm offers an interesting property: it works on data streams without requiring the full list to be present at the start. Since each item's SortKey is calculated independently, we can assign keys as items arrive. Once the stream ends, a single pass through the data (or maintaining a min-heap for a "Top K" selection) yields the result.

For the team back at Microsoft still managing these services, this is a small but elegant improvement. While N = 10 doesn't demand high-performance algorithms, replacing the O(N²) loop with a proper weighted sort aligns the implementation with the intended mathematical model. I suspect there might even be an old research ticket regarding this specific efficiency improvement sitting in the backlog, likely created by me before I moved on. It might be time to finally close it.

Building an Enterprise Data Access Layer: Automated User Auditing and Series Wrap-up

2025-12-01T00:00:00Z

Welcome to the seventh and final article in our series on building an enterprise-grade Data Access Layer (DAL) in C#. Over the last six posts, we have methodically built a robust, automated, and secure DAL using a database-first philosophy with C# and Linq2Db.

We've tackled soft-deletes, timestamp auditing, multi-tenancy, and even complex projected row-level security. In our very first article, we set a high bar for the capabilities our DAL must provide. Today, we implement the final missing piece: automated user auditing (CreatedByUser / ModifiedByUser).

Once that's in place, we'll hold a full retrospective to see how our final architecture stacks up against our original goals, and finally, we'll look at what challenges lie beyond this series.

Implementing User Auditing

So far, our audit fields (CreatedAt, ModifiedAt) tell us when a record was changed. User auditing completes the picture by telling us who made that change. This is a common requirement for compliance, traceability, and debugging.

Our goal is to automatically populate CreatedByUserId on insert and ModifiedByUserId on insert and update, using the UserId from our request-scoped context. We will follow the exact same pattern of "behavioral interfaces" that we established in Part 3 (Auditing) and Part 4 (Soft-Delete).

The Schema and Interface Contracts

Following our database-first approach, we first update the database schema. We add created_by_user_id ulid not null and modified_by_user_id ulid not null columns to the post and comment tables, both with foreign keys referencing the user table.

Next, we define the C# contracts in DAL.Base/EntityBehavior/:

namespace DAL.Base.EntityBehavior; public interface IUserCreatable { Ulid CreatedByUserId { get; set; } }

namespace DAL.Base.EntityBehavior; public interface IUserModifiable { Ulid ModifiedByUserId { get; set; } }

These simple interfaces define the properties our DAL will automatically manage.

Automated Scaffolding

With the database and interfaces in place, we update our custom scaffolding interceptor (DAL.ScaffoldInterceptor/Interceptor.cs).

Just as it was configured to detect created_at and attach ICreatable, we've now taught it to look for created_by_user_id and modified_by_user_id columns. When it finds them, it automatically adds IUserCreatable and IUserModifiable to the generated partial entity classes in DbCtx.generated.cs.

This is the power of our architecture: the database schema remains the single source of truth. A schema change, followed by a re-scaffold, is all that's needed to make the C# code aware of this new behavior.

Updating the CRUD Extensions

The final step is to update our CrudExtensions.cs file to enforce the logic. We need to fetch the current user's ID from our IDbCtx (which we added in Part 6) and assign it.

We update CreateAsync, ModifyAsync (for single entity), and ModifyAsync (for fluent queries) to handle these new interfaces.

public static async Task<long> CreateAsync<T>( this IDbCtx ctx, IEnumerable<T> entities, CancellationToken cancellationToken = default ) where T : class, IEntity => ( await ctx.BulkCopyAsync( entities.Select(e => { // Timestamp Auditing (from Part 3) if ( e is ICreatable creatable && creatable.CreatedAt == default ) { creatable.CreatedAt = DateTime.UtcNow; } // NEW: User Create Auditing if ( e is IUserCreatable userCreatable && userCreatable.CreatedByUserId == default ) { userCreatable.CreatedByUserId = ctx.Attributes.UserId ?? Ulid.Empty; } // Timestamp Auditing (from Part 3) if ( e is IModifiable updateable && updateable.ModifiedAt == default ) { updateable.ModifiedAt = DateTime.UtcNow; } // NEW: User Modify Auditing if ( e is IUserModifiable userUpdateable && userUpdateable.ModifiedByUserId == default ) { userUpdateable.ModifiedByUserId = ctx.Attributes.UserId ?? Ulid.Empty; } return e; } ), cancellationToken ) ).RowsCopied; public static Task<int> ModifyAsync<T>( this IDbCtx ctx, T entity, CancellationToken cancellationToken = default ) where T : class, IEntity { // Timestamp Auditing (from Part 3) if (entity is IModifiable updateable) { updateable.ModifiedAt = DateTime.UtcNow; } // NEW: User Modify Auditing if (entity is IUserModifiable userUpdateable) { userUpdateable.ModifiedByUserId = ctx.Attributes.UserId ?? Ulid.Empty; } return ctx.GetTable<T>() .UpdateOptimisticAsync(entity, cancellationToken); }

The `IUpdatable` Nuance

The fluent ModifyAsync extension (which operates on IUpdatable<T>) presents a unique challenge. This method is what allows us to write code like ctx.GetTable<Post>().Where(p => p.Id == id).ModifyAsync().

To inject the ModifiedByUserId value, we need the IDbCtx instance to get the ctx.Attributes.UserId. However, the IUpdatable<T> (which is essentially an IQueryable) doesn't expose its parent context directly.

To solve this, we use a helper provided by Linq2Db:

public static Task<int> ModifyAsync<T>( this IUpdatable<T> source, CancellationToken cancellationToken = default ) where T : class { // Timestamp Auditing (from Part 3) if (typeof(IModifiable).IsAssignableFrom(typeof(T))) { source = source.Set( x => Sql.Property<DateTime>(x, nameof(IModifiable.ModifiedAt)), DateTime.UtcNow ); } // NEW: User Modify Auditing if (typeof(IUserModifiable).IsAssignableFrom(typeof(T))) { // Get the DbCtx from the query var dbCtx = Internals.GetDataContext(source) as IDbCtx; source = source.Set( x => Sql.Property<Ulid>(x, nameof(IUserModifiable.ModifiedByUserId)), dbCtx?.Attributes.UserId ?? Ulid.Empty ); } return source.UpdateAsync(cancellationToken); }

The key part is (LinqToDB.Internal.Linq.)Internals.GetDataContext(source). While using an Internal namespace is generally something to be wary of, it is a pragmatic and necessary solution in this advanced scenario. It allows us to bridge our fluent query API with our request-scoped context, ensuring user auditing is applied even during batch UPDATE operations.

And with that, our final automated behavior is implemented.

The Result: A Fully Automated Query

To see all our work come together, let's look at the simple ModifyAsync call from our Program.cs that updates a Comment:

// Try to update a protected comment entity await ctx.GetTable<Comment>() .Set(x => x.Content, "asd123") .ModifyAsync();

When this C# code executes, our DAL intercepts it and, using all the logic from this series, generates the following comprehensive SQL query:

UPDATE [comment] SET [content] = 'asd123', [modified_at] = '2025-11-12 15:31:11.972', [modified_by_user_id] = X'019A78B1378CC2EC0F1736EE8D4F1E8F' FROM [post] [a_Post], [user] [a_User], [permission] [b] WHERE [a_User].[removed_at] IS NULL AND [a_User].[tenant_id] = X'019A78B13787E6060BF9BA9A51DAA2C6' AND [a_Post].[removed_at] IS NULL AND [comment].[removed_at] IS NULL AND [comment].[post_id] = [a_Post].[id] AND [a_Post].[user_id] = [a_User].[id] AND [b].[object_id] = [a_Post].[id] AND [b].[subject_id] = X'019A78B1378CC2EC0F1736EE8D4F1E8F'

This single UPDATE statement perfectly demonstrates our entire architecture working in harmony. The SET clause not only updates the content but also automatically injects modified_at (from Part 3) and our new modified_by_user_id field.

Furthermore, the WHERE clause is a composition of all our global filters:

Soft-Delete (removed_at IS NULL) on user, post, and comment.
Multi-Tenancy (tenant_id = ...) on the user table (a projected filter).
Row-Level Security ([b].[object_id] = ...) by joining the permission table (another projected filter).

This is the automation we set out to build, all abstracted from the developer who just called .ModifyAsync().

Achieving Our Goals

In our first article, we defined a clear set of requirements for an enterprise DAL. Our mission was to automate cross-cutting concerns to prevent errors and reduce technical debt. Let's review our original checklist.

Soft-Delete:
- Goal: Automatically filter out records marked with a DeletedAt timestamp on all read operations.
- Achieved: Yes. In Part 4, we implemented IRemovable and a composable global query filter system. This system automatically and ubiquitously applies the WHERE [removed_at] IS NULL clause to all queries, including joins. We also overrode DeleteAsync to transparently convert deletes into updates.
Timestamp Auditing:
- Goal: Automatically populate CreatedAt and ModifiedAt timestamps.
- Achieved: Yes. In Part 3, we used ICreatable and IModifiable interfaces and CrudExtensions to inject the current timestamp during create and modify operations.
User Auditing:
- Goal: Automatically populate CreatedByUserId and ModifiedByUserId with the current user's ID.
- Achieved: Yes. We just completed this in the first section of this article, using the exact same robust pattern (IUserCreatable, IUserModifiable).
Multi-Tenancy Filtering:
- Goal: Automatically inject a WHERE TenantId = [CurrentTenantId] clause for all tenant-owned entities.
- Achieved: Yes. In Part 5, we leveraged our composable filter system by introducing the ITenanted interface. This filter reads the TenantId from our request-scoped DbCtxAttributes and applies the filter.
Projected Data Support:
- Goal: Resolve contextual IDs (like TenantId or permission IDs) even when they are on a related entity.
- Achieved: Yes. This was a critical success and a key differentiator for Linq2Db.
  1. Projected Tenancy: In Part 5, our Post entity implemented ITenanted by defining its TenantId via an [ExpressionMethod] that navigated to its parent User (x => x.User.TenantId).
  2. Projected Permissions: In Part 6, our Comment entity implemented IProtected by projecting its permission ObjectId from its parent Post (x => x.Post.Id).
- In both cases, Linq2Db correctly translated these C# expressions into the necessary SQL INNER JOINs and WHERE clauses.
Entity-Based Permissions (RLS):
- Goal: Automatically filter rows that the current user is not authorized to see.
- Achieved: Yes. In Part 6, we built our final and most complex filter, IProtected. This filter joins against the permission table using the current UserId, effectively implementing row-level security transparently.

Verdict: We successfully implemented 100% of our initial goals. The final composed query, which Linq2Db generates by combining all these filters, is a testament to the power of this composable, interface-driven architecture.

Future Ideas

While this series is complete, the work of a systems architect is never truly finished. Our DAL is robust, but it exists within a larger ecosystem. Here are a few topics worth exploring next:

Database Migrations and CI Pipelines: We've perfected the runtime behavior of our DAL, but we've manually managed schema changes. A critical next step would be to build a full-fledged CI/CD pipeline. This would involve using a migration tool to manage schema evolution, and building a pipeline that runs tests, applies migrations, performs health checks, and supports automatic rollbacks.
Full History Support: In our first article, we deliberately scoped out full history support, settling for soft-deletes and simple audit stamps. For systems with deep compliance or analytical needs (e.g., "what did this record look like on June 1st?"), this isn't enough. A fascinating challenge would be to implement a full temporal history or versioning system directly within the DAL.
Replicating this with EF Core: Replicating this architecture in EF Core, .NET's most popular ORM, would be a significant challenge. While its Global Query Filters are identical, necessitating the same composable filter system, other aspects diverge. EF Core's "code-first" preference and reliance on a Change Tracker (Unit of Work) would fundamentally alter our scaffolding and CrudExtensions implementation. The largest obstacle would be projected properties, as EF Core lacks native support for [ExpressionMethod], requiring a deep investigation into community libraries to handle our projected tenancy and RLS.

Conclusion

Thank you for following this series. We began with an ambitious set of goals for a "perfect" DAL, and through seven articles, we've built it piece by piece. We have a Data Access Layer that is truly "enterprise-ready" - it is secure by default, resilient to common errors, and abstracts immense complexity away from the business logic.

The final code for this article, and the entire series, is available on GitHub.

Full Source Code: https://github.com/ByteAether/EnterpriseDal/tree/part7

I hope this series has provided a valuable blueprint for your own advanced data access architectures.

Building an Enterprise Data Access Layer: Composable Row-Level Security

2025-11-24T00:00:00Z

Welcome to the sixth post in our series on building a feature-rich, automated enterprise Data Access Layer (DAL) using C# and Linq2Db. In our previous articles, we established a powerful architectural pattern: a composable global query filter system. This system allows us to define cross-cutting concerns as simple interfaces, automatically combining and applying them to every relevant query.

So far, we have successfully implemented:

Automated Auditing (ICreatable, IModifiable) to set CreatedAt and ModifiedAt timestamps.
Transparent Soft-Deletes (IRemovable) to filter out records where RemovedAt is not NULL.
Composable Multi-Tenancy (ITenanted) to automatically isolate data based on a TenantId, even through projected relationships.

In this post, we will tackle the final and most complex pillar of our automated DAL: entity-based row-level security (RLS). Our goal is to automatically filter any query to return only the records that the current user is authorized to access. We will achieve this by extending the exact same composable filter architecture we've already built, demonstrating its power and flexibility.

1. Defining the Security Contracts

To build an RLS system, we need to define three core components:

A contract for the current user.
A contract for a permission record.
A contract for an entity that requires protection.

Updating the Database Context

First, we must make our DAL aware of the "current user." We previously extended our IDbCtx with DbCtxAttributes to hold the current TenantId. We will now update that same record to also hold a UserId.

// In DAL.Base/IDbCtx.cs public interface IDbCtx : IDataContext { DbCtxAttributes Attributes { get; set; } ITable<IPermissionEntity> GetPermissions(); // New! public record DbCtxAttributes( Ulid TenantId = default, Ulid? UserId = null // New! ); }

We've added two things:

Ulid? UserId: This will be set by the application (e.g., from an HTTP context) at the beginning of a request. It's nullable, which is a critical design choice. If UserId is null, our RLS system will treat the user as unauthenticated and (by default) deny all access to protected entities.
ITable<IPermissionEntity> GetPermissions(): This new method is an abstraction. Our filter logic needs to query "permissions," but it shouldn't be hard-coded to a specific Permission table. This interface-based approach allows our DbCtx implementation to provide the correct table, promoting loose coupling.

The Permission Contract (`IPermissionEntity`)

Next, we need a way to represent a permission. In our database, we've added a new permission table with a simple schema: subject_id (who has the permission) and object_id (what entity the permission is for).

To map this in code, we create a new interface:

// In DAL.Base/EntityBehavior/IPermissionEntity.cs public interface IPermissionEntity { Ulid SubjectId { get; } // The "Who" (e.g., a UserId) Ulid ObjectId { get; } // The "What" (e.g., a PostId) }

After running our scaffolder to generate the Permission entity from the new table, we simply create a partial class to apply this interface:

// In DAL.Context/Entity/Permission.cs public partial class Permission : IPermissionEntity { }

Finally, we implement the new GetPermissions() method in our DbCtx.cs file. It's a simple one-line pass-through:

// In DAL.Context/DbCtx.cs public ITable<IPermissionEntity> GetPermissions() => GetTable<Permission>();

2. The `IProtected` Interface: The RLS Filter

With our contracts in place, we can now create the "behavior" interface that will automatically apply our RLS filter. We'll call it IProtected. This interface is the heart of our new system and leverages the same [EntityFilter] attribute we used for soft-deletes and tenancy.

// In DAL.Base/EntityBehavior/IProtected.cs [EntityFilter<IProtected>(nameof(Filter))] public interface IProtected { Ulid GetPermissionObjectId(); private static IQueryable<T> Filter<T>(IQueryable<T> q, IDbCtx dbCtx) where T : IProtected => dbCtx.Attributes.UserId == null // 1. If no user is in context, return nothing. ? q.Where(_ => false) // 2. Otherwise, join with permissions and filter. : q.InnerJoin( dbCtx.GetPermissions(), (entity, perm) => perm.ObjectId == entity.GetPermissionObjectId() && perm.SubjectId == dbCtx.Attributes.UserId, (entity, perm) => entity ); }

Let's break this down, as it's the most important piece:

[EntityFilter<...>]: This attribute, as before, tells our DAL's bootstrapper to find the Filter method and apply it to any entity that implements IProtected.
Ulid GetPermissionObjectId(): This is the contract. Any entity implementing IProtected must tell the system which ObjectId to use for its permission check. This is a method, not a property, which allows for incredible flexibility, as we'll see next.
private static IQueryable<T> Filter<...>: This is the filter logic.
- The Security Check: First, it checks dbCtx.Attributes.UserId == null. If true, it returns q.Where(_ => false). This is a "fail-closed" security principle. If we don't know who the user is, they get to see nothing.
- The RLS Join: If a user is present, it performs an InnerJoin between the entity query (q) and the permissions table (dbCtx.GetPermissions()).
- The Join Condition: This is the core logic: perm.ObjectId == entity.GetPermissionObjectId() && perm.SubjectId == dbCtx.Attributes.UserId. It translates to: "Find a permission record where the ObjectId matches the ID the entity provides, AND the SubjectId matches the current user in the context."
- The Result: The final lambda (entity, perm) => entity simply returns the original entity. The InnerJoin acts as a pure filter, discarding any entity that doesn't have a matching permission record for the current user.

3. Implementation: Projected Permissions

Now, let's apply our new IProtected interface to an entity. A common scenario is that permissions aren't granted to granular entities like Comment, but rather to their parent, like Post. A user who can access a Post can access all of its Comments.

Our IProtected interface's GetPermissionObjectId() method is designed for precisely this. We can implement it on our Comment entity to return its parent Post.Id. This is the exact same "projected" logic we used for multi-tenancy.

// In DAL.Context/Entity/Comment.cs public partial class Comment : IProtected { // This is the implementation of IProtected.GetPermissionObjectId() [ExpressionMethod(nameof(GetPermissionObjectIdExpression))] public Ulid GetPermissionObjectId() => Post.Id; private static Expression<Func<Comment, Ulid>> GetPermissionObjectIdExpression() => x => x.Post.Id; }

By using Linq2Db's [ExpressionMethod], we are telling the query engine that when it sees entity.GetPermissionObjectId() inside our Filter's InnerJoin, it should substitute the expression x => x.Post.Id.

The RLS filter logic will now transparently translate to: perm.ObjectId == comment.Post.Id. The DAL will automatically join the Comment table to the Post table to get the Id for the check, all without the developer ever thinking about it.

4. The Payoff: The Final Composed Query

We have now layered four distinct, automated behaviors onto our entities:

ICreatable & IModifiable (Auditing)
IRemovable (Soft-Delete)
ITenanted (Multi-Tenancy)
IProtected (Row-Level Security)

Let's see what happens when we execute a simple business operation, like modifying a comment. We add this code to our Program.cs:

// Set DB Context parameters ctx.Attributes = new( tenant.Id, u.Id ); // ... // Try to update a protected comment entity await ctx.GetTable<Comment>() .Set(x => x.Content, "asd123") .ModifyAsync();

Remember, our custom ModifyAsync extension also automatically handles setting the ModifiedAt timestamp. The developer wrote a simple, two-line update. Our DAL, however, composes all the rules and generates the following SQL:

UPDATE [comment] SET [content] = 'asd123', -- 1. "ModifyAsync" Auditing [modified_at] = '2025-11-04 12:34:11.899' FROM [post] [a_Post], [user] [a_User], -- 4. RLS Join [permission] [b] WHERE -- 2. Soft-Delete Filters (on all joined tables) [a_User].[removed_at] IS NULL AND [a_Post].[removed_at] IS NULL AND [comment].[removed_at] IS NULL AND -- 3. Projected Multi-Tenancy Filter [a_User].[tenant_id] = X'019A4EDC4AD87A53C22679FA88F15885' AND -- Joins for projections [comment].[post_id] = [a_Post].[id] AND [a_Post].[user_id] = [a_User].[id] AND -- 4. Projected Row-Level Security Filter [b].[object_id] = [a_Post].[id] AND [b].[subject_id] = X'019A4EDC4ADE42CA89BA742103A7A723'

This query is a perfect demonstration of our architecture's power:

Auditing: ModifyAsync correctly injected the modified_at SET clause.
Soft-Delete: The [removed_at] IS NULL filter was applied to comment, post, AND user.
Multi-Tenancy: The projected tenancy filter ([a_User].[tenant_id] = ...) is present, ensuring we don't even see comments from other tenants.
Row-Level Security: The new IProtected filter joined the permission table ([b]) and correctly filtered on the Post ID ([b].[object_id] = [a_Post].[id]) and the current User ID ([b].[subject_id] = ...).

The developer is completely abstracted from this complexity. They just write business logic, and the DAL guarantees that auditing, soft-deletes, tenancy, and row-level security are all correctly and automatically enforced.

Conclusion

With the addition of composable row-level security, our enterprise DAL framework is now feature-complete on its core data integrity and security goals. We have proven that a thoughtful architecture built on interfaces, expression trees, and composable filters can eliminate entire classes of common bugs and security vulnerabilities.

By separating the definition of a behavior (the interface) from its implementation (the filter logic), we've created a system that is robust, testable, and incredibly easy to extend.

As always, the complete, working implementation for this post is available in our GitHub repository: https://github.com/ByteAether/EnterpriseDal/tree/part6

In our next post, we will address the final piece of our auditing system: automatically populating the CreatedBy and ModifiedBy fields, leveraging the new UserId we just added to our DbCtxAttributes.

Announcing ByteAether.Ulid 1.3.2: .NET 10 Support and Optimized Design

2025-11-14T00:00:00Z

We are excited to announce the release of ByteAether.Ulid version 1.3.2, which is now available on NuGet. This release introduces official support and dedicated binaries for the new .NET 10 platform, continuing our mission to provide the most performant, secure, and specification-compliant ULID (Universally Unique Lexicographically Sortable Identifier) implementation for the .NET ecosystem.

For those new to the project, ByteAether.Ulid provides a robust solution engineered to solve critical, often-overlooked issues in unique identifier generation, such as reliable overflow handling and secure monotonic generation.

Embracing .NET 10 and Finalizing C# 14 Features

The primary feature of version 1.3.2 is the inclusion of build artifacts specifically compiled against the .NET 10 SDK.

This release also solidifies our use of modern C# features. We were an early adopter of C# 14's "preview" features, specifically the field keyword. With the official release of .NET 10, we can now move from LangVersion "preview" to "latest," locking in the benefits this feature provides.

We use this feature in our GenerationOptions record to perform "fail-fast" validation. By validating a property once during its init assignment, we avoid all validation overhead on subsequent get operations or, more importantly, inside the Ulid.New() hot path.

For example, here is how we ensure that the Monotonicity property is always set to a valid enum value:

public MonotonicityOptions Monotonicity { get; init => field = Enum.IsDefined(typeof(MonotonicityOptions), value) ? value : throw new ArgumentOutOfRangeException( nameof(Monotonicity), value, "Invalid monotonicity option." ); } = MonotonicityOptions.MonotonicIncrement;

This pattern provides a critical optimization. The validation logic runs a single time when the GenerationOptions object is constructed, ensuring that any call to Ulid.New() using these options operates with pre-validated, zero-overhead configuration.

A Deeper Look: Our Multi-Targeting Strategy

Our NuGet package ships distinct, optimized artifacts for a wide range of targets:

.NET 10
.NET 9
.NET 8
.NET 7
.NET 6
.NET 5
.NET Standard 2.1
.NET Standard 2.0

This multi-targeting strategy is fundamental to our performance promise. We avoid the "lowest common denominator" approach of only shipping a .NET Standard 2.0 assembly.

When you install ByteAether.Ulid in a .NET 10 project, NuGet automatically selects the .NET 10 binary. This binary is compiled with all the latest JIT intrinsics and BCL improvements. Our codebase is rich with conditional compilation, allowing us to use the most powerful APIs available on each platform.

For example, our parsing (Ulid.Parse()) and stringification (ulid.ToString()) routines use optimized ReadOnlySpan<T> and MemoryMarshal APIs on modern targets, often leveraging SIMD for Base32 operations. This is a primary reason for our benchmark-leading performance, and it's an advantage you would lose if you only consumed a .NET Standard 2.0-compiled library.

How This Philosophy Shapes Our Core Features

This focus on performance and robust design is directly applied to the library's core features, particularly in how we handle security and reliability.

Reliable Overflow Handling

A critical, and often ignored, problem in ULID generation is the OverflowException that can occur during rapid-fire generation (many IDs in the same millisecond). While the 80-bit random component is massive, its starting value is random. This means a newly generated ULID could, by chance, have a random component already near its maximum value.

In this scenario, even a few increments (especially multi-byte random increments) could cause it to overflow. Our library programmatically prevents this by intelligently incrementing the 48-bit timestamp component by 1ms when an overflow is imminent, ensuring continuous, error-free generation.

We've written a detailed analysis of this problem and our solution here: Prioritizing Reliability: When Milliseconds Aren't Enough

Secure and Configurable Generation

The GenerationOptions class, which benefits from the field keyword mentioned earlier, is the key to our advanced security and performance tuning.

It allows you to configure MonotonicityOptions (e.g., MonotonicRandom1Byte) to defeat enumeration attacks, a vulnerability in simple +1 incrementors. It also lets you control the IRandomProvider used for both the initial random bytes and the monotonic increments. This design provides a nuanced balance, allowing for a fast, non-blocking pseudo-random incrementor while using a cryptographically secure generator for the initial seed.

You can read a deep dive into these options and their security implications here: ByteAether.Ulid v1.3.0: Enhanced ULID Generation Control and Security

Conclusion

The 1.3.2 release of ByteAether.Ulid, with its .NET 10 support, continues our commitment to providing a ULID implementation that is fast, secure, and meticulously spec-compliant.

Our aggressive multi-targeting strategy ensures your application uses the most optimized code for its platform, and our forward-looking adoption of C# features allows us to build a cleaner, faster, and more reliable API.

We encourage all architects and senior engineers who value performance, security, and specification-compliance to adopt ByteAether.Ulid for their identifier generation needs.

Get the package on NuGet: https://www.nuget.org/packages/ByteAether.Ulid/
```
dotnet add package ByteAether.Ulid
```
Explore the code, read the full README, and contribute on GitHub: https://github.com/ByteAether/Ulid

Building an Enterprise Data Access Layer: Composable Multi-Tenancy Filtering

2025-11-11T00:00:00Z

In our previous articles, we established a robust foundation for our enterprise Data Access Layer (DAL). We began with a database-first approach using C# and Linq2Db, then implemented automated auditing for CreatedAt and ModifiedAt timestamps. Most recently, we engineered a powerful, composable global query filter system to handle soft-deletes transparently. This architecture was designed for extensibility, and in this post, we will leverage that investment to tackle one of the most critical cross-cutting concerns in enterprise software: multi-tenancy.

Multi-tenancy ensures that one tenant's data is strictly isolated from another's. A failure in this area is not a minor bug, but a critical security breach. Our goal is to enforce this isolation at the lowest possible level—the DAL—to guarantee that it is impossible for business logic to accidentally query data from the wrong tenant.

We will extend our entity behavior model by introducing an ITenanted interface, update our database context to be tenant-aware, and enhance our scaffolding interceptor for automation. Crucially, we will also solve the complex problem of "projected tenancy," where an entity's tenant affiliation is derived from a related entity.

The complete source code for this part is available on GitHub: https://github.com/ByteAether/EnterpriseDal/tree/part5.

1. Establishing Tenant Context in the DAL

Before our DAL can filter by tenant, it needs to know the identity of the current tenant for any given operation. This context is typically derived from an HTTP request, a message queue header, or a similar scope. We need a clean mechanism to pass this information down to our database context.

Previously, our IDbCtx was a simple marker interface. We will now extend it to carry request-scoped attributes, starting with the TenantId.

File: DAL.Base/IDbCtx.cs

namespace DAL.Base; public interface IDbCtx : IDataContext { DbCtxAttributes Attributes { get; set; } public record DbCtxAttributes(Ulid TenantId = default); }

By adding the Attributes property, we provide a dedicated, extensible home for contextual data. We use a C# record for DbCtxAttributes to create a simple, immutable data carrier. The IDbCtx implementation (our DbCtx class) will be responsible for initializing this property. In a real application, this would be done via dependency injection at the beginning of a request scope, making the current TenantId available for the lifetime of that request.

For our demonstration, we will manually set this value in Program.cs before executing any queries. This simulates how a tenant's context would be established at the start of an operation.

File: App/Program.cs (Addition)

var tenantId = Ulid.New(); ctx.Attributes = new(TenantId: tenantId);

While we use a new Ulid here, the key is that this specific value will later appear in the generated SQL WHERE clause, confirming that our filter is using the context we've provided.

2. Defining the Tenancy Contract: The `ITenanted` Interface

Following the pattern established with ICreatable and IRemovable, we will define tenancy as an entity behavior through a new interface. This interface serves two purposes: it enforces a contract that the entity must expose a TenantId, and it hooks into our global filter system.

File: DAL.Base/EntityBehavior/ITenanted.cs

namespace DAL.Base.EntityBehavior; [EntityFilter<ITenanted>(nameof(Filter))] public interface ITenanted : IEntity { Ulid TenantId { get; } private static IQueryable<T> Filter<T>(IQueryable<T> q, IDbCtx ctx) where T : ITenanted => q.Where(x => x.TenantId == ctx.Attributes.TenantId); }

This implementation is concise but powerful, directly leveraging our previous work:

Ulid TenantId { get; }: This property contract mandates that any class implementing ITenanted must provide a TenantId getter. This is the key piece of information needed for filtering.
[EntityFilter<ITenanted>(nameof(Filter))]: This is the connection to our composable filter architecture. We are associating the ITenanted interface with a specific filter-providing method named Filter.
private static IQueryable<T> Filter(...): This method contains the filtering logic itself. It receives the current queryable (q) and the database context (ctx). It then appends a standard LINQ Where clause, comparing the entity's TenantId with the TenantId we stored in the context's Attributes.

When the DAL is initialized, our MappingSchema.ApplyEntityFilters<DbCtx>() helper will discover this attribute and automatically apply this Where clause to every query against any entity that implements ITenanted.

3. Automating Interface Scaffolding

To maintain our database-first philosophy, we must ensure that our generated entity classes automatically implement the ITenanted interface if their corresponding database tables contain a tenant_id column. This task is perfectly suited for our custom scaffolding interceptor.

We will add a simple check to the interceptor's logic.

File: DAL.ScaffoldInterceptor/Interceptor.cs (Addition)

// ITenanted var tenantIdField = entityModel.Columns.FirstOrDefault(x => x.Property.Name == nameof(ITenanted.TenantId) ); if (tenantIdField is not null) { addedInterfaces.Add(typeof(ITenanted)); }

This code snippet inspects the columns of the entity being scaffolded. If it finds a column that maps to a property named TenantId, it adds ITenanted to the list of interfaces for the generated partial class. With this change, entities like user which have a direct tenant_id column will be automatically protected by our tenancy filter without any manual intervention.

4. The Advanced Case: Projected Tenancy

The true test of our architecture is not in handling direct foreign keys, but in its ability to manage more complex, indirect relationships. Consider the post table. Its schema does not contain a tenant_id column. However, a post is unequivocally owned by a tenant because it belongs to a user, and that user belongs to a tenant. The Post entity's tenancy is therefore projected from its parent User entity.

Our DAL must enforce this projected relationship as a filtering rule. We need to make the Post entity implement ITenanted, but how do we implement the TenantId property when there is no backing column?

The solution lies in creating an expression-based property that Linq2Db can translate directly into SQL. We achieve this by manually creating a partial class for Post and using the [ExpressionMethod] attribute.

File: DAL.Context/Entity/Post.cs

namespace DAL.Context.Entity; public partial class Post : ITenanted { [ExpressionMethod(nameof(GetTenantIdExpression))] public Ulid TenantId => GetTenantIdExpression().Compile()(this); private static Expression<Func<Post, Ulid>> GetTenantIdExpression() => x => x.User.TenantId; }

Let's dissect this implementation, as it is central to the power of our DAL:

public partial class Post : ITenanted: We explicitly declare that Post conforms to the ITenanted contract. We do this manually because our scaffolder did not find a TenantId column.
private static Expression<Func<Post, Ulid>> GetTenantIdExpression(): Instead of a simple value, we define the logic for retrieving the TenantId as an expression tree. The expression x => x.User.TenantId is not just executable C# code, but it is a data structure that represents the navigation from a Post (x), through its User property, to that user's TenantId. Linq2Db is designed to parse these expression trees and convert them into the corresponding SQL, which in this case involves an INNER JOIN to the user table.
[ExpressionMethod(nameof(GetTenantIdExpression))]: This Linq2Db attribute is the magic that connects the property to the expression tree. When Linq2Db encounters post.TenantId inside a LINQ query (like the one in our ITenanted.Filter method), this attribute instructs it to substitute the SQL translation of the GetTenantIdExpression method's return value.
public Ulid TenantId => GetTenantIdExpression().Compile()(this);: This line handles the case where the TenantId property is accessed on an already-materialized Post object in C# memory, outside of a database query. In this scenario, Linq2Db is not involved, and the [ExpressionMethod] attribute has no effect. We must provide a valid C# implementation. We take our expression tree, .Compile() it into a runnable delegate, and then invoke it for the current Post instance (this). For performance-critical code, this compiled delegate could be cached, but we have kept it simple for clarity.

This elegant solution allows the TenantId property to work seamlessly both within database queries (translating to SQL) and on in-memory objects (executing as C# code).

5. Observing Composable Filters in Action

We have now implemented all the necessary components. The ITenanted interface defines the filter, the scaffolder applies it to entities with a direct TenantId, and we have manually implemented it for the Post entity using a projected property.

Let's verify that it all works together. We add a simple query to our application's entry point and inspect the generated SQL.

File: App/Program.cs (Addition)

// Set DB Context parameters ctx.Attributes = new( tenant.Id ); // ... // Get posts that are tenanted through a user await ctx.GetTable<Post>() .ToListAsync(); Console.WriteLine(ctx.LastQuery);

Executing this code produces the following SQL:

SELECT [x].[id], [x].[user_id], [x].[title], [x].[content], [x].[created_at], [x].[modified_at], [x].[removed_at] FROM [post] [x] INNER JOIN [user] [a_User] ON [x].[user_id] = [a_User].[id] WHERE [a_User].[removed_at] IS NULL AND [a_User].[tenant_id] = X'0199DD7C56CCCB4521596E010C8BED67' AND [x].[removed_at] IS NULL

This output is a perfect confirmation of our architecture's capabilities. A simple call to ToListAsync() on the Post table has triggered a cascade of automated, composed filters:

INNER JOIN [user] [a_User] ...:
Linq2Db generated this join automatically because the ITenanted filter on Post required access to User.TenantId via our ExpressionMethod.
WHERE ... [a_User].[tenant_id] = ...:
This is our new tenancy filter in action, correctly applied to the joined user table.
WHERE ... [x].[removed_at] IS NULL:
The soft-delete filter for the Post entity is present, as expected from our previous work.
WHERE ... [a_User].[removed_at] IS NULL:
The soft-delete filter for the User entity has also been applied to the joined table. Our system correctly aggregates filters for all entities involved in the query.

This demonstrates the power of composable filters. Each rule (soft-delete, tenancy) is defined independently, yet the system correctly combines them into a single, comprehensive WHERE clause, ensuring data integrity and security automatically.

Conclusion

In this article, we successfully implemented automated, non-bypassable multi-tenancy filtering by building upon our existing architectural foundation. By defining tenancy as a behavioral interface and leveraging Linq2Db's ExpressionMethod, we were able to handle both direct and complex projected tenancy relationships with equal elegance. The final generated SQL proves that our composable filter system is robust, correctly layering multi-tenancy rules on top of soft-delete rules for all entities involved in a query.

This approach significantly reduces the risk of data leakage and removes the burden of security filtering from the business logic developer, fulfilling a core requirement of a true enterprise DAL.

You can review the complete implementation for this stage of the project on GitHub: https://github.com/ByteAether/EnterpriseDal/tree/part5.

Moving forward, we will tackle an even more granular security challenge: a generic, row-based permission system. The goal is to create a mechanism where any entity can be protected, requiring users to have explicit permission for that specific row in the database. If a user lacks the required permission, the entity will be automatically and transparently filtered from all query results, abstracting this complex conditional logic away from the business layer.

Building an Enterprise Data Access Layer: Automated Soft-Delete

2025-11-04T00:00:00Z

Welcome to the fourth installment of our series on building a robust, enterprise-grade Data Access Layer (DAL) in C#. In our previous post, we established a powerful automated auditing system to track entity creation and modification times (CreatedAt/ModifiedAt). Now, we will tackle another critical enterprise requirement: soft-delete.

In many systems, physically deleting data (DELETE FROM ...) is unacceptable. Regulatory compliance, audit trails, and the simple need for data recovery demand that records are preserved, even when a user "deletes" them. The standard solution is soft-deletion, where a record is marked as inactive instead of being removed.

This post will detail how we implement a fully automated, transparent, and secure soft-delete mechanism. We will not only intercept delete operations but also ensure that soft-deleted records are automatically filtered out of all read operations, including through entity associations.

The complete code for this part of the series is available on our GitHub repository: https://github.com/ByteAether/EnterpriseDal/tree/part4.

The Soft-Delete Contract: The `IRemovable` Interface

Consistent with our architecture, we define entity behaviors through interfaces. For soft-delete, we introduce the IRemovable interface in the DAL.Base/EntityBehavior namespace.

namespace DAL.Base.EntityBehavior; [EntityFilter<IRemovable>(nameof(Filter))] public interface IRemovable : IEntity { DateTime? RemovedAt { get; set; } private static IQueryable<T> Filter<T>(IQueryable<T> q, IDbCtx _) where T : IRemovable => q.Where(x => x.RemovedAt == null); }

It introduces a nullable RemovedAt property. When this property is NULL, the record is active. When it contains a timestamp, the record is considered deleted. Any entity that should support soft-deletion will implement this interface.

Our database schema has been updated accordingly, with a nullable removed_at DATETIME column added to all tables.

The Core Challenge: Global and Composable Query Filters

Implementing soft-delete presents two significant challenges that a naive approach cannot solve:

Ubiquitous Filtering: Soft-deleted records must be hidden from every query by default. Manually adding a Where(x => x.RemovedAt == null) clause to every data retrieval call is brittle, error-prone, and violates the core principle of our DAL, which is to handle cross-cutting concerns automatically.
Filtering Through Associations: This is a more subtle but critical problem. Imagine fetching a Post entity and then accessing its associated Comments collection. The DAL must ensure that any soft-deleted comments are automatically filtered from that collection. A simple WHERE clause on the initial Post query will not propagate to lazily or eagerly loaded associations.

The solution is to use Global Query Filters, a feature supported by ORMs like Linq2Db and Entity Framework Core. A global filter is a WHERE condition that the ORM automatically appends to every query for a specific entity type.

However, these ORMs typically allow only a single filter expression per entity. Our architectural vision requires multiple, independent behaviors (soft-delete, multi-tenancy , row-level security), each potentially contributing its own filter. An entity could implement IRemovable and ITenanted, requiring two separate filters to be applied simultaneously.

A Composable Architecture for Global Filters

To overcome this limitation, we have engineered a system to aggregate multiple filter expressions into a single, cohesive filter for each entity. This logic is encapsulated within the new DAL.Base/EntityFilter folder.

The system works in three main steps:

Declaration: We use a custom attribute, [EntityFilter<T>(nameof(MethodName))], to associate a filtering method with an interface or class. As seen in the IRemovable interface code above, we declare that its filter logic is located in a static method named Filter. This makes each behavioral interface self-contained.
Discovery & Aggregation: We created a helper that, upon database context initialization, scans all our DAL entities (classes implementing IEntity). For each entity, it traverses its entire inheritance tree including all implemented interfaces. It collects all lambda expressions from the filter methods declared via the EntityFilter attribute. These individual expressions are then combined into a single, larger lambda expression using Expression.AndAlso.
Application: The final, aggregated expression is then applied as a single global filter to the entity using Linq2Db's mapping schema. We trigger this entire process with a single call in our database context DbCtx.InitDataContext():
```
... MappingSchema.ApplyEntityFilters<DbCtx>(); ...
```

This architecture is incredibly flexible. It allows us to define filtering logic alongside the relevant behavior (like IRemovable or, in the future, ITenanted), and the DAL automatically composes these rules at runtime.

Integrating Soft-Delete into the DAL

With the filter aggregation system in place, we can now integrate the soft-delete logic.

1. Automated Scaffolding (`Interceptor.cs`)

Our custom scaffolding interceptor is extended to automatically add the IRemovable interface to any generated entity partial class that has a corresponding RemovedAt column in the database. This ensures our C# entity model stays perfectly in sync with our database-first philosophy.

2. Overriding Delete Operations (`CrudExtensions.cs`)

Next, we introduce new RemoveAsync extension methods that replace direct calls to Linq2Db's DeleteAsync. These methods contain the core soft-delete logic.

public static Task<int> RemoveAsync<T>( this IQueryable<T> source, CancellationToken cancellationToken = default ) where T : class { // Check if the entity type T implements IRemovable if (typeof(IRemovable).IsAssignableFrom(typeof(T))) { // If so, build an UPDATE query instead of a DELETE return source .Set(x => ((IRemovable)x).RemovedAt, DateTime.UtcNow) .ModifyAsync(cancellationToken); // Reuse our existing ModifyAsync } // Otherwise, perform a hard delete return source.DeleteAsync(cancellationToken); }

This implementation is transparent to the developer. When they call RemoveAsync on a query for an IRemovable entity, the DAL automatically translates it into an UPDATE statement that sets the RemovedAt timestamp. By cleverly chaining this into our existing ModifyAsync method, we also get ModifiedAt auditing for free.

Verification: Seeing It in Action

Let's validate our implementation. We can write a simple test in Program.cs to remove a user and inspect the generated SQL.

Code in Program.cs:

// Assuming 'ctx' is our DbCtx instance and 'u' is a User entity await ctx.GetTable<User>() .Where(x => x.Id == u.Id) .RemoveAsync(); Console.WriteLine(ctx.LastQuery);

Generated SQL Output:

UPDATE [user] SET [removed_at] = '2025-10-10 10:30:31.029', [modified_at] = '2025-10-10 10:30:31.029' WHERE [user].[removed_at] IS NULL AND [user].[id] = X'0199CDAC13F5AB8EF21DB4A49A36D2F5'

The output confirms our success. The DELETE operation was transparently converted into an UPDATE that sets both removed_at and modified_at. Crucially, notice the WHERE [user].[removed_at] IS NULL clause. Our global filter is automatically applied even to the UPDATE operation itself, ensuring we don't try to re-delete an already deleted record. Any subsequent SELECT query for this user will now automatically fail to find it, as it will not satisfy the global filter.

Conclusion and Next Steps

In this post, we have successfully implemented a comprehensive and automated soft-delete system. By building a composable global filter architecture, we have not only solved the immediate challenge but also laid a robust foundation for future DAL capabilities. Our DAL now automatically handles soft-deletes and ensures data integrity across all queries and associations, preventing common security and consistency issues.

The powerful filter system we built is now ready for its next major task: multi-tenancy. In the next article, we will leverage this exact architecture to automatically isolate data between different tenants, preventing one of the most critical types of data leakage in SaaS applications.

For a deeper dive into the implementation, please explore the source code on our GitHub repository: https://github.com/ByteAether/EnterpriseDal/tree/part4.

Building an Enterprise Data Access Layer: Automated Auditing

2025-10-24T00:00:00Z

In our previous posts, we laid the foundation for our enterprise Data Access Layer (DAL). We established our core principles: a database-first philosophy, the use of C# and Linq2Db, and a commitment to automating cross-cutting concerns to enhance security and data integrity. We also structured our project, set up a scaffolding interceptor to enrich our auto-generated entities, and chose ULIDs as our primary keys for their performance benefits.

This post will build directly on that foundation. We will implement one of the most common and critical DAL features: automated audit fields. Specifically, we will ensure that CreatedAt and ModifiedAt timestamps are automatically and correctly populated for every entity, without requiring any manual intervention from the developer using the DAL. This automation is key to preventing data inconsistencies and reducing cognitive load on engineers.

A Philosophical Shift: Technical vs. Business-Logical CRUD

Before diving into the implementation, it is important to introduce a conceptual distinction that will guide our design. In software development, we often use the acronym CRUD (Create, Read, Update, Delete) to describe data operations. However, these terms often conflate low-level database actions with high-level business logic.

To build a truly robust DAL, we must separate these concepts:

Technical CRUD: These are the raw database commands: INSERT, UPDATE, DELETE. They represent the fundamental operations the database engine can perform. In our DAL, these will be the underlying methods provided by Linq2Db.
Business-Logical CRUD: These are higher-level abstractions that represent business intent: CREATE, MODIFY, REMOVE. A single business-logical operation might involve multiple technical operations, validation, and the application of cross-cutting concerns like auditing or security.

Our goal is to expose the business-logical methods (CREATE, MODIFY, REMOVE) to the application's business logic layer, while discouraging the direct use of the technical methods (INSERT, UPDATE, DELETE). By doing so, we guarantee that all our automated rules (such as setting audit fields, enforcing soft-delete, or applying multi-tenancy filters) are always executed.

For now, this separation is a matter of developer discipline. In a future post, we may explore building a custom Roslyn (static code) analyzer that warns an engineer if they attempt to call a technical CRUD method directly from a higher-level service, thus enforcing this architectural pattern at compile time.

Step 1: Defining Behavior with `ICreatable` and `IModifiable`

To apply auditing logic selectively, we first need a way to identify which entities require it. We achieve this by defining "entity behavior" interfaces. For this feature, we will add two new interfaces to our DAL.Base/EntityBehavior directory:

ICreatable: This interface signifies that an entity has a creation timestamp.

public interface ICreatable : IEntity { DateTime CreatedAt { get; set; } }

IModifiable: This interface signifies that an entity has a modification timestamp.

public interface IModifiable : IEntity { DateTime ModifiedAt { get; set; } }

These interfaces are simple contracts. An entity implementing ICreatable guarantees it has a CreatedAt property. This allows us to write generic extension methods that can operate on any entity fulfilling this contract.

Step 2: Evolving the Database and Scaffolding

Following our database-first approach, the next step is to update our database schema. We add created_at DATETIME not null and modified_at DATETIME not null columns to all four of our tables: tenant, user, post, and comment.

With the database schema updated, we can enhance our scaffolding interceptor. In addition to adding the IEntity and IIdentifiable<Ulid> interfaces as it did before, the interceptor will now inspect the properties of each table during code generation.

If a table contains a property named CreatedAt, the interceptor will automatically add ICreatable interface to the generated partial class definition.
If a table contains a property named ModifiedAt, it will add IModifiable interface.

After running the scaffolding tool, our generated User entity, for example, will now have a signature like this in DbCtx.generated.cs:

public partial class User : IEntity, IIdentifiable<Ulid>, ICreatable, IModifiable { // ... generated properties }

This powerful combination of a database-first approach and an intelligent interceptor ensures our C# entity definitions always stay synchronized with the database schema and its intended behaviors, without manual intervention.

Step 3: Implementing the Business Logic in `CrudExtensions.cs`

Now that our entities automatically implement the correct interfaces, we can create the extension methods that constitute our business-logical CREATE and MODIFY operations. We'll place these in a new file, DAL.Base/CrudExtensions.cs.

The `CreateAsync` Method

The CreateAsync method is an extension on DbCtx. It takes either an entity object or an enumerable of them, automatically sets the audit fields, and then calls the underlying technical INSERT operation.

public static async Task<long> CreateAsync<T>( this DbCtx ctx, IEnumerable<T> entities, CancellationToken cancellationToken = default ) where T : class, IEntity => ( await ctx.BulkCopyAsync( entities.Select(e => { if (e is ICreatable creatable && creatable.CreatedAt == default) { creatable.CreatedAt = DateTime.UtcNow; } if (e is IModifiable updateable && updateable.ModifiedAt == default) { updateable.ModifiedAt = DateTime.UtcNow; } return e; } ), cancellationToken ) ).RowsCopied; public static Task<long> CreateAsync<T>( this DbCtx ctx, T entity, CancellationToken cancellationToken = default ) where T : class, IEntity => ctx.CreateAsync([entity], cancellationToken);

By checking the interfaces, these methods correctly handle any entity. If an entity only implements ICreatable, only CreatedAt is set. If it implements both, both timestamps are set.

The `ModifyAsync` Method

The ModifyAsync methods are slightly different. They are extensions on either DbCtx or IQueryable<T>, designed to work with Linq2Db's fluent update syntax.

public static Task<int> ModifyAsync<T>( this DbCtx ctx, T entity, CancellationToken cancellationToken = default ) where T : class, IEntity { if (entity is IModifiable updateable) { updateable.ModifiedAt = DateTime.UtcNow; } return ctx.GetTable<T>().UpdateOptimisticAsync(entity, cancellationToken); } public static Task<int> ModifyAsync<T>( this IUpdatable<T> source, CancellationToken cancellationToken = default ) where T : class { if (typeof(IModifiable).IsAssignableFrom(typeof(T))) { source = source.Set( x => Sql.Property<DateTime>(x, nameof(IModifiable.ModifiedAt)), DateTime.UtcNow ); } return source.UpdateAsync(cancellationToken); } public static Task<int> ModifyAsync<T>( this IQueryable<T> source, CancellationToken cancellationToken = default ) where T : class => source.AsUpdatable().ModifyAsync(cancellationToken);

These methods cleverly inspect the generic type T. If T implements IModifiable, it injects a .Set() call to update the ModifiedAt field with the current timestamp before executing the final UpdateAsync() call or assigns the current timestamp to an entity's property. This ensures that any update operation expressed through this fluent API is properly audited.

A Note on `IQueryExpressionInterceptor`

You might be wondering if there is a more integrated way to achieve this within Linq2Db, rather than creating wrapper extension methods. Linq2Db provides a IQueryExpressionInterceptor interface, which is designed to intercept every query expression before its translation into SQL. In theory, this would be the perfect place to inject our auditing logic.

Unfortunately, as of this writing, the implementation of this interceptor is not consistently triggered across all operation types. For example, it does not fire for INSERT operations or for calls to IDataContext.UpdateAsync<T>(), although it does trigger for the fluent IUpdatable<T>.UpdateAsync() method. This inconsistency makes it unsuitable for building a reliable, all-encompassing auditing system.

Should this behavior be fixed in a future version of Linq2Db to reliably intercept all query expressions, it would offer a more elegant solution. We could then centralize our auditing logic in the interceptor and use the standard InsertAsync and UpdateAsync methods directly. This would eliminate the need for our custom CreateAsync and ModifyAsync wrappers and the potential need for a static code analyzer to enforce their use. If such an update occurs, we will certainly explore it in a follow-up article.

Seeing it in Action

With all the pieces in place, we can verify that our implementation works as expected. We can write a small test in Program.cs to create and then modify a User entity. Notice that our C# code never explicitly provides a value for CreatedAt or ModifiedAt.

await ctx.BeginTransactionAsync(); // Create entity var u = new User { Id = Ulid.New(), Username = "asd123" }; await ctx.CreateAsync(u); Console.WriteLine(ctx.LastQuery); // Modify entity await ctx.GetTable<User>() .Where(x => x.Id == u.Id) .Set(x => x.Username, "asd1234") .ModifyAsync(); Console.WriteLine(ctx.LastQuery); await ctx.RollbackTransactionAsync();

Executing this code produces the following SQL, captured from Linq2Db's LastQuery property:

INSERT INTO [user] ( [id], [tenant_id], [username], [created_at], [modified_at] ) VALUES (X'0199C31CC424CFC7293147E8A6AE578C',X'00000000000000000000000000000000','asd123','2025-10-08 09:17:46.472','2025-10-08 09:17:46.473') UPDATE [user] SET [username] = 'asd1234', [modified_at] = '2025-10-08 09:17:46.506' WHERE [user].[id] = X'0199C31CC424CFC7293147E8A6AE578C'

The output confirms our success. The INSERT statement correctly includes values for both created_at and modified_at. The UPDATE statement automatically includes the SET clause for modified_at. Our DAL now handles these audit fields transparently, reliably, and without any developer effort.

The complete implementation for this part of the series can be found on GitHub: https://github.com/ByteAether/EnterpriseDal/tree/part3.

Conclusion and Next Steps

In this post, we successfully implemented automated auditing for creation and modification timestamps. We introduced the critical distinction between technical and business-logical CRUD operations, defined entity behaviors using interfaces, and leveraged our scaffolding interceptor to automate their implementation. Finally, we created generic extension methods that apply auditing rules consistently across all relevant entities.

In the next episode, we will tackle another core DAL capability: Soft-Delete. This feature is similar in that it will rely on a new interface, but it introduces an additional layer of complexity: we must also implement a global query filter to automatically exclude soft-deleted records from all read operations, a crucial step in preventing data leakage and ensuring application correctness.

Building an Enterprise Data Access Layer: Database and Code Structure

2025-10-07T00:00:00Z

Welcome back to our series on building a robust, enterprise-grade Data Access Layer (DAL) with C# and Linq2Db. In our previous post, we established the core principles and non-negotiable capabilities our DAL must possess, including automatic multi-tenancy filtering, soft-delete, and auditing. Now, we'll begin laying the foundation for this powerful system by defining the database schema and the initial code structure.

This post will explore the deliberate technical choices we have made for this project's foundation. While these decisions may seem straightforward at first glance, each one serves a specific purpose in building a scalable, secure, and maintainable data layer that abstracts complexity away from the business logic.

The Database-First Philosophy

Before we define the structure, let's address the approach. This project is firmly rooted in a database-first philosophy. In my view, the database is a core engineering artifact and should be treated as such, designed and managed using purpose-built database engineering tools. The schema is the source of truth, and our code should be a faithful reflection of that schema.

This approach ensures that database constraints, indexes, and data types are optimized for the database engine itself, rather than being an afterthought generated by an Object-Relational Mapper (ORM). It provides a clear separation of concerns, allowing database administrators and backend engineers to collaborate on a well-defined and performant schema.

Our Core Data Model

For this series, we will build a simple data model to represent a multi-tenant blogging platform. The model consists of four essential tables, each with a clear purpose and relationship to the others.

tenant: This table represents the top-level entity in our multi-tenant application. Every user belongs to a single tenant, and all data within a tenant is isolated from others. It contains a unique id and a name.
user: This table holds our user accounts. Each user is associated with a specific tenant via a foreign key (tenant_id). It also contains a username.
post: A post is a content unit created by a user. It references the user via a foreign key (user_id). A post has a title and the main content.
comment: This table stores comments on a post. Each comment is linked to a post via a foreign key (post_id) and contains its content.

The relationships are as follows:

comment.post_id references post.id
post.user_id references user.id
user.tenant_id references tenant.id

This simple structure allows us to demonstrate how the DAL can automatically enforce rules like multi-tenancy and permissions by navigating these relationships.

The Power of the ULID

A cornerstone of our database design is the choice of ULID (Universal Unique Lexicographically Sortable Identifier) as the primary key for all tables. A ULID is a 128-bit identifier that combines the uniqueness of a UUID with the sortable properties of a timestamp.

In our C# code, we will use the ByteAether.Ulid library. This library provides a native Ulid type that is specifically designed for this purpose. In the database, ULIDs are stored as 128-bit binary, which is the most efficient representation.

The key advantage of ULIDs is their sortability. Because the first 48 bits of a ULID are a timestamp, when you sort a column of ULIDs, you are also sorting by the order of creation. This is incredibly beneficial for performance on append-only tables, as new records are always written to the end of the table, minimizing fragmentation. It also makes it easy to find the most recent records without a separate timestamp column.

For databases like SQLite, this property allows us to declare our tables WITHOUT ROWID. This SQLite-specific feature, when used with a ULID primary key, removes the default internal 64-bit integer row identifier, making the ULID the sole source of record identity and order. Since ULIDs are inherently sortable, the table is naturally clustered by creation time, which optimizes read operations on the most recent data.

Here is the full SQL schema for our four tables:

create table tenant ( id ulid not null primary key, name VARCHAR(64) not null unique ) without rowid; create table user ( id ulid not null primary key, tenant_id ulid not null references tenant, username VARCHAR(64) not null ) without rowid; create table post ( id ulid not null primary key, user_id ulid not null references user, title varchar(64) not null, content text not null ) without rowid; create table comment ( id ulid not null primary key, post_id ulid not null references post, content text not null ) without rowid;

The Scaffolding and Code Structure

With our database schema defined, we now turn to the C# code. We will use Linq2Db's built-in scaffolding tool to generate our C# entity classes and a database context. However, we will enhance this process with a custom scaffolding interceptor.

Our core code structure will be organized into a few key areas:

`DAL.Base`

This namespace holds the fundamental interfaces that all of our entities may inherit from. We're keeping it simple for now, with two interfaces:

IEntity: A simple marker interface that all of our data access layer entities will inherit. While it is empty now, its existence allows us to build generic services and behaviors that can be applied to any entity in the DAL.
IIdentifiable<T>: An interface that marks any entity that has a property named Id of type T. This is a crucial interface for our core services, as it allows us to build generic logic that can operate on any entity with an identifier. For example, a generic queryable.WhereId() method would require this interface.

`DAL.Context`

This namespace contains our database context and all generated entity classes. We've made a key architectural decision here: all generated classes will reside in a single file named DbCtx.generated.cs. This simplifies the regeneration process, as you only need to update a single file when the database schema changes.

DbCtx.generated.cs: This file will be created by the Linq2Db scaffolding tool. It will contain our DbCtx class, as well as partial classes for our Tenant, User, Post, and Comment entities.
DbCtx.cs: This is the complementary file for our DbCtx.generated.cs. The DbCtx class is a partial class, so we can extend it with our own methods and properties here, leaving the generated file untouched.

A key piece of the DbCtx.cs file is the partial void InitDataContext() method. This method, which is automatically called by the generated constructor in DbCtx.generated.cs, is where we will define the runtime type mapping for our Ulids. This ensures that when Linq2Db reads a ulid type from the database (as a byte array), it is correctly converted into a Ulid C# object, and vice versa. This runtime mapping is the counterpart to the design-time mapping handled by our ScaffoldInterceptor.

`DAL.Context.Entity`

This namespace is where we will create additional partial classes to extend the functionality of our generated entity classes. For example, we could create a Post.cs file to add a convenience method for getting the post's user from the database.

`DAL.ScaffoldInterceptor`

This is the "secret sauce" of our scaffolding process. We will create a class that implements ScaffoldInterceptors. This interceptor allows us to hook into the scaffolding process and customize it.

Our custom interceptor will perform two key functions:

Interface Injection: It will automatically add our IEntity and IIdentifiable<Ulid> interfaces to the generated partial entity classes.
ULID Type Mapping: It will intercept any database column with the ulid type and ensure it is properly mapped to the Ulid type from our C# library in the generated code.
Association Naming Convention: We will use the interceptor to enforce a strict and predictable naming convention for association properties. For One-To-Many relationships, we adopt a simple 's' suffix (e.g., a Post entity will have a property named Comments, not Commentaries or Commentss). This deliberate choice avoids the ambiguity and confusion that can arise from irregular pluralization in English (e.g., avoiding a scenario where a Mouse entity might generate a Mice collection). For Many-To-One relationships, we simply use the entity's singular name (e.g., a Comment entity will have a Post property).

The use of partial classes is a core tenet of this approach. It gives us the best of both worlds: we have the convenience of an automatically generated code base that stays in sync with our database schema, while also having the freedom to extend and customize our models and database context without ever touching the generated code.

Looking Ahead

In this post, we've defined the bedrock of our enterprise DAL, from the database schema and the choice of ULID primary keys to the core code structure and our enhanced scaffolding process. We started simple, without implementing audit fields or a permission system. The project's root also includes a simple Program.cs file used for demonstration. This utility file connects to our SQLite database and runs simple LINQ queries (like selecting all users). Crucially, we use it to inspect the generated SQL from our LINQ expressions, rather than executing the queries and reviewing the result set. This allows us to verify that our DAL is correctly translating our C# code into performant SQL.

The full source code for this post, including the scaffolding interceptor and the completed project structure, is available at GitHub.

In the next post, we will dive into the details of implementing the crucial audit fields (CreatedAt, CreatedBy, ModifiedAt, and ModifiedBy) and the logic to automatically populate them during data operations. We'll show how the foundation we've built here makes this complex, cross-cutting concern remarkably simple to implement.

Building an Enterprise Data Access Layer: The Foundation

2025-09-25T00:00:00Z

In enterprise software development, the Data Access Layer (DAL) serves as the critical interface between an application's business logic and its underlying data store. Beyond basic CRUD operations, a robust DAL is fundamental for ensuring data integrity, security, and operational consistency. It proactively addresses cross-cutting concerns, preventing inconsistencies, defects, and potential security vulnerabilities that arise when these responsibilities are left to the business logic.

This series will detail the design and implementation of an enterprise-level Data Access Layer in C#, with a primary focus on Linq2Db. We'll demonstrate how to embed essential cross-cutting concerns directly within the DAL, ensuring their consistent application without reliance on manual enforcement within the business logic. Linq2Db's capabilities, particularly its strong support for advanced SQL features and expression tree manipulation, make it an excellent choice for building a highly customized and efficient DAL. We outline the fundamental capabilities such a DAL must provide, establishing the framework for subsequent practical implementations.

The Necessity of an Automated, Error-Resistant DAL

The lifecycle of an enterprise application involves continuous data creation, modification, and retrieval by various users and automated processes. Without a centralized, opinionated, and highly capable DAL, developers are tasked with manually implementing critical data-related behaviors across numerous service methods and business logic components. This decentralized approach is susceptible to human error, such as overlooking a filter, omitting an audit field, or mismanaging a soft-delete operation. Such oversights can lead to:

Data Inconsistencies: Records may lack complete audit information, entities might be inconsistently soft-deleted, or multi-tenancy rules may be applied unevenly.
Security Vulnerabilities: A missed TenantId filter or inadequate enforcement of row-level permissions can result in unauthorized data exposure. Such breaches carry significant legal, financial, and reputational risks.
Increased Development Overhead and Technical Debt: Manual implementation of cross-cutting concerns introduces boilerplate code, extends development cycles, and increases the probability of introducing subtle, hard-to-diagnose defects.

The core premise of this series is that these capabilities must be inherent to the DAL. The DAL should function as a guardian, automatically applying these rules and transformations, thereby offloading this responsibility from the business logic and ensuring consistent, secure, and reliable data interaction.

Core Capabilities of an Enterprise Data Access Layer

We'll now examine the critical capabilities an enterprise DAL should provide, abstracting them from the application's business logic.

1. `CreatedAt`/`ModifiedAt` Auditing

Maintaining an audit trail of when data records were created and last modified is a fundamental requirement for most enterprise applications. This temporal auditing provides insights for debugging, compliance, and understanding data evolution. Manually setting CreatedAt and ModifiedAt timestamps in the business logic for every INSERT and UPDATE operation is repetitive and prone to omission.

A sophisticated DAL should automate this process. Upon entity insertion, the DAL should automatically populate its CreatedAt property with the current timestamp. Similarly, upon any update to an existing entity, the DAL should automatically update its ModifiedAt property. This ensures that every record consistently carries its creation and last modification timestamps, without explicit action required from the business logic developer. This automation guarantees comprehensive temporal auditing across the entire dataset.

2. `CreatedBy`/`ModifiedBy` Auditing

Extending temporal auditing, it is often critical to identify the user responsible for a particular data change. This "who" information, typically represented by a User ID, enhances accountability and traceability within the audit trail. As with CreatedAt/ModifiedAt, manually populating CreatedBy and ModifiedBy fields in the business logic is a source of potential errors.

The enterprise DAL should seamlessly manage this. For new entities, it should automatically set the CreatedBy property to the ID of the current user. For updates, it should update the ModifiedBy property. The current User ID must be settable for the scope of an entire API request or a specific unit of work. The DAL will then automatically retrieve and apply this contextual User ID to the appropriate fields during persistence operations. This mechanism ensures that every data change is attributed to the responsible user, providing a complete and reliable audit history.

3. Soft-Delete

In many enterprise scenarios, physical data deletion is undesirable due to auditing requirements, data recovery needs, or the necessity of maintaining historical context. Soft-delete addresses this by marking a record as logically "deleted" rather than physically removing it.

An enterprise DAL should automate this process. When the business logic initiates a "delete" operation, the DAL should intercept this call. Instead of issuing a DELETE SQL command, it should update a designated DeletedAt property (e.g., a DateTimeOffset? nullable timestamp) on the entity. Furthermore, all standard read operations performed through the DAL must automatically filter out entities where DeletedAt is not null, unless explicitly overridden (e.g., for administrative recovery tools). This ensures that the business logic perceives soft-deleted entities as non-existent without requiring manual WHERE DeletedAt IS NULL clauses in every query. This capability is essential for data integrity and provides a safeguard against accidental data loss.

4. `TenantId` Filtering (Multi-Tenancy)

Multi-tenancy, where a single application instance serves multiple distinct organizations (tenants), is a common architectural pattern in SaaS solutions. Strict data isolation is critical: Tenant A must never access Tenant B's data. Enforcing this isolation is exceptionally challenging if left to the business logic, as every query, join, and relationship traversal would require manual TenantId filtering. A single missed filter can lead to catastrophic data leakage.

Our enterprise DAL must provide automatic TenantId filtering. For entities designated as "tenant-owned," the DAL should automatically inject a WHERE TenantId = [CurrentTenantId] clause into all read operations. Crucially, this filtering must propagate throughout all associations. If a query involves joining across multiple tables, the DAL must ensure the TenantId filter is applied appropriately at each relevant level to prevent data from other tenants from being inadvertently included. Similar to the CreatedBy/ModifiedBy capability, the TenantId must be settable for the scope of the current API request or unit of work, enabling the DAL to transparently apply it to all relevant data operations. This capability is a cornerstone of security and data isolation in multi-tenant architectures.

5. Entity-Based-Permissions (Row-Level Security)

Beyond multi-tenancy, many applications require more granular control over data visibility, often termed row-level security or entity-based permissions. This allows specific users to view certain entities while restricting others, even within the same tenant. For example, in a project management system, a user might only access tasks assigned to them or their team. Implementing this within the business logic is complex, often resulting in deeply nested conditional logic and a high risk of oversight.

An advanced DAL should fully enforce entity-based permissions. Entities themselves will define whether they are protected by the permission system. For protected entities, they will also define how the ID, upon which the permission system will operate, is derived. The DAL will then automatically apply these permission checks during all read operations, effectively filtering out rows that the current user is not authorized to see. This abstraction ensures that the business logic operates under the assumption that it only receives data the user is permitted to view, significantly simplifying development and bolstering security. The current User ID, set for the scope of the API request or unit of work, will provide the context for these permission evaluations.

6. Projected Data Support for Contextual Filtering

Both TenantId filtering and entity-based permissions introduce a common challenge: the relevant ID (e.g., TenantId or permission ObjectId) may not always be a direct property on the entity being queried. For instance, a Comment entity might not have its own TenantId but instead inherits it from its parent Post entity (this.Post.TenantId). Similarly, permissions for a Task might be based on the Id of its Project (this.Project.Id).

The enterprise DAL must provide a mechanism for entities to define how these contextual IDs are retrieved. This "projected data support" allows an entity to specify a path or a function (e.g., a LINQ expression) that the DAL can use to resolve the TenantId or the ObjectId for filtering purposes. This flexibility ensures that the DAL can correctly apply multi-tenancy and row-level security even when the relevant identifiers are not directly present on the entity itself but are accessible through its relationships, maintaining consistency and correctness across complex data models.

Why Linq2Db?

While Entity Framework Core (EF Core) is a widely adopted and powerful ORM in the .NET ecosystem, this series will primarily focus on implementing our enterprise DAL using Linq2Db. Linq2Db offers a highly flexible and performant approach to data access, particularly excelling in scenarios requiring fine-grained control over generated SQL.

One of Linq2Db's significant advantages for our purposes is its robust support for features like projected properties and direct translation of SQL window functions into LINQ queries. While not all of these advanced features may be strictly necessary for the current enterprise DAL implementation, they collectively illustrate Linq2Db's broader capabilities and its suitability for complex data manipulation. Such capabilities are crucial for efficiently implementing complex filtering and auditing mechanisms directly within the DAL, often requiring less boilerplate or specialized extension libraries compared to EF Core. While EF Core does support some of these advanced scenarios through community-contributed extension libraries, Linq2Db provides many of these features out-of-the-box, simplifying our implementation journey.

Our decision to focus on Linq2Db for this series is driven by its suitability for demonstrating how to build a highly optimized and feature-rich DAL that minimizes manual intervention and maximizes precision in data operations.

Scope of History Support

It is important to clarify that while this series will implement certain auditing functionalities, such as CreatedAt/ModifiedAt and CreatedBy/ModifiedBy fields, it will not cover full history support. Implementing a complete archive of all data at all points in time, including granular versioning and temporal querying capabilities, is a significant undertaking. However, the capabilities developed in this series are foundational and can be extended with full history support later without invalidating the core principles and implementations discussed. Our focus remains on the automated enforcement of the capabilities outlined above to enhance data consistency and security at the transactional level.

The Journey Ahead

Centralizing these essential capabilities within an enterprise-grade Data Access Layer is key to building applications that are inherently more consistent, secure, and maintainable. With Linq2Db as our primary ORM for this implementation journey, the business logic can focus solely on its core rules rather than on data access mechanics.

We encourage you to prepare your development environment for the next installment, where we will establish the foundational C# project and begin implementing the DAL with Linq2Db. Upon completion of this series, a comparative analysis may also be provided by reproducing the same solution using Entity Framework Core.

ByteAether

The Architecture of Obsession: Why ByteAether.Ulid is the Last Identifier Library You Will Ever Need

The Sortability: Why UUIDv7 Isn't the Hero We Expected

Eliminating the Overflow Exception

High-Performance, Lock-Free Concurrency

Preventing Enumeration Attacks with Random Increments

The Developer Experience: Frictionless Integration

Advanced Filtering with LINQ

Embracing the Over-Engineered

The Weight of Decisions: Solving Weighted Random Sorting at Scale

The Requirement for Ordered Fail-over

Balancing Traffic via Weighted Randomization

Implementation Logic

The Intuition and the Initial O(N2 log N) Approach

The Efraimidis-Spirakis Algorithm

Applications for Streaming Data

Building an Enterprise Data Access Layer: Automated User Auditing and Series Wrap-up

Implementing User Auditing

The Schema and Interface Contracts

Automated Scaffolding

Updating the CRUD Extensions

The IUpdatable Nuance

The Result: A Fully Automated Query

Achieving Our Goals

Future Ideas

Conclusion

Building an Enterprise Data Access Layer: Composable Row-Level Security

1. Defining the Security Contracts

Updating the Database Context

The Permission Contract (IPermissionEntity)

2. The IProtected Interface: The RLS Filter

3. Implementation: Projected Permissions

4. The Payoff: The Final Composed Query

Conclusion

Announcing ByteAether.Ulid 1.3.2: .NET 10 Support and Optimized Design

Embracing .NET 10 and Finalizing C# 14 Features

A Deeper Look: Our Multi-Targeting Strategy

How This Philosophy Shapes Our Core Features

Reliable Overflow Handling

Secure and Configurable Generation

Conclusion

Building an Enterprise Data Access Layer: Composable Multi-Tenancy Filtering

1. Establishing Tenant Context in the DAL

2. Defining the Tenancy Contract: The ITenanted Interface

3. Automating Interface Scaffolding

4. The Advanced Case: Projected Tenancy

5. Observing Composable Filters in Action

Conclusion

Building an Enterprise Data Access Layer: Automated Soft-Delete

The Soft-Delete Contract: The IRemovable Interface

The Core Challenge: Global and Composable Query Filters

A Composable Architecture for Global Filters

Integrating Soft-Delete into the DAL

1. Automated Scaffolding (Interceptor.cs)

2. Overriding Delete Operations (CrudExtensions.cs)

Verification: Seeing It in Action

Conclusion and Next Steps

Building an Enterprise Data Access Layer: Automated Auditing

A Philosophical Shift: Technical vs. Business-Logical CRUD

Step 1: Defining Behavior with ICreatable and IModifiable

Step 2: Evolving the Database and Scaffolding

Step 3: Implementing the Business Logic in CrudExtensions.cs

The CreateAsync Method

The ModifyAsync Method

A Note on IQueryExpressionInterceptor

Seeing it in Action

Conclusion and Next Steps

Building an Enterprise Data Access Layer: Database and Code Structure

The Database-First Philosophy

Our Core Data Model

The Power of the ULID

The Scaffolding and Code Structure

DAL.Base

DAL.Context

DAL.Context.Entity

DAL.ScaffoldInterceptor

Looking Ahead

Building an Enterprise Data Access Layer: The Foundation

The Necessity of an Automated, Error-Resistant DAL

Core Capabilities of an Enterprise Data Access Layer

The Intuition and the Initial O(N² log N) Approach

The `IUpdatable` Nuance

The Permission Contract (`IPermissionEntity`)

2. The `IProtected` Interface: The RLS Filter

2. Defining the Tenancy Contract: The `ITenanted` Interface

The Soft-Delete Contract: The `IRemovable` Interface

1. Automated Scaffolding (`Interceptor.cs`)

2. Overriding Delete Operations (`CrudExtensions.cs`)

Step 1: Defining Behavior with `ICreatable` and `IModifiable`

Step 3: Implementing the Business Logic in `CrudExtensions.cs`

The `CreateAsync` Method

The `ModifyAsync` Method

A Note on `IQueryExpressionInterceptor`

`DAL.Base`

`DAL.Context`

`DAL.Context.Entity`

`DAL.ScaffoldInterceptor`

1. `CreatedAt`/`ModifiedAt` Auditing

2. `CreatedBy`/`ModifiedBy` Auditing

4. `TenantId` Filtering (Multi-Tenancy)