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

metalama-2026.0