Represents a reference to an IDeclaration or IType that remains valid across different compilation versions (i.e., ICompilation) and, when serialized, across projects and processes. All objects implementing this interface also implement the strongly-typed IRef<T>.
Namespace: Metalama.Framework.Code
Assembly: Metalama.Framework.dll
Syntax
[CompileTime]
[InternalImplement]
public interface IRef : IEquatable<IRef>Remarks
References are essential in Metalama because each IDeclaration or IType object is bound to a specific ICompilation. As aspects execute, the compilation evolves through multiple immutable versions at each pipeline step. References provide a stable way to identify the same declaration across these compilation versions.
Common use cases:
- Storing declaration references in aspect fields for use across compilation versions.
- Serializing declaration references for cross-project scenarios (inheritable aspects, reference validators).
- Passing declaration references to child aspects or storing them in IAspectState.
To obtain a reference, call ToRef() or ToRef(). To resolve a reference back to the declaration in a specific compilation, use GetTarget<T>(IRef<T>, ICompilation, IGenericContext?) or GetTarget<T>(IRef<T>) (for the current execution context).
Use RefEqualityComparer<T> to compare instances of IRef in collections.
Properties
| Name | Description |
|---|---|
| IsDurable | Gets a value indicating whether the reference stores only a string identifier rather than holding a reference to the compilation state. This is an internal concept with no user-facing scenario; there is no public API to create durable references. |
Methods
| Name | Description |
|---|---|
| As<TOut>() | Changes the reference type. This method can be used in two scenarios: instead of a C# cast with durable references (see IsDurable), or between IField and IProperty when a field is overridden into a property (see OverridingProperty and OriginalField). |
| Equals(IRef?, RefComparison) | Compares this reference to another reference using the specified comparison strategy. |
| GetHashCode(RefComparison) | Returns a hash code for this reference using the specified comparison strategy. |
| GetTargetInterface(ICompilation, Type?, IGenericContext?, bool) | Gets the target of the reference for a given compilation, with control over the interface type and error handling. Prefer the extension methods GetTarget<T>(IRef<T>, ICompilation, IGenericContext?) or GetTargetOrNull<T>(IRef<T>, ICompilation, IGenericContext?) for typical usage. |
| ToSerializableId() | Returns a string that uniquely identifies the declaration represented by the current reference. This identifier can then be resolved using GetDeclarationFromId(SerializableDeclarationId), even in a different process or with a different version of Metalama than the one that created the id. |