If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dotnetcore/Util shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 3 active contributors
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dotnetcore/Util repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnetcore/Util.

What it runs against: a local clone of dotnetcore/Util — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dotnetcore/Util | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 602 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnetcore/Util. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnetcore/Util.git
#   cd Util
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dotnetcore/Util and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnetcore/Util(\\.git)?\\b" \\
  && ok "origin remote is dotnetcore/Util" \\
  || miss "origin remote is not dotnetcore/Util (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/Util.Application/ServiceBase.cs" \\
  && ok "src/Util.Application/ServiceBase.cs" \\
  || miss "missing critical file: src/Util.Application/ServiceBase.cs"
test -f "src/Util.Application.EntityFrameworkCore/CrudServiceBase.cs" \\
  && ok "src/Util.Application.EntityFrameworkCore/CrudServiceBase.cs" \\
  || miss "missing critical file: src/Util.Application.EntityFrameworkCore/CrudServiceBase.cs"
test -f "src/Util.Application.WebApi/Controllers/WebApiControllerBase.cs" \\
  && ok "src/Util.Application.WebApi/Controllers/WebApiControllerBase.cs" \\
  || miss "missing critical file: src/Util.Application.WebApi/Controllers/WebApiControllerBase.cs"
test -f "src/Util.Aop.AspectCore/InterceptorBase.cs" \\
  && ok "src/Util.Aop.AspectCore/InterceptorBase.cs" \\
  || miss "missing critical file: src/Util.Aop.AspectCore/InterceptorBase.cs"
test -f "src/Util.AspNetCore/Security/Authorization/AclHandler.cs" \\
  && ok "src/Util.AspNetCore/Security/Authorization/AclHandler.cs" \\
  || miss "missing critical file: src/Util.AspNetCore/Security/Authorization/AclHandler.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 602 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~572d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dotnetcore/Util"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Util is a .NET application framework that accelerates middle-tier team development by providing layered architecture base classes, utility libraries, AOP (AspectCore-based), validation, authentication (Identity/IdentityServer4), and WebApi scaffolding. It reduces boilerplate through auto-discovered service registrars and standardized CRUD/Tree controller and service patterns. Modular architecture: src/ contains independent framework modules (Util.Aop.AspectCore, Util.Application.EntityFrameworkCore, Util.Application.WebApi). Each module is a self-contained .csproj. build/ contains centralized build scripts and versioning (version.props, common.props). WebApi module exposes CrudControllerBase, TreeControllerBase, and filter infrastructure; EntityFrameworkCore module provides CrudServiceBase and TreeServiceBase; Aop module wraps AspectCore with parameter validation interceptors.

.NET developers and small-to-medium teams building business applications who want rapid CRUD operations, automatic dependency injection wiring, and role-based access control without writing repetitive infrastructure code. Framework authors extending or composing Util into custom domain frameworks.

