.NET Custom API Documentation

Welcome to the custom API documentation for the .NET framework. This section covers extension points, customization hooks, and advanced features that allow you to tailor the .NET runtime and its libraries to your specific needs.

Introduction to Customization

The .NET platform is designed with extensibility in mind. Whether you're building domain-specific languages, integrating with third-party systems, or creating advanced debugging tools, understanding these custom APIs is crucial.

This documentation provides detailed information on:

Runtime extensibility points
Custom attribute creation and usage
Reflection and metadata manipulation
Custom serialization and deserialization
Advanced diagnostics and profiling interfaces

Core Customization Namespaces

Explore the primary namespaces that provide the building blocks for .NET customization.

System.Reflection

The System.Reflection namespace provides types that allow you to inspect the assembly, modules, and types contained within an assembly, as well as list the members of a type and invoke methods on those members.

System.Reflection.Emit: Enables the creation of custom types and members at runtime.
System.Reflection.CustomAttributeExtensions: Provides methods for retrieving custom attributes from reflected elements.

System.Runtime.CompilerServices

This namespace provides types that enable compiler support for custom languages and for the implementation of language features.

System.Runtime.CompilerServices.InternalsVisibleToAttribute: Allows specifying assemblies that can access internal members.
System.Runtime.CompilerServices.DynamicRuntimeAttribute: Used to mark types that are dynamically generated.

System.ComponentModel

Offers types that support the creation of custom components and extend the design-time and run-time behavior of .NET objects.

System.ComponentModel.TypeConverter: Base class for converting between different types of objects.
System.ComponentModel.Attribute: Base class for attributes that can be applied to code elements.

System.Reflection.Emit

This sub-namespace allows you to dynamically generate Microsoft intermediate language (MSIL) and create assemblies and modules at runtime. This is essential for Just-In-Time (JIT) compilers, code generation tools, and dynamic proxies.

ILGenerator

The ILGenerator class provides a set of methods that allow you to generate Microsoft intermediate language (MSIL) instructions.

Example Usage:

                    // Define a method that adds two integers

                    DynamicMethod dm = new DynamicMethod("Add", typeof(int), new Type[] { typeof(int), typeof(int) });

                    ILGenerator il = dm.GetILGenerator();

                    il.Emit(OpCodes.Ldarg_0);

                    il.Emit(OpCodes.Ldarg_1);

                    il.Emit(OpCodes.Add);

                    il.Emit(OpCodes.Ret);

                    // Create a delegate to the generated method

                    Func<int, int, int> addDelegate = (Func<int, int, int>)dm.CreateDelegate(typeof(Func<int, int, int>));

                    // Invoke the method

                    int result = addDelegate(5, 10); 

                    Console.WriteLine($"Result: {result}");

System.Reflection.CustomAttributeExtensions

Easily retrieve and work with custom attributes applied to types, members, and parameters.

GetCustomAttribute<T> Method

A convenient extension method to retrieve a custom attribute of a specified type.

Example Usage:

                    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]

                    public class CustomDocumentationAttribute : Attribute {

                        public string Description { get; }

                        public CustomDocumentationAttribute(string description) { Description = description; }

                    }

                    [CustomDocumentation("This is a sample class.")]

                    public class MyClass {

                        [CustomDocumentation("This method performs an operation.")]

                        public void MyMethod() {}

                    }

                    // Retrieving attributes

                    Type type = typeof(MyClass);

                    CustomDocumentationAttribute classAttr = type.GetCustomAttribute<CustomDocumentationAttribute>();

                    if (classAttr != null) { Console.WriteLine($"Class Description: {classAttr.Description}"); }

                    MethodInfo methodInfo = type.GetMethod("MyMethod");

                    CustomDocumentationAttribute methodAttr = methodInfo.GetCustomAttribute<CustomDocumentationAttribute>();

                    if (methodAttr != null) { Console.WriteLine($"Method Description: {methodAttr.Description}"); }

System.Runtime.CompilerServices.InternalsVisibleToAttribute

Use this attribute to grant access to your assembly's internal members to specified friend assemblies. This is common in library development for testing or modular design.

Usage

Add the attribute to your assembly's global attributes file (e.g., AssemblyInfo.cs or AssemblyAttributes.cs).

                    // In your main assembly

                    [assembly: InternalsVisibleTo("MyAssembly.Tests")]

                    [assembly: InternalsVisibleTo("MyAssembly.FriendModule")]

                    // In the friend assembly (e.g., MyAssembly.Tests)

                    internal class InternalHelper {

                        public void DoSomething() { /* ... */ }

                    }

The MyAssembly.Tests and MyAssembly.FriendModule assemblies will now be able to access members marked as internal within the main assembly.