ANcpLua.Roslyn.Utilities provides utilities for building Roslyn analyzers and source generators.
What’s New in v1.19
Expanded Guard API - Comprehensive argument validation:
- Collections:
NoDuplicates() for duplicate detection
- File System:
FileExists(), DirectoryExists(), ValidFileName(), ValidPath(), ValidExtension(), NormalizedExtension()
- Type Validation:
DefinedEnum(), NotNullableType(), AssignableTo<T>(), AssignableFrom<T>()
- Member Validation:
NotNullWithMember(), MemberNotNull() for object + member validation
- Numeric:
NotZero, NotNegative, Positive, NotGreaterThan, NotLessThan, LessThan, GreaterThan (int/long/double/decimal)
- Double-specific:
NotNaN(), Finite() for floating-point edge cases
- Unreachable Code:
Unreachable(), Unreachable<T>() with caller info capture
All numeric methods use [MethodImpl(AggressiveInlining)] for hot paths.
What’s New in v1.18
API cleanup - Tightened public surface, renamed methods for clarity:
Guard.NotNullOr* renamed to Guard.NotNullOrElse* with new lazy Func<T> overloadsIndentedStringBuilder.Indent()/Outdent() made private (use BeginBlock())- Helper extensions reorganized:
NullableExtensions, ObjectExtensions, TryExtensions
- Redundant nullability attributes and operators removed
Install
# For analyzers/generators (source-only, no runtime dependency)
dotnet add package ANcpLua.Roslyn.Utilities.Sources
# For polyfills only (no Roslyn dependency)
dotnet add package ANcpLua.Roslyn.Utilities.Polyfills
# For runtime reference
dotnet add package ANcpLua.Roslyn.Utilities
# For testing
dotnet add package ANcpLua.Roslyn.Utilities.Testing
Layer 0 Package: This package cannot depend on ANcpLua.NET.Sdk (circular
dependency). Uses Microsoft.NET.Sdk with built-in polyfills.
Packages
| Package | Target | Description |
|---|
| ANcpLua.Roslyn.Utilities | netstandard2.0 | Core library (DLL reference) |
| ANcpLua.Roslyn.Utilities.Sources | netstandard2.0 | Source-only (embeds as internal in analyzers/generators) |
| ANcpLua.Roslyn.Utilities.Polyfills | netstandard2.0 | Source-only polyfills (no Roslyn dependency) |
| ANcpLua.Roslyn.Utilities.Testing | net10.0 | Generator testing |
Features
| Category | APIs | Docs |
|---|
| Flow Control | DiagnosticFlow<T>, ReportAndContinue() | DiagnosticFlow |
| Pattern Matching | Match.* (symbols), Invoke.* (operations) | Patterns |
| Guard Clauses | Guard.NotNull(), Guard.Positive(), etc. | Guard |
| Semantic Validation | SemanticGuard<T>, MustBeAsync() | SemanticGuard |
| Domain Contexts | AwaitableContext, AspNetContext | Contexts |
| Operations | OperationExtensions, InvocationExtensions | Operations |
| Code Generation | IndentedStringBuilder | Codegen |
| Pipeline | GroupBy(), Batch(), Distinct() | Pipeline |
| Symbol Extensions | IsEqualTo(), HasAttribute() | Symbols |
| Testing | Test<TGenerator>.Run(), caching validation | Testing |
Quick Example
// DiagnosticFlow - never lose diagnostics
symbol.ToFlow(nullDiag)
.Then(ValidateMethod)
.Where(m => m.IsAsync, asyncRequired)
.WarnIf(m => m.IsObsolete, obsoleteWarn)
.Then(GenerateCode)
.ReportAndContinue(context);
// Pattern matching - replace 50-line if-statements
Match.Method()
.Async()
.ReturningTask()
.WithCancellationToken()
.Matches(method);
