Metalama Documentation Skill

This skill contains the complete Metalama documentation including conceptual guides, API reference, and sample code.

This skill pertains to Metalama 2026.0.

Directory Structure

| Directory | Contents | |-----------|----------| | content/conceptual/ | Conceptual documentation (aspects, templates, fabrics, validation, etc.) | | content/patterns/ | Pattern libraries (contracts, caching, observability, memoization, DI) | | content/api/ | API documentation overview pages | | code/ | Sample code (.cs = source, .t.cs = transformed output, .Aspect.cs = aspect implementation) | | api/ | API reference YML files from DocFx |

Finding Information

Search the index: Use grep with -B3 to search index.yml for keywords (each entry has: name, path, summary, keywords - so -B3 captures the path):
```
grep -i -B3 "caching" index.yml
grep -i -B3 "BuildAspect" index.yml
```
Browse by topic: Navigate the content/ directory structure.
API lookup: Use grep on api/.manifest to find API YML files by type or member name:
```
grep -i "OverrideMethodAspect" api/.manifest
```

Key Entry Points

| Topic | File | Description | |-------|------|-------------| | Getting Started | content/conceptual/using/using-metalama.md | How to use Metalama in your projects | | Creating Aspects | content/conceptual/aspects/aspects.md | Overview of aspect creation | | Overriding Methods | content/conceptual/aspects/simple-aspects/overriding-methods.md | Basic method interception | | Templates | content/conceptual/aspects/templates/templates.md | T# template syntax and patterns | | Fabrics | content/conceptual/using/fabrics/fabrics.md | Bulk aspect application | | Contracts | content/patterns/contracts/contract-patterns.md | Parameter/property validation | | Caching | content/patterns/caching/caching.md | Method result caching | | Observability | content/patterns/observability/observability.md | INotifyPropertyChanged implementation | | Debugging Aspects | content/conceptual/aspects/testing/debugging-aspects.md | Debug compile-time code, breakpoints, meta.DebugBreak() | | Debugging User Code | content/conceptual/using/debugging-aspect-oriented-code.md | Debug run-time transformed code, LamaDebug configuration |

Common Patterns

Base Classes

| Base Class | Target | Key Override | Use When | |------------|--------|--------------|----------| | OverrideMethodAspect | Methods | OverrideMethod() | Wrap/intercept methods | | OverrideFieldOrPropertyAspect | Fields/Properties | OverrideProperty | Wrap property access | | ContractAspect | Parameters/Fields/Properties | Validate(dynamic? value) | Validate values | | TypeAspect | Types | BuildAspect() | Introduce members, implement interfaces | | MethodAspect | Methods | BuildAspect() | Programmatic method transformation | | TypeFabric | Single type | AmendType() | Bulk changes to one type | | ProjectFabric | Project | AmendProject() | Apply aspects across project |

Template Fundamentals

[!IMPORTANT] T# templates look like C# but have different semantics. Code that works in normal C# may not work identically in a template. Always read the full template documentation at content/conceptual/aspects/templates/ before writing template code.

public override dynamic? OverrideMethod()
{
    // Pre-logic
    try
    {
        return meta.Proceed();  // Calls original method
    }
    finally
    {
        // Post-logic (always runs)
    }
}

dynamic? handles any return type (void returns null)
meta.Proceed() auto-transforms to await for async targets
Use meta.Target.* to access compile-time information about the target declaration
To debug templates, use meta.DebugBreak() (not Debugger.Break())

Debugging Quick Reference

Debugging compile-time code (aspects, fabrics, templates):

Add Debugger.Break() in BuildAspect/fabrics, or meta.DebugBreak() in templates
Build with: dotnet build -p:MetalamaDebugCompiler=True -p:MetalamaConcurrentBuildEnabled=False
Attach debugger when prompted, then set breakpoints in transformed code (obj/.../metalama/)

Debugging run-time code (transformed output):

Create a LamaDebug build configuration in Visual Studio
Use F11 to step into code, or add Debugger.Break()
Set breakpoints in transformed files under obj/<Config>/<TFM>/metalama/

Common Pitfalls

| Mistake | Correct Approach | |---------|------------------| | Using Debugger.Break() in templates | Use meta.DebugBreak() in templates; Debugger.Break() only works in BuildAspect and fabrics | | Setting breakpoints in source files | Breakpoints don't work in Metalama-transformed projects; use Debugger.Break()/meta.DebugBreak() then set breakpoints in transformed code | | Using nameof() for introduced members | Use string literals; nameof() resolves at aspect compile-time, not target compile-time | | Filtering all types by namespace in fabrics | Use GlobalNamespace.GetDescendant("Ns") or a NamespaceFabric instead of SelectTypes().Where(t => t.Namespace...) | | Forgetting partial on target classes | Classes receiving introduced members need the partial modifier |

Sample Code Conventions

Name.cs - Target code receiving the aspect
Name.Aspect.cs - Aspect implementation
Name.t.cs - Transformed output (what the compiler generates)
Name.Dependency.cs - Referenced project code for multi-project examples

