SlugKit.Dapper 1.0.0

SlugKit

Automatic URL-safe slug generation for EF Core and Dapper entities with scoped uniqueness, transliteration, and regeneration control. Inspired by spatie/laravel-sluggable.

Table of Contents

• Packages
• Quick Start
• Core Concepts
  • IHasSlug Interface
  • SlugAttribute
  • SlugBehavior
• Slug Generation Pipeline
• Configuration
  • Global Options
  • Reserved Slugs
  • Custom Transliterator
• EF Core Integration
  • Setup
  • Scoped Uniqueness
  • Update Behaviour
  • Query Extensions
• Dapper Integration
  • Setup
  • FindBySlugAsync
  • GetExistingSlugsAsync
• ASP.NET Core Integration
• Advanced Scenarios
  • Custom Slug Generator
  • Unicode and Non-Latin Scripts
  • Table Name Resolution (Dapper)
• Entity Examples
• Supported Frameworks

Packages

Quick Start

1. Install packages

dotnet add package SlugKit
dotnet add package SlugKit.EntityFrameworkCore   # for EF Core
dotnet add package SlugKit.Dapper                # for Dapper

2. Mark your entity

public class Article : IHasSlug
{
    public int Id { get; set; }
    public string Title { get; set; }

    [Slug(From = nameof(Title), Unique = true, MaxLength = 80)]
    public string Slug { get; set; }
}

3. Register services

// Program.cs
builder.Services.AddSlugKit(options =>
{
    options.DefaultSeparator = "-";
    options.DefaultMaxLength = 100;
    options.DefaultOnUpdate = SlugBehavior.NeverRegenerate;
    options.ReservedSlugs = ["admin", "api", "settings", "new", "edit", "delete"];
})
.UseEntityFrameworkCore<AppDbContext>()
.UseDapper();

4. Register the EF Core interceptor

// In your DbContext OnConfiguring, or when registering DbContext:
optionsBuilder.AddInterceptors(serviceProvider.GetRequiredService<SlugGenerationInterceptor>());

5. Save your entity — slug is generated automatically

var article = new Article { Title = "Hello World" };
context.Articles.Add(article);
await context.SaveChangesAsync();

Console.WriteLine(article.Slug); // "hello-world"

Core Concepts

IHasSlug Interface

All slug-bearing entities must implement IHasSlug:

public interface IHasSlug
{
    string Slug { get; set; }
}

SlugAttribute

Decorate the Slug property with [Slug] to configure generation:

[AttributeUsage(AttributeTargets.Property)]
public class SlugAttribute : Attribute
{
    public string From { get; set; }           // Source property name (required)
    public string? Scope { get; set; }         // Scoping property name (optional)
    public bool Unique { get; set; } = true;
    public int MaxLength { get; set; } = 100;
    public SlugBehavior OnUpdate { get; set; } = SlugBehavior.NeverRegenerate;
}

SlugBehavior

Slug Generation Pipeline

Given the input "Héllo, Wörld!" with MaxLength = 100:

If "hello-world" already exists, the result would be "hello-world-2", then "hello-world-3", etc.

Configuration

Global Options

services.AddSlugKit(options =>
{
    options.DefaultSeparator = "-";           // Word separator character
    options.DefaultMaxLength = 100;           // Max slug length
    options.DefaultOnUpdate = SlugBehavior.NeverRegenerate;
    options.ReservedSlugs = ["admin", "api", "settings"];
});

Individual [Slug] attribute settings always override global options.

Reserved Slugs

Slugs that match a reserved value are automatically suffixed:

// "admin" is reserved → generated slug becomes "admin-2"
var entity = new SomeEntity { Name = "Admin" };
// slug → "admin-2"

Default reserved slugs: admin, api, settings, new, edit, delete.

Custom Transliterator

Replace the default NFD-based transliterator with your own for non-Latin scripts:

public class CyrillicTransliterator : ISlugTransliterator
{
    private static readonly Dictionary<char, string> Map = new()
    {
        ['а'] = "a", ['б'] = "b", ['в'] = "v", // ...
    };

    public string Transliterate(string input)
        => string.Concat(input.Select(c => Map.TryGetValue(c, out var v) ? v : c.ToString()));
}

// Registration:
services.AddSlugKit().UseTransliterator<CyrillicTransliterator>();

EF Core Integration

Setup

Install the package:

dotnet add package SlugKit.EntityFrameworkCore

Register services and wire the interceptor into your DbContext:

// Program.cs
builder.Services.AddSlugKit(/* options */)
    .UseEntityFrameworkCore<AppDbContext>();

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    options.UseSqlServer(connectionString);
    options.AddInterceptors(sp.GetRequiredService<SlugGenerationInterceptor>());
});

Scoped Uniqueness

Use Scope to make slugs unique within a parent entity:

public class TicketTag : IHasSlug
{
    public string Name { get; set; }
    public Guid ProjectId { get; set; }

    [Slug(From = nameof(Name), Scope = nameof(ProjectId), Unique = true)]
    public string Slug { get; set; }
}

Two TicketTag rows with the same Name in different projects can share the same slug. Two rows in the same project will get "tag-name" and "tag-name-2".

Update Behaviour

// Never regenerate (default) — stable URLs
public class Page : IHasSlug
{
    public string Title { get; set; }

    [Slug(From = nameof(Title), OnUpdate = SlugBehavior.NeverRegenerate)]
    public string Slug { get; set; }
}

// Always regenerate — slug tracks title exactly
public class Article : IHasSlug
{
    public string Title { get; set; }

    [Slug(From = nameof(Title), OnUpdate = SlugBehavior.AlwaysRegenerate)]
    public string Slug { get; set; }
}

// Regenerate only when title changes
public class Post : IHasSlug
{
    public string Title { get; set; }

    [Slug(From = nameof(Title), OnUpdate = SlugBehavior.RegenerateOnChange)]
    public string Slug { get; set; }
}

Query Extensions

using SlugKit.EntityFrameworkCore.Extensions;

// Filter by slug
var article = await context.Articles.WhereSlug("hello-world").FirstOrDefaultAsync();

// Convenience single-result lookup
var article = await context.Articles.FindBySlugAsync("hello-world");

Dapper Integration

Setup

dotnet add package SlugKit.Dapper

services.AddSlugKit().UseDapper();

FindBySlugAsync

using SlugKit.Dapper.Extensions;

// Simple lookup by slug
var project = await connection.FindBySlugAsync<Project>("my-project");

// Scoped lookup (unique within project)
var tag = await connection.FindBySlugAsync<TicketTag>(
    slug: "backend",
    scopeId: projectId,
    scopeColumn: "project_id");

The table name is resolved automatically:

• If the entity has [Table("table_name")], that name is used.
• Otherwise, the type name is converted to snake_case and pluralised (e.g. TicketTag → ticket_tags).

GetExistingSlugsAsync

Use this to populate the existingSlugs list before calling ISlugGenerator.Generate:

var existingSlugs = await connection.GetExistingSlugsAsync<TicketTag>(
    scopeId: projectId,
    scopeColumn: "project_id");

var newSlug = slugGenerator.Generate("Backend", existingSlugs);
// "backend-2" if "backend" is already taken in this project

ASP.NET Core Integration

dotnet add package SlugKit.AspNetCore

using SlugKit.AspNetCore.DependencyInjection;

services.AddSlugKit().AddAspNetCore();

Advanced Scenarios

Custom Slug Generator

Replace the default generator entirely:

public class MySlugGenerator : ISlugGenerator
{
    public string Generate(string source, IReadOnlyList<string>? existingSlugs = null, int maxLength = 0)
    {
        // your implementation
    }
}

services.AddSlugKit();
services.AddSingleton<ISlugGenerator, MySlugGenerator>();

Unicode and Non-Latin Scripts

The default transliterator handles Western European accents via Unicode NFD decomposition:

For Cyrillic, CJK, Arabic, or other scripts, register a custom ISlugTransliterator.

Table Name Resolution (Dapper)

Entity Examples

Simple Entity (global uniqueness)

public class Project : IHasSlug
{
    public int Id { get; set; }
    public string Name { get; set; }

    [Slug(From = nameof(Name), Unique = true, MaxLength = 60)]
    public string Slug { get; set; }
}

Scoped Entity (unique per parent)

public class TicketTag : IHasSlug
{
    public int Id { get; set; }
    public string Name { get; set; }
    public Guid ProjectId { get; set; }

    [Slug(From = nameof(Name), Scope = nameof(ProjectId), Unique = true)]
    public string Slug { get; set; }
}

Always-fresh slug (tracks source changes)

public class WikiPage : IHasSlug
{
    public int Id { get; set; }
    public string Title { get; set; }

    [Slug(From = nameof(Title), OnUpdate = SlugBehavior.RegenerateOnChange, MaxLength = 120)]
    public string Slug { get; set; }
}

Supported Frameworks

All packages multi-target:

SlugKit.AspNetCore targets net8.0 and net10.0 (ASP.NET Core LTS cadence).

License

MIT — see LICENSE.