.NET Framework Documentation

API Terms and Conventions

This document outlines the standard terms and conventions used throughout the .NET Framework API documentation. Understanding these terms will help you navigate and utilize the API reference more effectively.

General Terms

  • Namespace: A hierarchical organization of types (classes, interfaces, enums, delegates, etc.). Namespaces help prevent naming conflicts and group related types. For example, System.Collections.Generic contains collection types.
  • Type: A fundamental unit in .NET, representing a class, struct, interface, enum, or delegate. Types define data and behavior.
  • Member: A component of a type, such as a field, property, method, event, constructor, or indexer.
  • Assembly: A physical file (typically a .dll or .exe) that contains one or more types and is the unit of deployment, versioning, and reuse in .NET.
  • Metadata: Information about the types and members within an assembly, which the .NET runtime uses to understand and interact with the code.

Member Modifiers and Accessibility

The following keywords define the accessibility and behavior of members:

  • `public`: Accessible from any other code in any assembly.
  • `internal`: Accessible only within the same assembly.
  • `protected`: Accessible within its own class and by derived classes.
  • `private`: Accessible only within its own class.
  • `protected internal`: Accessible from any assembly or from derived classes within the same assembly.
  • `private protected`: Accessible within its own assembly or by derived classes in the same assembly.
  • `static`: The member belongs to the type itself, not to any specific instance of the type. You can access static members directly using the type name (e.g., Math.PI).
  • `abstract`: The member is not implemented in the current type and must be implemented by a derived type.
  • `virtual`: The member can be overridden by a derived type.
  • `override`: The member provides a specific implementation for a virtual or abstract member inherited from a base type.
  • `sealed`: Prevents a class from being inherited or a method from being overridden.
  • `readonly`: Indicates that the field's value can only be assigned during initialization or in the constructor.

Type Designators

  • `class`: Defines a reference type that can be instantiated. Classes support inheritance.
  • `struct`: Defines a value type. Value types are typically smaller and are copied by value.
  • `interface`: Defines a contract of methods, properties, events, and indexers that a class or struct must implement.
  • `enum`: Defines a set of named constants.
  • `delegate`: Represents a reference type that can be used to encapsulate a method with a specific signature.

Common Method Types

  • Constructor: A special member used to create and initialize instances of a type. It has the same name as the type and no return type.
  • Property: A member that provides a flexible mechanism to read, write, or compute the value of a private field. Properties use get and set accessors.
  • Method: A block of code that performs a specific task.
  • Event: A mechanism that allows an object to notify other objects when something significant happens.
  • Indexer: Allows an instance of a class or struct to be indexed as if it were an array.

Documentation Conventions

API documentation entries typically include:

  • A brief description of the type or member.
  • A detailed explanation, often including usage examples.
  • Information about parameters for methods and constructors.
  • Return value descriptions for methods.
  • Exceptions that might be thrown.
  • Notes on thread safety, inheritance, or other important considerations.
  • Links to related types or members.

For example, a method signature might look like this:

public static int CalculateSum(int number1, int number2)

Here:

  • public and static are modifiers.
  • int is the return type.
  • CalculateSum is the method name.
  • (int number1, int number2) are the parameters with their types and names.