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.

.NET Only

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).

AssemblyVersionAttribute, AssemblyFileVersionAttribute

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.

Out

Used to mark out params. The .NET runtime passes out parameters by passing them as "by reference" (similar to the var or 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

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.

Conditional

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.

Obsolete

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).

StructLayout/FieldOffset

  • See Records for modifying record storage layouts.

Guid

The compiler will enforce proper GUID format for string constants used with the GuidAttribute.

Debuggable

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.

MethodImpl

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.

Security Attributes

Oxygene provides full support for understanding security attributes and generating the appropriate XML structures inside the output assembly.

CoClass

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.

CLSCompliant

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.

See Unmanaged Exports

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.

See Also