View source for Metadata (CLI)

{{Short description|Common Language Infrastructure metadata about classes and class members}}
{{Use mdy dates|date=January 2019}}
{{Use American English|date=January 2019}}
{{More references | date=July 2016}}
{{Infobox file format
| name          = CLI metadata, on-disk representation
| icon          = 
| standard      = [[ECMA-335|ECMA-335 part II]]
| url           = 
| magic         = 0x424A5342
| developer     = [[Microsoft]],<br />[[Ecma International]]
| type          = 
| extension     = {{code|.exe}}, {{code|.dll}}, {{code|.winmd}}
| extensions    = 
| mime          = 
}}
'''Metadata''', in the [[Common Language Infrastructure]] (CLI), refers to certain data structures embedded within the [[Common Intermediate Language]] (CIL) code that describes the high-level structure of the code. Metadata describes all [[class (computer science)|classes]] and class members that are defined in the assembly, and the classes and class [[Method (computer science)|members]] that the current assembly will call from another assembly. The metadata for a method contains the complete description of the method, including the class (and the assembly that contains the class), the [[return type]] and all of the method [[parameter (computer science)|parameter]]s.

A [[List of CLI languages|CLI language]] [[compiler]] will generate the [[metadata]] and store this in the [[Assembly (CLI)|assembly]] containing the [[Common Intermediate Language|CIL]]. When the run-time executes CIL it will check to make sure that the metadata of the called method is the same as the metadata that is stored in the calling method. This ensures that a method can only be called with exactly the right number of parameters and exactly the right parameter types.

