AspectGenerator 0.1.0

Aspect Generator

AspectGenerator is a source generator for compile-time call-site rewriting with C# interceptors. It lets you define attribute-based aspects that run around intercepted method calls without runtime proxies or IL weaving.

Quick Start

Install the package:

dotnet add package AspectGenerator

Configure the consuming project:

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <InterceptorsNamespaces>$(InterceptorsNamespaces);AspectGenerator</InterceptorsNamespaces>
</PropertyGroup>

Define an aspect:

using AspectGenerator;

namespace Aspects;

[Aspect(OnBeforeCall = nameof(OnBeforeCall))]
[AttributeUsage(AttributeTargets.Method, Inherited = false, AllowMultiple = false)]
sealed class LogAttribute : Attribute
{
    public static void OnBeforeCall(InterceptInfo info)
    {
        Console.WriteLine($"Calling {info.MemberInfo.Name}");
    }
}

Use it on a method:

using Aspects;

class Service
{
    [Log]
    public static void DoWork()
    {
    }
}

Service.DoWork();

AspectGenerator finds interceptable call sites to DoWork in the current compilation and emits interceptor methods for those locations.

Configuration

AspectGenerator can be configured with MSBuild properties:

<PropertyGroup>
  <AspectGeneratorGenerateApi>true</AspectGeneratorGenerateApi>
  <AspectGeneratorPublicApi>false</AspectGeneratorPublicApi>
  <AspectGeneratorDebuggerStepThrough>false</AspectGeneratorDebuggerStepThrough>
  <AspectGeneratorInterceptorsNamespace>AspectGenerator</AspectGeneratorInterceptorsNamespace>
</PropertyGroup>

The same settings can be overridden with an assembly-level attribute:

using AspectGenerator;

[assembly: AspectGeneratorOptions(
    GenerateApi = true,
    PublicApi = false,
    DebuggerStepThrough = false,
    InterceptorsNamespace = "AspectGenerator")]

AspectGeneratorInterceptorsNamespace must also be listed in InterceptorsNamespaces, otherwise the compiler will not enable generated interceptors from that namespace.

Generated API Ownership

AspectGenerator normally generates the authoring/runtime API into each consuming compilation:

• GenerateApi=true: generate AspectAttribute, InterceptInfo, InterceptData<T>, InterceptResult, and related types.
• GenerateApi=false: do not generate the API. Use this when the API is supplied by an aspect library.
• PublicApi=false: generated API is internal to the consuming assembly.
• PublicApi=true: generated API is public. Treat this mode as experimental until the public contract is stabilized.

Common modes:

Supported Scenarios

Hooks

AspectAttribute maps lifecycle hooks to static method names:

[Aspect(
    OnInit = nameof(OnInit),
    OnUsing = nameof(OnUsing),
    OnUsingAsync = nameof(OnUsingAsync),
    OnBeforeCall = nameof(OnBeforeCall),
    OnBeforeCallAsync = nameof(OnBeforeCallAsync),
    OnCall = nameof(OnCall),
    OnAfterCall = nameof(OnAfterCall),
    OnAfterCallAsync = nameof(OnAfterCallAsync),
    OnCatch = nameof(OnCatch),
    OnCatchAsync = nameof(OnCatchAsync),
    OnFinally = nameof(OnFinally),
    OnFinallyAsync = nameof(OnFinallyAsync))]

Hook names are strings, so prefer nameof(...). Invalid names or signatures should be reported by AspectGenerator diagnostics; if a case still fails only through generated-code compiler errors, treat that as a bug.

Explicit Method Interception

InterceptMethods is a low-level compatibility feature that matches methods by display string:

[Aspect(
    OnAfterCall = nameof(OnAfterCall),
    InterceptMethods =
    [
        "System.String.Substring(int)",
        "string.Substring(int)"
    ])]

This form is brittle because it depends on compiler display strings, aliases, overloads, and generic spelling. Prefer method-level aspect attributes where possible.

Documentation And Wiki

The README is the concise entry point. The wiki should contain expanded pages with the same current terminology:

• Configuration
• Aspect library mode
• Hook lifecycle
• InterceptMethods
• Diagnostics
• Limitations

When updating docs, keep README and wiki synchronized:

• document the .NET 10 SDK/compiler requirement and use net10.0 in examples;
• use InterceptorsNamespaces, not InterceptorsPreviewNamespaces;
• use AspectGeneratorGenerateApi, AspectGeneratorPublicApi, AspectGeneratorDebuggerStepThrough, and AspectGeneratorInterceptorsNamespace;
• describe InterceptableLocation as opaque compiler data;
• keep unsupported scenarios consistent between README and wiki.

Any remaining preview-era wiki page should be updated or marked with an “Obsolete preview documentation” warning.

Development

Run the main checks locally:

dotnet restore
dotnet build --no-restore
dotnet test --no-build
dotnet pack Source/AspectGenerator.csproj --no-build

Build artifacts under bin/ and obj/ must not be committed. If generated source snapshots are needed, store them in an explicit baseline folder under UnitTests/, not under obj/GeneratedFiles.