Production-ready and actively maintained. The codebase is substantial (8.7M LOC in C#), authored by 何镇汐 with documented contributors, organized as a proper NuGet package ecosystem (Util.Aop.AspectCore, Util.Application.EntityFrameworkCore, Util.Application.WebApi modules), and clearly designed for real-world use. MIT license indicates maturity intent.

Moderate risk: as a framework, breaking changes in core registrars (ServiceRegistrarConfigExtensions) or AOP interceptor patterns could cascade across consumer code. The monolithic design (single Util.sln) means framework updates may require coordination. Last activity and open issue backlog are not visible in provided data, so check GitHub repo directly for staleness. Single primary maintainer (何镇汐) concentration is typical for framework projects but warrants monitoring.

Unable to determine from provided data. Check GitHub repository's recent commits, PR list, and Releases tab to see current development focus and roadmap.

git clone https://github.com/dotnetcore/Util.git cd Util dotnet build Util.sln OR inspect individual module .csproj files for targeted builds (e.g., dotnet build src/Util.Aop.AspectCore/03-Util.Aop.AspectCore.csproj).

Daily commands: dotnet build Util.sln to compile the framework. No standalone runnable app is present; Util is a library. To test: dotnet test (if test projects exist in repo; not visible in top-60 files). Individual modules are consumed as NuGet packages by client applications.

• src/Util.Application/ServiceBase.cs — Core base class for all application services; defines the service interface contract that all CRUD and query services inherit from
• src/Util.Application.EntityFrameworkCore/CrudServiceBase.cs — Implements CRUD operations using EF Core; all data-driven services extend this class to handle Create, Read, Update, Delete
• src/Util.Application.WebApi/Controllers/WebApiControllerBase.cs — Base controller class for all Web API endpoints; handles request routing, error handling, and response formatting
• src/Util.Aop.AspectCore/InterceptorBase.cs — Foundation for cross-cutting concerns (logging, validation, exception handling); all interceptors extend this to provide AOP behavior
• src/Util.AspNetCore/Security/Authorization/AclHandler.cs — Access control list authorization handler; implements permission validation for protected resources across the application
• src/Util.Application/Dtos/DtoBase.cs — Base class for all Data Transfer Objects; defines common DTO patterns used throughout request/response cycles
• src/Util.Application.WebApi/Result.cs — Unified API response wrapper; standardizes all HTTP responses with consistent status, message, and data structure

Add a New CRUD Service

1. Create a new service interface extending ICrudService<T> in your domain project (src/Util.Application/ICrudService.cs)
2. Implement the service by extending CrudServiceBase<T> and override methods as needed (src/Util.Application.EntityFrameworkCore/CrudServiceBase.cs)
3. Register the service in DI container using WebApiServiceRegistrar.AddCrudService() (src/Util.Application.WebApi/Infrastructure/WebApiServiceRegistrar.cs)

Add a New Web API Endpoint

1. Create a new controller extending CrudControllerBase<TDto,TQueryParameter> for CRUD or QueryControllerBase for read-only (src/Util.Application.WebApi/Controllers/CrudControllerBase.cs)
2. Inject the corresponding service (from step 1 above) via constructor dependency injection (src/Util.Application.WebApi/Controllers/WebApiControllerBase.cs)
3. Define action methods that call service methods; Result<T> wrapper handles consistent response formatting (src/Util.Application.WebApi/Result.cs)
4. Optionally add [Acl] attribute to protected endpoints for authorization (src/Util.AspNetCore/Security/AclAttribute.cs)

Add Parameter Validation via Interceptor

1. Create an interceptor class extending ParameterInterceptorBase (src/Util.Aop.AspectCore/ParameterInterceptorBase.cs)
2. Override ExecuteAsync() to validate parameters and throw validation exceptions (src/Util.Aop.AspectCore/InterceptorBase.cs)
3. Apply custom interceptor attribute to service methods requiring validation (src/Util.Aop.AspectCore/NotNullAttribute.cs)
4. Register interceptor in AspNetCore startup via AopOptions configuration (src/Util.Aop.AspectCore/AopOptions.cs)

Implement Tree/Hierarchical Data Operations

1. Create a DTO extending TreeDtoBase which includes Id, ParentId, and Children properties (src/Util.Application/Trees/TreeDtoBase.cs)
2. Implement service extending TreeServiceBase<T> for tree operations (src/Util.Application.EntityFrameworkCore/Trees/TreeServiceBase.cs)
3. Create controller extending TreeControllerBase<TDto> to expose tree endpoints (src/Util.Application.WebApi/Controllers/TreeControllerBase.cs)
4. Define load modes (Parent, Children, All) in service to control hierarchy loading (src/Util.Application/Trees/LoadMode.cs)

• AspectCore AOP — Provides lightweight method interception for cross-cutting concerns (validation, logging) without invasive code changes
• Entity Framework Core — ORM abstraction for database operations; enables generic CRUD service implementation across different entities
• ASP.NET Core Middleware & Filters — Allows centralized request/response processing and exception handling across all endpoints
• Authorization Policies (ACL Handler) — Integrates with ASP.NET Core's authorization model to provide declarative access control at the action level

• Generic base service classes (CrudServiceBase, QueryServiceBase) rather than code generation

  • Why: Reduces boilerplate and provides consistent behavior across all entity services; enables quick onboarding
  • Consequence: Less flexibility for entity-specific service logic; developers must override methods for custom behavior rather than modifying generated code

• Unified Result<T> wrapper for all API responses

  • Why: Ensures consistent API contracts and response structure across endpoints
  • Consequence: Every endpoint must use Result<T>; cannot return raw entities; requires client-side understanding of the wrapper format

• Tree/Hierarchical data support built into core framework

  • Why: Many enterprise applications need tree structures; providing TreeServiceBase and TreeControllerBase
  • Consequence: undefined

Service registrars must be public classes in assemblies scanned by the startup bootstrapper—silent failures if not discoverable. AOP interceptors applied via attributes require AspectCore to be registered in DI, or method interception silently does not occur. Tree-based entities require specific navigation property structure (TreeQueryServiceBase and TreeServiceBase expect parent/child relationships). IdentityServer4 requires external token validation endpoint configuration (not bundled). LogContextMiddleware must be registered in pipeline before other middleware to capture request context correctly. Breaking change risk: the ServiceRegistrar discovery mechanism may differ between framework versions—pin exact version in production.

• Service Registrar Pattern — Util's core startup mechanism auto-discovers and executes service registrars to wire dependencies without explicit module registration code; understanding this enables you to extend the framework.
• Aspect-Oriented Programming (AOP) via Method Interception — Util uses AspectCore to intercept method calls for validation and cross-cutting concerns; knowing AOP patterns is essential to extending validation and logging behavior.
• Dependency Injection Container Auto-Discovery (ISingletonDependency, IScopeDependency, ITransientDependency) — Util automatically registers dependencies by interface inheritance; this magic convention reduces boilerplate but requires understanding the lifetime model and discovery timing.
• Layered Architecture with Base Classes (Service/Controller Inheritance Hierarchy) — Util enforces a 3-tier pattern (WebApi Controller → Application Service → EntityFrameworkCore Repository); most extension points involve overriding or decorating these base classes.
• Tree Data Structures (Hierarchical Entity Patterns) — Util provides TreeServiceBase and TreeQueryServiceBase for parent-child data; understanding tree traversal and self-referential foreign keys is needed to use these modules.
• Object-to-Object Mapping (DTO Pattern via AutoMapper) — Util adds MapTo extension methods for automatic DTO↔Entity conversion; understanding mapping configuration is essential for avoiding circular references and lazy-loading issues.
• Role-Based Access Control (RBAC) via Policy-Based Authorization — Util extends ASP.NET Core's authorization policies for simplified role/permission checks on controllers; understanding policy definition is needed for custom access control.

• aspnetboilerplate/aspnetboilerplate — Similar ASP.NET application framework providing CRUD abstractions, validation, and DDD patterns; direct architectural competitor for same use case.
• dotnetcore/AspectCore-Framework — Upstream dependency—Util.Aop.AspectCore is a wrapper; understanding AspectCore internals helps customize interceptor behavior.
• AutoMapper/AutoMapper — Dependency for object-to-object mapping (MapTo extension); critical for DTO↔Entity transformations in layered architecture.
• IdentityServer/IdentityServer4 — Bundled auth option; Util documents integration patterns and extends custom authorization policies on top of IdentityServer4.
• dotnetcore/Home — Parent organization repo (.NET Core Community); Util is a member project; contains shared governance and community guidelines.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for AOP interceptor chain in Util.Aop.AspectCore

The Util.Aop.AspectCore module contains critical interceptor base classes (InterceptorBase.cs, ParameterInterceptorBase.cs) and validation attributes (NotEmptyAttribute.cs, NotNullAttribute.cs) but lacks visible test coverage. Given that AOP is a core cross-cutting concern for the framework, adding tests would ensure reliability and reduce regressions. This is especially important for parameter validation interceptors that protect service boundaries.

• [ ] Create test project: tests/Util.Aop.AspectCore.Tests/Util.Aop.AspectCore.Tests.csproj
• [ ] Add unit tests for InterceptorBase.cs covering method interception and exception handling
• [ ] Add unit tests for ParameterInterceptorBase.cs validating NotNullAttribute and NotEmptyAttribute enforcement
• [ ] Add integration tests demonstrating interceptor chain ordering and IAopProxy behavior
• [ ] Verify tests pass in CI pipeline

Create missing GitHub Actions CI/CD workflow for multi-platform build validation

The repository has a build infrastructure (build/Build.csproj, build/BuildScript.cs, Directory.Build.props) but no visible GitHub Actions workflows (.github/workflows/) for automated testing. This is critical for a framework serving as architectural foundation—without CI, contributors cannot verify their changes work across .NET versions and configurations. This also protects the codebase from regressions in dependent packages.

• [ ] Create .github/workflows/build-and-test.yml with matrix strategy for .NET 6, 7, 8
• [ ] Configure workflow to run: dotnet build (referencing build/Build.csproj), execute test projects, and publish results
• [ ] Add workflow for NuGet package validation (if applicable to build/version.props)
• [ ] Document build requirements in readme.md or CONTRIBUTING.md (pull version info from build/version.props)
• [ ] Ensure workflow triggers on pull requests and commits to main branch

Add XML documentation and usage examples for WebAPI base controllers in Util.Application.WebApi

The WebAPI module provides critical base classes (CrudControllerBase.cs, QueryControllerBase.cs, TreeControllerBase.cs, WebApiControllerBase.cs) that serve as templates for team development, but these lack API documentation and practical examples. Since Util's design philosophy emphasizes 'simple API and low learning cost,' missing documentation contradicts this goal. Adding comprehensive XML docs and example usage guides would accelerate the 3-day onboarding target mentioned in the README.

• [ ] Add XML documentation comments to src/Util.Application.WebApi/Controllers/WebApiControllerBase.cs describing lifecycle, virtual methods, and typical customization points
• [ ] Add XML documentation to CrudControllerBase.cs, QueryControllerBase.cs, and TreeControllerBase.cs with inheritance patterns
• [ ] Create docs/WebApi-Controllers-Guide.md with code examples showing: inheriting from each base class, overriding methods, and Result/IResultFactory usage
• [ ] Document the filter pipeline (Filters/ExceptionHandlerAttribute.cs, ErrorLogFilterAttribute.cs, LockAttribute.cs) with examples
• [ ] Reference new guide in readme.md under a 'Getting Started' section

• Add comprehensive XML documentation comments to all public methods in src/Util.Aop.AspectCore/InterceptorBase.cs and ParameterInterceptorBase.cs; currently missing examples of custom interceptor creation.
• Create unit test file src/Util.Application.EntityFrameworkCore/Tests/CrudServiceBase.Tests.cs covering soft-delete, pagination, and sorting scenarios; no test directory visible in file list.
• Add English-language README.md to src/Util.Application.WebApi/ module explaining filter pipeline execution order, exception mapping, and LogContextMiddleware initialization (currently only Chinese readme.md at root).

• Medium · Potential Unsafe Deserialization in WebApi JSON Processing — src/Util.Application.WebApi/JsonSerializerOptionsFactory.cs. The file JsonSerializerOptionsFactory.cs suggests custom JSON serialization configuration. Without examining the actual code, there's a risk of unsafe deserialization patterns that could allow arbitrary code execution if not properly configured. .NET JSON serializers can be vulnerable to denial-of-service attacks or type confusion if not hardened. Fix: Review and ensure JsonSerializerOptions uses TypeInfoResolver with explicit type allowlists. Avoid deserializing untrusted data with loose type handling. Consider using System.Text.Json with strict configuration over third-party serializers.
• Medium · Global Exception Handling May Expose Sensitive Information — src/Util.Application.WebApi/Filters/ExceptionHandlerAttribute.cs, src/Util.Application.WebApi/Filters/ErrorLogFilterAttribute.cs. The ExceptionHandlerAttribute.cs and ErrorLogFilterAttribute.cs suggest centralized exception handling in web APIs. Exception details could potentially leak sensitive information (stack traces, internal paths, database schema) to clients if not properly sanitized. Fix: Implement exception filtering to ensure sensitive details are never sent to clients. Log full exception details server-side only. Return generic error messages to users. Ensure stack traces are excluded from production responses.
• Medium · Potential SQL Injection in ORM Layer — src/Util.Application.EntityFrameworkCore/CrudServiceBase.cs, src/Util.Application.EntityFrameworkCore/QueryServiceBase.cs. The codebase includes EntityFramework-based services (CrudServiceBase.cs, QueryServiceBase.cs). If raw SQL queries or dynamic LINQ construction is used without proper parameterization, SQL injection vulnerabilities could exist. Fix: Audit all database queries to ensure parameterized queries are used exclusively. Never concatenate user input into SQL strings. Use Entity Framework's LINQ APIs which provide built-in protection. Add static analysis tools to catch SQL construction issues.
• Medium · Missing CSRF Protection Configuration — src/Util.Application.WebApi/Controllers/. No visible CSRF token configuration in the WebApi controllers or middleware. ASP.NET Core requires explicit configuration for CSRF protection in state-changing operations (POST, PUT, DELETE). Fix: Implement ValidateAntiForgeryToken attributes on all state-changing endpoints. Configure middleware to automatically validate CSRF tokens. Ensure CORS policy is properly restricted and doesn't allow overly permissive origins.
• Medium · Authorization Not Explicitly Defined in Base Controllers — src/Util.Application.WebApi/Controllers/WebApiControllerBase.cs, src/Util.Application.WebApi/Controllers/CrudControllerBase.cs. The WebApiControllerBase and derived controllers (CrudControllerBase, QueryControllerBase) do not show explicit authorization attributes. Without default authorization requirements, endpoints may be inadvertently exposed. Fix: Apply [Authorize] attribute at the controller level as a default, requiring explicit [AllowAnonymous] for public endpoints. Implement fine-grained authorization policies. Use role-based or claim-based access control consistently.
• Low · Missing Security Headers Configuration — src/Util.AspNetCore/AppBuilderExtensions.cs. No visible middleware configuration for security headers (X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security, Content-Security-Policy) in the AspNetCore extension files. Fix: Add middleware to set security headers. Implement: X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security, Content-Security-Policy, X-XSS-Protection. Consider using NWebsec NuGet package.
• Low · Dependency Versions Not Visible in Analysis — build/common.props, *.csproj files. The dependency/package information was not provided in the analysis context. Unable to identify vulnerable NuGet package versions that may be in use. Fix: Run 'dotnet list package --vulnerable' to identify vulnerable dependencies. Use NuGet package analyzer tools. Implement automated dependency scanning in CI/CD. Keep all packages updated to latest stable versions.
• Low · Potential Distributed Denial of — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.