Metalama Markdown Directives

The documentation uses custom [!metalama-*] directives to include code samples. These are processed at build time to generate HTML, but in the skill files you see the raw directives.

Reading Directive References

When you see a directive in a Markdown file, extract the file path and read the referenced file directly.

| Directive | Purpose | Example | |-----------|---------|---------| | [!metalama-file PATH] | Shows a single source file | [!metalama-file ~/code/Project/File.cs] | | [!metalama-test PATH] | Shows test with input/output | [!metalama-test ~/code/Project/Test.cs] | | [!metalama-compare PATH] | Shows side-by-side diff | [!metalama-compare ~/code/Project/File.cs] | | [!metalama-vimeo ID] | Embeds Vimeo video | [!metalama-vimeo 842168905] |

Path Resolution

~/ resolves to the SKILLS.md directory
Example: ~/code/Metalama.Documentation.SampleCode.AspectFramework/GettingStarted/GettingStarted.cs → Read code/Metalama.Documentation.SampleCode.AspectFramework/GettingStarted/GettingStarted.cs

How to Read Referenced Code

When you encounter a directive like [!metalama-file ~/code/Project/File.cs]:

Read the main file: code/Project/File.cs
Check for related files (same name, different suffix):
- File.Aspect.cs - Aspect implementation
- File.t.cs - Transformed output
- File.Fabric.cs - Fabric code

Markers: If you see marker="NAME", look for code between // [<snippet NAME>] and // [<endsnippet NAME>] in the file.

API Reference

The api/ directory contains DocFx-generated YML files for all public APIs.

Finding API Documentation

Use api/.manifest - a JSON index mapping all UIDs (types, members, overloads) to their YML files.

Search the manifest for the type or member name:

"Metalama.Framework.Aspects.OverrideMethodAspect": "Metalama.Framework.Aspects.OverrideMethodAspect.yml"
"Metalama.Framework.Aspects.OverrideMethodAspect.OverrideMethod": "Metalama.Framework.Aspects.OverrideMethodAspect.yml"
"Metalama.Framework.Code.IMethod": "Metalama.Framework.Code.IMethod.yml"

Read the corresponding YML file to get full documentation.
Naming conventions:
- Types: Namespace.TypeName.yml
- Generic types: backtick becomes dash, e.g., IAspectBuilder<T> → Metalama.Framework.Aspects.IAspectBuilder-1.yml
- All members of a type are in the same YML file as the type

YML File Structure

Each type's YML file contains all members of that type in a single file:

items:
- uid: Namespace.TypeName           # Type definition
  commentId: T:Namespace.TypeName
  type: Class|Interface|Enum|...
  summary: Type description
  remarks: Detailed explanation
  syntax:
    content: public class TypeName : BaseClass
  children:                         # List of member UIDs
  - Namespace.TypeName.Method1
  - Namespace.TypeName.Property1

- uid: Namespace.TypeName.Method1   # Member definition
  commentId: M:Namespace.TypeName.Method1
  type: Method|Property|Field|...
  summary: Member description
  syntax:
    content: public void Method1()
  parameters: [...]                 # For methods
  return: { type: ..., description: ... }

Key Namespaces

| Namespace | Purpose | |-----------|---------| | Metalama.Framework.Aspects | Aspect base classes, attributes, meta API | | Metalama.Framework.Code | Code model interfaces (IMethod, IType, IParameter, etc.) | | Metalama.Framework.Advising | Advice APIs for introducing members, implementing interfaces | | Metalama.Framework.Eligibility | Eligibility builders for aspect targeting | | Metalama.Framework.Diagnostics | Reporting warnings and errors | | Metalama.Framework.Fabrics | Fabric base classes | | Metalama.Patterns.Contracts | Contract validation aspects | | Metalama.Patterns.Caching | Caching aspects and configuration | | Metalama.Patterns.Observability | INotifyPropertyChanged implementation | | Metalama.Extensions.DependencyInjection | Dependency injection | | Metalama.Extensions.Architecture | Architecture enforcement/validation |

Linking to Documentation

When referencing documentation articles, provide links to the live documentation at https://doc.metalama.net.

URL format: https://doc.metalama.net/<path> where <path> is derived from the file path under content/:

Remove content/ prefix
Remove .md suffix
For index files where the filename matches the parent folder (e.g., path/leaf/leaf.md), use just path/leaf

Examples: | File Path | URL | |-----------|-----| | content/conceptual/aspects/aspects.md | https://doc.metalama.net/conceptual/aspects | | content/conceptual/aspects/templates/templates.md | https://doc.metalama.net/conceptual/aspects/templates | | content/patterns/caching/caching.md | https://doc.metalama.net/patterns/caching | | content/conceptual/aspects/simple-aspects/overriding-methods.md | https://doc.metalama.net/conceptual/aspects/simple-aspects/overriding-methods |

External Resources

Live documentation: https://doc.metalama.net
Source repository: https://github.com/metalama/Metalama
Samples repository: https://github.com/metalama/Metalama.Samples