SplatDev.Umbraco.NPoco 2.0.5

SplatDev.Umbraco.NPoco

NPoco database layer for Umbraco — provides BaseEntityRepository<T> with automatic IScopeProvider integration, ambient scope management, SuperUser identity fallback, event-driven auditing, and bulk CRUD operations. Built on top of Umbraco's native NPoco infrastructure.

Compatibility

Installation

dotnet add package SplatDev.Umbraco.NPoco

Configuration

DI registration

using SplatDev.Umbraco.NPoco;

// Register your repository implementation
builder.Services.AddScoped<IMyEntityRepository, MyEntityRepository>();

Define an entity

using NPoco;

[TableName("MyTable")]
[PrimaryKey("Id", AutoIncrement = true)]
public class MyEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime CreatedAt { get; set; }
    public int CreatedBy { get; set; }
}

Implement a repository

using SplatDev.Umbraco.NPoco;
using Umbraco.Cms.Infrastructure.Scoping;

public class MyEntityRepository : BaseEntityRepository<MyEntity>, IMyEntityRepository
{
    public MyEntityRepository(IScopeProvider scopeProvider)
        : base(scopeProvider) { }

    public async Task<IEnumerable<MyEntity>> GetActiveAsync()
    {
        return await FetchAsync("WHERE IsActive = 1 ORDER BY CreatedAt DESC");
    }
}

Usage

CRUD operations

var repo = serviceProvider.GetRequiredService<IMyEntityRepository>();

// Scope management is automatic — no need to manually begin/commit
// Each method wraps its database work in an ambient IScope

// Insert
var entity = new MyEntity { Name = "Example" };
repo.Insert(entity);

// Get by ID
var item = repo.GetById(1);

// Update
item.Name = "Updated";
repo.Update(item);

// Delete
repo.Delete(item);

// Fetch with SQL
var recent = repo.Fetch("WHERE CreatedAt > @0", DateTime.UtcNow.AddDays(-7));

Bulk operations

// Insert multiple records in one batch
var entities = Enumerable.Range(1, 100).Select(i => new MyEntity
{
    Name = $"Bulk Item {i}"
}).ToList();

repo.InsertBulk(entities);

// Update multiple records
repo.UpdateBulk(entities);

// Delete multiple records by ID
repo.DeleteBulk(new[] { 1, 2, 3, 4, 5 });

Auto-complete scopes

BaseEntityRepository<T> automatically wraps every database operation in an ambient IScope:

// No manual scope.Begin() or scope.Complete() needed
// The repository handles scope lifecycle internally

var item = repo.GetById(42);          // Auto-scoped
repo.Insert(new MyEntity());           // Auto-scoped with auto-commit
repo.Update(existingItem);             // Auto-scoped with auto-commit

SuperUser fallback

When no authenticated backoffice user is available (e.g., during scheduled tasks or background jobs), the repository automatically falls back to the SuperUser identity (-1) for audit fields like CreatedBy and UpdatedBy.

Auditing via ActionCompletedEvent

// Audit changes by subscribing to the event
MyEntityRepository.ActionCompleted += (sender, entity) =>
{
    Console.WriteLine($"Action completed on entity {entity.Id}");
    // Log, notify, or trigger downstream workflows
};

Features

• BaseEntityRepository<T> — Generic base class with full CRUD
• Automatic IScopeProvider integration — scopes managed internally
• Ambient scope auto-completion — no manual Begin()/Complete() required
• SuperUser identity fallback for non-interactive contexts
• Event-driven auditing via ActionCompletedEvent
• Bulk insert, update, and delete operations
• Uses Umbraco's native IScopeProvider and NPoco infrastructure

Dependencies

NPoco is included implicitly via Umbraco.Cms.Infrastructure — no additional NPoco package reference required.

Target Frameworks

• net8.0 — for Umbraco 13 applications (v13.12.0)
• net10.0 — for Umbraco 17 applications (v17.3.4)

SplatDev.Umbraco.NPoco — part of the SplatDev.Umbraco.Plugins suite. Licensed under MIT. © SplatDev Ltda.

Changelog

2.0.5 — 2026-08-24

Removes a dashboard screenshot that showed an error toast. It was captured against a site where this plugin's API was unreachable, so it advertised a broken dashboard. No screenshot is better than a misleading one; a replacement will be taken against a working install.

2.0.4 — 2026-08-24

Package metadata only: the listing now carries an icon and search tags, and the project and repository links point at the organisation that actually hosts this code. No code changes.

2.0.2 — 2026-08-22

• This package's README now reaches NuGet. The publish workflow discovered packages by a list of name patterns, and this one matched none of them, so it was never built or pushed by CI — the version on NuGet was placed there by hand before the README was wired up, and no release could refresh it. Discovery is now by prefix, so the package ships whenever the repo is tagged.