Special Attributes for .NET
In addition to normal Custom Attributes and Predefined Aspects and Attributes provided by the compiler, the Elements compiler provides support for the special, attribute classes defined by the .NET Framework itself. In many cases, these attributes result in specific code or data to be generated in the executable, or in changed the compiler behavior.
These attributes or aspects are available for the .NET platform only.
AssemblyKeyFile, AssemblyKeyName, AssemblyDelaySign
These attributes control strong-naming and signing of the assembly, as required for installation in the Global Assembly Cache (GAC).
These two attributes specify the version numbering of the output assembly.
If AssemblyFileVersionAttribute is not specified, the AssemblyVersionAttribute value is used for both the string name and the Win32 file version. If it is specified, the AssemblyFileVersion will be for the Win32 version resource and the AssemblyVersion will go into the strong name.
AssemblyCompany, AssemblyProduct, AssemblyCopyright, AssemblyTrademarkAttribute, AssemblyCulture, AssemblyDescription
These attributes contribute additional fields to the assembly strong name and or version information.
Used to mark
out params. The .NET runtime passes
out parameters by passing them as "by
reference" (similar to the
ref keyword) and setting the
Out attribute on the parameter.
ComImport, In, Optional, MarshalAs, NonSerializable, Serializable, PreserveSig
These are not real custom attributes, but represent flags in the IL. Oxygene knows about these and correctly maps them to the underlying flags.
DllImport is used to import functions from unmanaged dlls (such as Win32 dlls or shared objects and dylibs on Linux or Mac, with Mono. A static method header can be defined in a class, and the DllImport attribute can be added to specify what dll and what function to import (and possibly more details on how to marshal parameters back and forth) and calls to this method will be directed to the external Win32 dll.
DllImportfor more information.
This attribute is used to mark types or members for conditional compilation.
The compiler will link calls to members with this attribute only if the matching define is set. For example, most methods in RemObjects.DebugServer.dll have the
[Conditional("DEBUG")] attribute. This means that if you write code referencing this assembly and use those methods, the actual calls will only be generated if the "
DEBUG" define is set for the project or via \$IFDEF.
The nice thing about ConditionalAttribute is that it not only works within the same assembly as traditional IFDEFs, but also across assembly boundaries. The DebugServer assembly, for example, is written in C# and completely outside of the control of the Oxygene compiler - yet the Oxygene-written code will behave differently depending on what defines it is compiled with.
Conditionalfor more information.
This attribute marks types or members (or entire assemblies) as obsolete. When the compiler notices that you are using an item marked with this attribute, it will generate the appropriate warning or error (depending on the parameters supplied to the attribute).
Obsoletefor more information.
- See Records for modifying record storage layouts.
The compiler will enforce proper GUID format for string constants used with the GuidAttribute.
The compiler will emit this assembly level attribute automatically when compiling, however, when it's present, the compiler will use the one defined in code.
An attribute that changes the flags of a MethodDef in the metadata. Used for ComImport and internal calls. Generally these shouldn't be used as they might create invalid code, depending on the combination of flags.
Oxygene provides full support for understanding security attributes and generating the appropriate XML structures inside the output assembly.
This attribute is used in COM imports to define what class is a co-class for the interface this is applied to. When it is defined, the
new operator will work on interfaces and it will instantiate the proper co-class.
This attribute is used to define whether a type or member is compliant with the Common Language Specification (CLS).
UnmanagedExport & NativeExport
This is a special attribute that can be used to export a class method as an unmanaged dll export entry.
CallerFilePath, CallerMemberName, CallerLineNumber
When applied to a parameter (with a default set) the compiler will insert the filename, member name or line number of the caller. Useful for logging purposes:
public static void Test([CallerMemberName] string mn = "",
[CallerFilePath] string fp = "",
[CallerLineNumber] int ln = 0)
Console.WriteLine("member name: " + mn);
Console.WriteLine("file path: " + fp);
Console.WriteLine("line number: " + ln);
Test(); // will emit the name, filename and line number of the current location.