BlazorWebForms.Infrastructure.SqlServer 1.1.2

BlazorWebForms

Structured form collection for Blazor applications.
Define forms as data, collect submissions, run approval workflows, and export results — without rebuilding UI for every new process.

What is BlazorWebForms?

BlazorWebForms is a library that lets you define forms as structured data (FormDefinition), render them dynamically, and collect submissions with full workflow support — all from a Blazor application.

You describe a form once. The library handles rendering, validation, drafts, file uploads, multi-step approvals, email notifications, PDF export, and search indexing.

Packages

Architecture

Your Blazor App
      │
      ▼
FormsApplicationService          ← single entry point for all operations
      │
      ├── IFormsRepository       ← persistence (implemented by Infrastructure.SqlServer)
      ├── IFileStorage           ← file storage (local disk or bring your own)
      ├── IEmailNotifier         ← email (SMTP / SendGrid / Graph / no-op)
      ├── IPermissionEvaluator   ← role-based access (override for custom rules)
      ├── ICurrentUserContext    ← who is logged in (you implement this)
      └── ICustomFieldHandler[]  ← optional: register your own field types

Core has no dependency on any database, email provider, or UI framework. Every integration point is an interface you can swap.

Quick Start

1. Install packages

dotnet add package BlazorWebForms.Core
dotnet add package BlazorWebForms.Infrastructure.SqlServer

2. Register services

// Program.cs
builder.Services.AddBlazorWebFormsCore();

builder.Services.AddBlazorWebFormsSqlServer(opt =>
{
    opt.ConnectionString = builder.Configuration.GetConnectionString("BlazorWebForms")!;
    opt.StorageRoot = Path.Combine(builder.Environment.ContentRootPath, "uploads");
});

// Required: tell the service who the current user is
builder.Services.AddScoped<ICurrentUserContext, YourCurrentUserContext>();

3. Apply database schema

On first run, call SeedAsync to create tables automatically:

await app.Services.GetRequiredService<FormsApplicationService>().SeedAsync();

Or generate a migration script for review before applying:

dotnet ef migrations script \
  --project src/BlazorWebForms.Infrastructure.SqlServer \
  --startup-project src/BlazorWebForms.SampleApp

4. Create and publish a form

var draft = await formsService.SaveDraftAsync(new SaveDraftRequest
{
    Name = "Travel Request",
    Slug = "travel-request",
    Definition = new FormDefinition
    {
        DefaultCulture = "en-US",
        Sections =
        [
            new FormSectionDefinition
            {
                Title = "Trip Details",
                Fields =
                [
                    new FormFieldDefinition { Id = "destination", Label = "Destination", Kind = FormFieldKind.Text, Required = true },
                    new FormFieldDefinition { Id = "depart-date", Label = "Departure date", Kind = FormFieldKind.Date, Required = true },
                    new FormFieldDefinition { Id = "reason",      Label = "Reason",         Kind = FormFieldKind.TextArea }
                ]
            }
        ]
    }
});

await formsService.PublishAsync(draft.Id);

5. Accept a submission

var entry = await formsService.SubmitEntryAsync(formId, new SubmitEntryRequest
{
    Answers = new() { ["destination"] = "Paris", ["depart-date"] = "2026-09-01" },
    Approvers = [new ApproverInput { Id = "E-1042", DisplayName = "Jane Smith", Email = "jane@example.com" }]
});

Feature Overview

Forms

• 13 built-in field types — Text, TextArea, Number, Select, Radio, Checkbox, Date, File, RichText, Signature, RepeatableList, RankedChoice, and Custom (bring your own)
• Visibility conditions — show/hide sections and fields using AND/OR rules against other field values
• Localization — per-field/section/option localized labels with culture fallback chain
• Branding — logo, hero image, accent color, button radius, surface color per form
• Metadata bags — attach arbitrary Dictionary<string, string> to forms, sections, and fields
• Schema versioning — definitions carry a SchemaVersion for forward-compatibility handling

Submissions

• Draft flow — save, resume, and finalize multi-session drafts
• Immutable revisions or overwrite-latest — configurable per form
• File uploads — per-field constraints (size, MIME type, extension, file count)
• Search indexing — mark fields as Searchable; text index is maintained on save

Approvals

• Sequential multi-step approval — one approver per step, ordered
• Approve / reject / resubmit — full state machine with server-side invariant enforcement
• Audit trail — every action is appended to an immutable ApprovalAuditEvent log
• Approver identity — Id (employee ID), DisplayName, and Email on each step
• Email notifications — assignment, reminder, approval, rejection, and resubmit events

Infrastructure (SqlServer package)

• EF Core 10 persistence with SQL Server / Azure SQL
• Idempotent schema bootstrap — SeedAsync applies column additions without a full migration runner
• Local file storage — safe filename normalization, SHA-256 hash, signed short-lived download links
• Text PDF export — structured entry export with configurable row/size limits
• Email strategies — DryRun (default), Smtp, SendGrid, Graph (Microsoft 365)
• Anti-abuse guards — per-minute upload and notification rate limits
• Draft cleanup — background removal of stale drafts and orphaned files (configurable retention)
• Operational telemetry — upload/PDF/email counters via IOperationalTelemetry

Extensibility

• Register custom field types with AddCustomFieldHandler<T>()
• Override any default implementation (IPermissionEvaluator, IConditionEvaluator, IFileStorage, …)
• Plug in prefill providers (IFormPrefillProvider) for claim-based, employee-based, or custom data

Documentation

Running the Sample App

Prerequisites: .NET 10 SDK, SQL Server or LocalDB.

# Restore and build
dotnet restore
dotnet build -c Debug

# Apply database schema
dotnet ef database update \
  --project src/BlazorWebForms.Infrastructure.SqlServer/BlazorWebForms.Infrastructure.SqlServer.csproj \
  --startup-project src/BlazorWebForms.SampleApp/BlazorWebForms.SampleApp.csproj

# Run
dotnet run --project src/BlazorWebForms.SampleApp/BlazorWebForms.SampleApp.csproj -c Debug

Configuration (src/BlazorWebForms.SampleApp/appsettings.Development.json):

Dev login: use the top-right "Dev login" controls in the sample app shell to sign in as Manager, Owner, Approver, or Admin.

Running Tests

# Core isolated unit tests
dotnet run --project tests/BlazorWebForms.Core.Tests -c Debug

# SQL Server integration tests (requires LocalDB)
dotnet run --project tests/BlazorWebForms.Infrastructure.SqlServer.Tests -c Debug

License

AGPL-3.0-only. Commercial licensing inquiries: open an issue.