The [[Windows Runtime]] application platform, present in [[Windows 8]] and [[Windows Phone 8]], makes use of the CLI metadata format to describe [[Component-oriented programming|component]] [[interface (object-oriented programming)|interface]]s for code written in any of the supported [[programming language]]s. A difference in use within the [[Common Language Runtime]] is that an assembly typically does not contain any CIL instructions.<ref>{{cite web |title=Windows Metadata (WinMD) files |url=https://docs.microsoft.com/en-us/uwp/winrt-cref/winmd-files |website=Windows UWP applications |date=December 30, 2021 |language=en-us}}</ref>

==Attributes==
Developers can add metadata to their code through ''attributes''. There are two types of attributes, custom and pseudo custom attributes, and to the developer these have the same [[syntax#Computer science|syntax]]. Attributes in code are messages to the compiler to generate metadata. In CIL, metadata such as inheritance modifiers, scope modifiers, and almost anything that isn't either opcodes or streams, are also referred to as attributes.

A custom attribute is a regular [[class (computing)|class]] that [[inheritance|inherits]] from the <code>Attribute</code> class. A custom attribute can be used on any method, property, class or entire assembly with the syntax: <code>[''AttributeName''(optional ''parameter'', optional ''name=value'' pairs)]</code> as in:
<syntaxhighlight lang="csharp">
[Custom]
[Custom(1)]
[Custom(1, Comment="yes")]
</syntaxhighlight>

Custom attributes are used by CLI extensively. [[Windows Communication Framework]] uses attributes to define service contracts, [[ASP.NET]] uses these to expose methods as [[web service]]s, [[LINQ|LINQ to SQL]] uses them to define the mapping of classes to the underlying [[Database schema|relational schema]], [[Visual Studio]] uses them to group together [[Property (programming)|properties]] of an object, the class developer indicates the category for the object's class by applying the <code>[Category]</code> custom attribute. Custom attributes are interpreted by application code and not the CLR. When the compiler sees a custom attribute it will generate custom metadata that is not recognised by the CLR. The developer has to provide code to read the metadata and act on it. As an example, the attribute shown in the example can be handled by the code:

<syntaxhighlight lang="csharp">
class CustomAttribute : Attribute
{
   private int paramNumber = 0;
   private string comment = "";

   public CustomAttribute() { }
   public CustomAttribute(int num) { paramNumber = num; }

   public String Comment
   {
      set { comment = value; }
   }
}
</syntaxhighlight>

The name of the class is mapped to the attribute name. The [[Visual C Sharp|Visual C#]] compiler automatically adds the string "<code>Attribute</code>" at the end of any attribute name.  Consequently, every attribute class name should end with this string, but it is legal to define an attribute without the <code>Attribute</code>-suffix. When affixing an attribute to an item, the compiler will look for both the literal name and the name with <code>Attribute</code> added to the end, i.&nbsp;e. if you were to write <code>[Custom]</code> the compiler would look for both <code>Custom</code> and <code>CustomAttribute</code>. If both exist, the compiler fails. The attribute can be prefixed with "<code>@</code>" if you don't want to risk ambiguity, so writing <code>[@Custom]</code> will not match <code>CustomAttribute</code>. Using the attribute invokes the constructor of the class. Overloaded constructors are supported. Name-Value pairs are mapped to properties, the name denotes the name of the property and the value supplied is set by the property.

Sometimes there is ambiguity concerning to what you are affixing the attribute. Consider the following code:

<syntaxhighlight lang="csharp">
[Orange]
public int ExampleMethod(string input)
{
    //method body goes here
}
</syntaxhighlight>

What has been marked as orange? Is it the <code>ExampleMethod</code>, its return value, or perhaps the entire assembly? In this case, the compiler will default, and treat the attribute as being affixed to the method. If this is not what was intended, or if the author wishes to clarify their code, an ''attribute target'' may be specified. Writing <code>[return: Orange]</code> will mark the return value as orange, <code>[assembly: Orange]</code> will mark the entire assembly. The valid targets are <code>assembly</code>, <code>field</code>, <code>event</code>, <code>method</code>, <code>module</code>, <code>param</code>, <code>property</code>, <code>return</code> and <code>type</code>.

A pseudo-custom attribute is used just like regular custom attributes but they do not have a custom handler; rather the compiler has intrinsic awareness of the attributes and handles the code marked with such attributes differently.  Attributes such as <code>Serializable</code> and <code>Obsolete</code> are implemented as pseudo-custom attributes. Pseudo-custom attributes should never be used by [[ILAsm]], as it has adequate syntax to describe the metadata.{{Clarify me|date=March 2008}}
<!-- What the hell does this mean? Was something vandalized out? If someone can make sense, please add this back.
A pseudo custom attribute is metadata that  public class MyClass
 {
    ...
 }
-->

==Metadata storage==
Assemblies contain tables of metadata. These tables are described by the CIL specification. The metadata tables will have zero or more entries and the position of an entry determines its index. When CIL code uses metadata it does so through a metadata token. This is a 32-[[bit]] value where the top 8 bits identify the appropriate metadata table, and the remaining 24 bits give the index of the metadata in the table. The Framework [[Software development kit|SDK]] contains a sample called {{code|metainfo}} that will list the metadata tables in an assembly, however, this information is rarely of use to a developer. Metadata in an assembly may be viewed using the ILDASM tool provided by the [[.NET Framework]] SDK.

In the CIL standard, metadata is defined in ILAsm (assembly language) form, an on-disk representation form for storage, and a form that is embedded into assemblies of the [[Portable Executable]] (PE, .exe or .dll) format. The PE form is based on the on-disk form.

== Reflection ==
{{main|Reflection (computer science)#C.23|l1=Reflection in C#|Reflection (computer programming)}}
Reflection is the [[Application programming interface|API]] used to read CLI metadata. The reflection API provides a logical view of metadata rather than the literal view provided by tools like metainfo. Reflection in version 1.1 of the .NET framework can be used to inspect the descriptions of classes and their members, and invoke methods. However, it does not allow runtime access to the CIL for a method. Version 2.0 of the framework allows the CIL for a method to be obtained.

== Other metadata tools ==
Besides the {{code|System{{Not a typo|.}}Reflection}} namespace, other tools are also available that can be used to handle metadata. The Microsoft .NET Framework ships a CLR metadata manipulation library that is implemented in [[native code]]. Third-party tools to retrieve and manipulate metadata include [https://web.archive.org/web/20070205053546/http://www.postsharp.org/ PostSharp] and [http://www.mono-project.com/Cecil Mono Cecil] can also be used.

==See also==
* [[Java annotation]]

==References==
{{Reflist}}

{{Common Language Infrastructure}}

[[Category:Common Language Infrastructure]]