The System.Object class is the root of the class hierarchy and serves as the base class for every other class. The C# object type aliases System.Object. System.Object provides a handful of useful methods that are present on all objects, and whose signatures are listed in the following fragment of the System.Object class definition:

public class Object {
   public Object(  ) {...}
   public virtual bool Equals(object o) {...}
   public virtual int GetHashCode(  ){...}
   public Type GetType(  ){...}
   public virtual string ToString(  ) {...}
   protected virtual void Finalize(  ) {...}
   protected object MemberwiseClone(  ) {...}
   public static bool Equals (object a, object b) {...}
   public static bool ReferenceEquals (object a, object b) {...}
}

// Point3D - a 3D point
// Compile with: csc /t:library Point3D.cs
using System;
public sealed class Point3D {
  int x, y, z;
  public Point3D(int x, int y, int z) {
    this.x=x; this.y=y; this.z=z; // Initialize data
  }
  public override bool Equals(object o) {
    if (o == (object) this) return true; // Identity test
    if (o == null) return false; // Safety test
    if (!(o is Point3D)) // Type equivalence test
      return false;
    Point3D p = (Point3D) o;
    return ((this.x==p.x) && (this.y==p.y) && (this.z==p.z));
  }
  public override int GetHashCode(  ){
    return ((((37+x)*37)+y)*37)+z; // :-)
  }
  public override string ToString(  ) {
    return String.Format("[{0},{1},{2}]", x, y, z);
  }
}

// TestPoint3D - test the 3D point type
// Compile with: csc /r:Point3D.dll TestPoint3D.cs
using System;
using System.Collections;
class TestPoint3D {
  static void Main(  ) {
    // Uses ToString, prints "p1=[1,1,1] p2=[2,2,2] p3=[2,2,2]"
    Point3D p1 = new Point3D(1,1,1);
    Point3D p2 = new Point3D(2,2,2);
    Point3D p3 = new Point3D(2,2,2);
    Console.WriteLine("p1={0} p2={1} p3={2}", p1, p2, p3);

    // Tests for equality to demonstrate Equals
    Console.WriteLine(Equals(p1, p2)); // Prints "False"
    Console.WriteLine(Equals(p2, p3)); // Prints "True"

    // Use a hashtable to cache each point's variable name
    // (uses GetHashCode).
    Hashtable ht = new Hashtable(  );
    ht[p1] = "p1"; 
    ht[p2] = "p2";
    ht[p3] = "p3"; // replaces ht[p2], since p2 == p3

    // Prints:
    //    p1 is at [1,1,1]
    //    p3 is at [2,2,2] 
    foreach (DictionaryEntry de in ht)
      Console.WriteLine("{0} is at {1} ", de.Value, de.Key);
  }
}

public interface ICloneable {
  object Clone(  );
}

ICloneable allows class or struct instances to be cloned. It contains a single method named Clone that returns a copy of the instance. When implementing this interface your Clone method can simply return this.MemberwiseClone( ), which performs a shallow copy (the fields are copied directly), or you can perform a custom deep copy, in which you clone individual fields in the class or struct.The following example is the simplest implementation of ICloneable:

public class Foo : ICloneable {
      public object Clone(  ) {
       return this.MemberwiseClone(  );
   }
}

interface IComparable {
  int CompareTo(object o);
}

IComparable is implemented by types that have instances that can be ordered (see Section 3.4). It contains a single method named CompareTo that:

This interface is implemented by all numeric types: string, DateTime, etc. It may also be implemented by custom classes or structs to provide comparison semantics. For example:

using System;
using System.Collections;
class MyType : IComparable {
  public int x;
  public MyType(int x) {
    this.x = x;
  }
  public int CompareTo(object o) {
    return x -((MyType)o).x;
  }
}
class Test {
  static void Main(  ) {
    ArrayList a = new ArrayList(  );
    a.Add(new MyType(42));
    a.Add(new MyType(17));
    a.Sort(  );
    foreach(MyType t in a)
      Console.WriteLine(((MyType)t).x);
   }
}

public interface IFormattable {
  string ToString(string format, IFormatProvider formatProvider);
}

The IFormattable interface is implemented by types that have formatting options for converting their value to a string representation. For instance, a decimal may be converted to a string representing currency or to a string that uses a comma for a decimal point. The formatting options are specified by the format string (see Section 3.3.4 later in this chapter). If an IFormatProvider interface is supplied, it specifies the specific culture to be used for the conversion.

IFormattable is commonly used when calling one of the String class Format methods (see Section 3.3).

All the common types (int, string, DateTime, etc.) implement this interface, and you should implement it on your own types if you want them to be fully supported by the String class when formatting.

C# has many useful features for math and can even build custom mathematical types. Operator overloading allows custom mathematical types, such as complex numbers and vectors, to be used in a natural way. Rectangular arrays provide a fast and easy way to express matrices. Finally, structs allow the efficient creation of low-overhead objects. For example:

struct Vector {
  float direction;
  float magnitude;
  public Vector(float direction, float magnitude) {
    this.direction = direction;
    this.magnitude = magnitude;
  }
  public static Vector operator *(Vector v, float scale) {
    return new Vector(v.direction, v.magnitude * scale);
  }
  public static Vector operator /(Vector v, float scale) {
    return new Vector(v.direction, v.magnitude * scale);
  }
  // ...
}
class Test {
  static void Main(  ) {
  Vector [,] matrix = {{new Vector(1f,2f), new Vector(6f,2f)},
                       {new Vector(7f,3f), new Vector(4f,9f)}};
  for (int i=0; i<matrix.GetLength(0); i++)
    for (int j=0; j<matrix.GetLength(1); j++)
      matrix[i, j] *= 2f;
  }
}

The decimal datatype is useful for financial calculations, since it is a base₁₀ number that can store 28 to 29 significant figures (see Section 2.2.5.3).

The checked operator allows integral operations to be bounds checked (see Section 2.4.2).

The Math class provides static methods and constants for basic mathematical purposes. All trigonometric and exponential functions use the double type, and all angles use radians. For example:

using System;
class Test {
  static void Main(  ) {
    double a = 3;
    double b = 4;
    double C = Math.PI / 2;
    double c = Math.Sqrt (a*a+b*b-2*a*b*Math.Cos(C));
    Console.WriteLine("The length of side c is "+c);
  }
}

The Random class produces pseudo-random numbers and may be extended if you require greater randomness (for cryptographically strong random numbers, see the System.Security.Cryptography.RandomNumberGenerator class). The random values returned are always between a minimum (inclusive) value and a maximum (exclusive) value. By default, the Random class uses the current time as its seed, but a custom seed can also be supplied to the constructor. Here’s a simple example:

Random r = new Random(  );
Console.WriteLine(r.Next(50)); // return between 0 and 50

A C# string represents an immutable sequence of characters and aliases the System.String class. Strings have comparison, appending, inserting, conversion, copying, formatting, indexing, joining, splitting, padding, trimming, removing, replacing, and searching methods. The compiler converts + operations on operands where the left operand is a string to Concat methods and preevaluates and interns string constants wherever possible.

Strings are immutable, which means they can’t be modified after creation. Consequently, many of the methods that initially appear to modify a string actually create a new string:

string a = "Heat";
string b = a.Insert(3, "r");
Console.WriteLine(b); // Prints Heart

If you need a mutable string, see the StringBuilder class.

In addition, the immutability of strings enable all strings in an application to be interned. Interning describes the process whereby all the constant strings in an application are stored in a common place, and any duplicate strings are eliminated. This saves space at runtime but creates the possibility that multiple string references will point at the same spot in memory. This can be the source of unexpected results when comparing two constant strings, as follows:

string a = "hello";
string b = "hello";
Console.WriteLine(a == b); // True for String only
Console.WriteLine(a.Equals(b)); // True for all objects
Console.WriteLine(Object.ReferenceEquals(a, b)); // True!!

The Format method provides a convenient way to build strings that embed string representations of a variable number of parameters. Each parameter can be of any type, including both predefined types and user-defined types.

The Format method takes a format-specification string and a variable number of parameters. The format-specification string defines the template for the string and includes format specifications for each of the parameters. The syntax of a format specifier looks like this:

{ParamIndex[,MinWidth][:FormatString]}

In the following example, we embed a basic string representation of the account variable (param 0) and a monetary string representation of the cash variable (param 1, C=Currency):

using System;
class TestFormatting {
  static void Main(  ) {
    int i = 2;
    decimal m = 42.73m;
    string s = String.Format("Account {0} has {1:C}.", i, m);
    Console.WriteLine(s); // Prints "Account 2 has $42.73"
  }
}

Consistent with all other indexing in the CLR, the characters in a string are accessed with a zero-based index:

using System;
class TestIndexing {
  static void Main(  ) {
    string s = "Going down?";
    for (int i=0; i<s.Length; i++)
      Console.WriteLine(s[i]); // Prints s vertically
  }
}

Strings can be converted between different character encodings using the Encoding type. The Encoding type can’t be created directly, but the ASCII, Unicode, UTF7, UTF8, and BigEndianUnicode static properties on the Encoding type return correctly constructed instances.

Here is an example that converts an array of bytes into a string using the ASCII encoding:

using System;
using System.Text;
class TestEncoding {
  static void Main(  ) {
    byte[] ba = new byte[] { 67, 35, 32, 105, 115, 
                             32, 67, 79, 79, 76, 33 };
    string s = Encoding.ASCII.GetString(ba);
    Console.WriteLine(s);
  }
}

The StringBuilder class is used to represent mutable strings. It starts at a predefined size (16 characters by default) and grows dynamically as more string data is added. It can either grow unbounded or up to a configurable maximum. For example:

using System;
using System.Text;
class TestStringBuilder {
  static void Main(  ) {
    StringBuilder sb = new StringBuilder("Hello, ");
    sb.Append("World?");
    sb[12] = '!';
    Console.WriteLine(sb); // Hello, World!
  }
}

The FCL includes the concrete implementations of the collection design patterns that are described in this section.

Unlike C++, C# doesn’t yet support templates, so these implementations work generically by accepting elements of type System.Object.

ArrayList a = new ArrayList(  );
a.Add("Vernon");
a.Add("Corey");
a.Add("William");
a.Add("Muzz");
a.Sort(  );
for(int i = 0; i < a.Count; i++)
   Console.WriteLine(a [i]);

BitArray bits = new BitArray( 0 ); // initialize a zero-length bit array
bits.Length = 2;
bits[1] = true;
bits.Xor(bits); // Xor the array with itself

Hashtable ht = new Hashtable(  );
ht["One"] = 1;
ht["Two"] = 2;
ht["Three"] = 3;
Console.WriteLine(ht["Two"]); // Prints "2"

Queue q = new Queue(  );
q.Enqueue(1);
q.Enqueue(2);
Console.WriteLine(q.Dequeue(  )); // Prints "1"
Console.WriteLine(q.Dequeue(  )); // Prints "2"

SortedList s = new SortedList(  );
s["Zebra"] = 1;
s["Antelope"] = 2;
s["Eland"] = 3;
s["Giraffe"] = 4;
s["Meerkat"] = 5;
s["Dassie"] = 6;
s["Tokoloshe"] = 7;
Console.WriteLine(s["Meerkat"]); // Prints "5" in 3 lookups

Stack s = new Stack(  );
s.Push(1); // Stack = 1
s.Push(2); // Stack = 1,2
s.Push(3); // Stack = 1,2,3
Console.WriteLine(s.Pop(  )); // Prints 3, Stack=1,2
Console.WriteLine(s.Pop(  )); // Prints 2, Stack=1
Console.WriteLine(s.Pop(  )); // Prints 1, Stack=

StringCollection sc = new StringCollection(  );
sc.Add("s1");
string[] sarr =  {"s2", "s3", "s4"};
sc.AddRange(sarr);
foreach (string s in sc)
  Console.Write("{0} ", s); // s1 s2 s3 s4

The collection interfaces provide standard ways to enumerate, populate, and author collections. The FCL defines the interfaces in this section to support the standard collection design patterns.

public interface IEnumerable {
  IEnumerator GetEnumerator(  );
}

public interface IEnumerator {
   bool MoveNext(  );
   object Current {get;}
   void Reset(  );
}

using System;
using System.Collections;
public class MyCollection : IEnumerable {
  // Contents of this collection.
  private string[] items = {"hello", "world"};
  // Accessors for this collection.
  public string this[int index] { 
    get { return items[index]; }
  }
  public int Count {
    get { return items.Length; }
  }
  // Implement IEnumerable.
  public virtual IEnumerator GetEnumerator (  ) {
    return new MyCollection.Enumerator(this);
  }
  // Define a custom enumerator.
  private class Enumerator : IEnumerator { 
    private MyCollection collection;
    private int currentIndex = -1;
    internal Enumerator (MyCollection collection) {
      this.collection = collection;
    }
    public object Current {
      get {
        if (currentIndex==-1 || currentIndex == collection.Count)
          throw new InvalidOperationException(  );
        return collection [currentIndex];
      }
    }
    public bool MoveNext (  ) {
      if (currentIndex > collection.Count)
        throw new InvalidOperationException(  );
      return ++currentIndex < collection.Count;
    }
    public void Reset (  ) {
      currentIndex = -1;
    }
  }
}

MyCollection mcoll = new MyCollection(  );
// Using foreach: substitute your typename for 
string
foreach (
string item in mcoll) {
  Console.WriteLine(item);
}
// Using IEnumerator: substitute your typename for 
string
IEnumerator ie = mcoll.GetEnumerator(  );
while (ie.MoveNext(  )) {
  
string item = (
string) ie.Current;
  Console.WriteLine(item);
}

public interface ICollection : IEnumerable {
   void CopyTo(Array 
array, int 
index);
   int Count {get;}
   bool IsSynchronized {get;}
   object SyncRoot {get;}
}

public interface IComparer {
   int Compare(object x, object y);
}

public interface IList : ICollection, IEnumerable {
   object this [int index] {get; set}
   bool IsFixedSize { get; }
   bool IsReadOnly { get; }
   int Add(object o);
   void Clear(  );
   bool Contains(object value);
   int IndexOf(object value);
   void Insert(int index, object value);
   void Remove(object value);
   void RemoveAt(int index);
}

public interface IDictionary : ICollection, IEnumerable {
   object this [object key] {get; set};
   bool IsFixedSize { get; }
   bool IsReadOnly { get; }
   ICollection Keys {get;}
   ICollection Values {get;}
   void Clear(  );
   bool Contains(object key);
   IDictionaryEnumerator GetEnumerator(  );
   void Remove(object key);
}

public interface IDictionaryEnumerator : IEnumerator {
   DictionaryEntry Entry {get;}
   object Key {get;}
   object Value {get;}
}

public interface IHashCodeProvider {
   int GetHashCode(object o);
}

The Regex class is the heart of the FCL regular expression support. Used both as an object instance and a static type, the Regex class represents an immutable, compiled instance of a regular expression that can be applied to a string via a matching process.

Internally, the regular expression is stored as either a sequence of internal regular expression bytecodes that are interpreted at match time or as compiled MSIL opcodes that are JIT-compiled by the CLR at runtime. This allows you to make a tradeoff between worsened regular expression startup time and memory utilization versus higher raw match performance at runtime.

For more information on the regular expression options, supported character escapes, substitution patterns, character sets, positioning assertions, quantifiers, grouping constructs, backreferences, and alternation, see Appendix B.

The Match class represents the result of applying a regular expression to a string, looking for the first successful match. The MatchCollection class contains a collection of Match instances that represent the result of applying a regular expression to a string recursively until the first unsuccessful match occurs.

The Group class represents the results from a single grouping expression. From this class, it is possible to drill down to the individual subexpression matches with the Captures property.

The CaptureCollection class contains a collection of Capture instances, each representing the results of a single subexpression match.

Combining these classes, you can create the following example:

/*
 * Sample showing multiple groups
 * and groups with multiple captures
 */
using System;
using System.Text.RegularExpressions;
class Test {
  static void Main(  ) {
    string text = "abracadabra1abracadabra2abracadabra3";
    string pat = @"
      (       # start the first group
        abra  # match the literal 'abra'
        (     # start the second (inner) group
        cad   # match the literal 'cad'
        )?    # end the second (optional) group
      )       # end the first group
     +        # match one or more occurences
     ";
    Console.WriteLine("Original text = [{0}]", text);
    // Create the Regex. IgnorePatternWhitespace permits 
    // whitespace and comments.
    Regex r = new Regex(pat, RegexOptions.IgnorePatternWhitespace);
    int[] gnums = r.GetGroupNumbers(  ); // get the list of group numbers
    Match m = r.Match(text); // get first match
    while (m.Success) {
      Console.WriteLine("Match found:");
      // start at group 1
      for (int i = 1; i < gnums.Length; i++) {
        Group g = m.Groups[gnums[i]]; // get the group for this match
        Console.WriteLine("	Group{0}=[{1}]", gnums[i], g);
        CaptureCollection cc = g.Captures; // get caps for this group
        for (int j = 0; j < cc.Count; j++) {
          Capture c = cc[j];
          Console.WriteLine("		Capture{0}=[{1}] Index={2} Length={3}",
                            j, c, c.Index, c.Length);
        }
      }
      m = m.NextMatch(  ); // get next match
    } // end while
  }
}

The preceding example produces the following output:

Original text = [abracadabra1abracadabra2abracadabra3]
Match found:
        Group1=[abra]
                Capture0=[abracad] Index=0 Length=7
                Capture1=[abra] Index=7 Length=4
        Group2=[cad]
                Capture0=[cad] Index=4 Length=3
Match found:
        Group1=[abra]
                Capture0=[abracad] Index=12 Length=7
                Capture1=[abra] Index=19 Length=4
        Group2=[cad]
                Capture0=[cad] Index=16 Length=3
Match found:
        Group1=[abra]
                Capture0=[abracad] Index=24 Length=7
                Capture1=[abra] Index=31 Length=4
        Group2=[cad]
                Capture0=[cad] Index=28 Length=3

A stream represents the flow of data coming in and out of a backing store. A backing store represents the endpoint of a stream. Although a backing store is often a file or network connection, in reality it can represent any medium capable of reading or writing raw data.

A simple example would be to use a stream to read and write to a file on disk. However, streams and backing stores are not limited to disk and network I/O. A more sophisticated example would be to use the cryptography support in the FCL to encrypt or decrypt a stream of bytes as they move around in memory.

using System.IO;
class Test {
  static void Main(  ) {
    Stream s = new FileStream("foo.txt", FileMode.Create);
    s.WriteByte(67);
    s.WriteByte(35);
    s.Close(  );
  }
}

using System.Text;
using System.IO;
class Test {
  static void Main(  ) {
    Stream fs = new FileStream ("foo.txt", FileMode.Create);
    StreamWriter sw = new StreamWriter(fs, Encoding.ASCII);
    sw.Write("Hello!");
    sw.Close(  );
  }
}

using System;
using System.IO;
using System.Text;
class Test {
  static void Main(  ) {
    StringBuilder sb = new StringBuilder(  );
    StringWriter sw = new StringWriter(sb);
    WriteHello(sw);
    Console.WriteLine(sb);
  }
  static void WriteHello(TextWriter tw) {
    tw.Write("Hello, String I/O!");
  }
}

The File and Directory classes encapsulate the operations typically associated with file I/O, such as copying, moving, deleting, renaming, and enumerating files and directories.

The actual manipulation of the contents of a file is done with a FileStream. The File class has methods that return a FileStream, though you may directly instantiate a FileStream.

In this example, you read in and print out the first line of a text file specified on the command line:

using System;
using System.IO;
class Test {
   static void Main(string[] args) {
      Stream s = File.OpenRead(args[0]);
      StreamReader sr = new StreamReader(s);
      Console.WriteLine(sr.ReadLine(  ));
      sr.Close(  );
   }
}

High-level access is performed using a set of types that implement a generic request/response architecture that is extensible to support new protocols. The implementation of this architecture in the FCL also includes HTTP-specific extensions to make interacting with web servers easy.

Should the application require lower-level access to the network, types exist to support the Transmission Control Protocol (TCP) and User Datagram Protocol (UDP). Finally, in situations in which direct transport-level access is required, there are types that provide raw socket access.

The request/response architecture is based on Uniform Resource Indicator (URI) and stream I/O, follows the factory design pattern, and makes good use of abstract types and interfaces.

A factory type (WebRequest) parses the URI and creates the appropriate protocol handler to fulfill the request.

Protocol handlers share a common abstract base type (WebRequest) that exposes properties that configure the request and methods used to retrieve the response.

Responses are also represented as types and share a common abstract base type (WebResponse) that exposes a Stream, providing simple streams-based I/O and easy integration into the rest of the FCL.

This example is a simple implementation of the popular Unix snarf utility. It demonstrates the use of the WebRequest and WebResponse classes to retrieve the contents of a URI and print them to the console:

// Snarf.cs
// Run Snarf.exe <http-uri> to retrieve a web page
using System;
using System.IO;
using System.Net;
using System.Text;
class Snarf {
  static void Main(string[] args) {

    // Retrieve the data at the URL with an WebRequest ABC
    WebRequest req = WebRequest.Create(args[0]);
    WebResponse resp = req.GetResponse(  );

    // Read in the data, performing ASCII->Unicode encoding
    Stream s = resp.GetResponseStream(  );
    StreamReader sr = new StreamReader(s, Encoding.ASCII);
    string doc = sr.ReadToEnd(  );

    Console.WriteLine(doc); // Print result to console
  }
}

The request/response architecture inherently supports protocol-specific extensions via the use of subtyping.

Since the WebRequest creates and returns the appropriate handler type based on the URI, accessing protocol-specific features is as easy as downcasting the returned WebRequest object to the appropriate protocol-specific handler and accessing the extended functionality.

The FCL includes specific support for the HTTP protocol, including the ability to easily access and control elements of an interactive web session, such as the HTTP headers, user-agent strings, proxy support, user credentials, authentication, keep-alives, pipelining, and more.

This example demonstrates the use of the HTTP-specific request/response classes to control the user-agent string for the request and retrieve the server type:

// ProbeSvr.cs
// Run ProbeSvr.exe <servername> to retrieve the server type
using System;
using System.Net;
class ProbeSvr {
  static void Main(string[] args) {

    // Get instance of WebRequest ABC, convert to HttpWebRequest
    WebRequest req = WebRequest.Create(args[0]);
    HttpWebRequest httpReq = (HttpWebRequest)req;

    // Access HTTP-specific features such as User-Agent
    httpReq.UserAgent = "CSPRProbe/1.0";

    // Retrieve response and print to console
    WebResponse resp = req.GetResponse(  );
    HttpWebResponse httpResp = (HttpWebResponse)resp;
    Console.WriteLine(httpResp.Server);
  }
}

Adding handlers to support new protocols is trivial: simply implement a new set of derived types based on WebRequest and WebResponse, implement the IWebRequestCreate interface on your WebRequest-derived type, and register it as a new protocol handler with Web-Request.RegisterPrefix( ) at runtime. Once this is done, any code that uses the request/response architecture can access networked resources using the new URI format (and underlying protocol).

The System.Net.Sockets namespace includes types that provide protocol-level support for TCP and UDP. These types are built on the underlying Socket type, which is itself directly accessible for transport-level access to the network.

Two classes provide the TCP support: TcpListener and TcpClient. TcpListener listens for incoming connections, creating Socket instances that respond to the connection request. TcpClient connects to a remote host, hiding the details of the underlying socket in a Stream-derived type that allows stream I/O over the network.

A class called UdpClient provides the UDP support. UdpClient serves as both a client and a listener and includes multicast support, allowing individual datagrams to be sent and received as byte arrays.

Both the TCP and the UDP classes help access the underlying network socket (represented by the Socket class). The Socket class is a thin wrapper over the native Windows sockets functionality and is the lowest level of networking accessible to managed code.

The following example is a simple implementation of the Quote of the Day (QUOTD) protocol, as defined by the IETF in RFC 865. It demonstrates the use of a TCP listener to accept incoming requests and the use of the lower-level Socket type to fulfill the request:

// QOTDListener.cs 
// Run QOTDListener.exe to service incoming QOTD requests
using System;
using System.Net;
using System.Net.Sockets;
using System.Text;
class QOTDListener {
  static string[] quotes = {
    @"Sufficiently advanced magic is indistinguishable from technology
         -- Terry Pratchett",
    @"Sufficiently advanced technology is indistinguishable from magic
         -- Arthur C. Clarke" };
  static void Main(  ) {

    // Start a TCP listener on port 17
    TcpListener l = new TcpListener(17);
    l.Start(  );
    Console.WriteLine("Waiting for clients to connect");
    Console.WriteLine("Press Ctrl+C to quit...");
    int numServed = 1;
    while (true) {

      // Block waiting for an incoming socket connect request
      Socket s = l.AcceptSocket(  );

      // Encode alternating quotes as bytes for sending 
      Char[] carr = quotes[numServed%2].ToCharArray(  );
      Byte[] barr = Encoding.ASCII.GetBytes(carr);

      // Return data to client, then clean up socket and repeat
      s.Send(barr, barr.Length, 0);
      s.Shutdown(SocketShutdown.Both);
      s.Close(  );
      Console.WriteLine("{0} quotes served...", numServed++);
    }
  }
}

To test this example, run the listener and try connecting to port 17 on localhost using a telnet client. (Under Windows, this can be done from the command line by entering telnet localhost 17).

Notice the use of Socket.Shutdown and Socket.Close at the end of the while loop. This is required to flush and close the socket immediately, rather than wait for the garbage collector to finalize and collect unreachable Socket objects later.

The networking types in the base class library also support normal and reverse Domain Name System (DNS) resolution. Here’s an example using these types:

// DNSLookup.cs
// Run DNSLookup.exe <servername> to determine IP addresses
using System;
using System.Net;
class DNSLookup {
  static void Main(string[] args) {
    IPHostEntry he = Dns.GetHostByName(args[0]);
    IPAddress[] addrs = he.AddressList;
    foreach (IPAddress addr in addrs)
      Console.WriteLine(addr);
  }
}

Thread synchronization comprises techniques for ensuring that multiple threads coordinate their access to shared resources.

using System;
using System.Threading;
class LockTest {
  static void Main(  ) {
    LockTest lt = new LockTest (  );
    Thread t = new Thread(new ThreadStart(lt.Go));
    t.Start(  );
    lt.Go(  );
  }
  void Go(  ) {
    lock(this)
      for ( char c='a'; c<='z'; c++)
        Console.Write(c);
  }
}

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz

System.Threading.Monitor.Enter(expression);
try {
  ...
}
finally {
  System.Threading.Monitor.Exit(expression);
}

using System;
using System.Threading;
class MonitorTest {
  static void Main(  ) {
    MonitorTest mt = new MonitorTest(  );
    Thread t = new Thread(new ThreadStart(mt.Go));
    t.Start(  );
    mt.Go(  );
  }
  void Go(  ) {
    for ( char c='a'; c<='z'; c++)
      lock(this) {
        Console.Write(c);
        Monitor.Pulse(this);
        Monitor.Wait(this);
      }
  }
}

aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz

void Go(  ) {
  for ( char c='a'; c<='z'; c++)
    lock(this) {
      Console.Write(c);
      Monitor.Pulse(this);
      if (c<'z')
        Monitor.Wait(this);
    }
}

Much of the functionality of threads is provided through the classes in the System.Threading namespace. The most basic thread class to understand is the Monitor class, which is explained in the following section.

The System.Threading.Monitor class provides an implementation of Hoare’s Monitor that allows you to use any reference-type instance as a monitor.

Every .NET application consists of at least one assembly, which is in turn built from a number of basic elements.

The manifest contains a set of metadata that describes everything the runtime needs to know about the assembly. This information includes:

Modules contain types described using metadata and implemented using MSIL.

Resources contain nonexecutable data that is logically included with the assembly. Examples of this include bitmaps, localizable text, persisted objects, etc.

The simplest assembly contains a manifest and a single module containing the application’s types, packaged as an EXE with a Main entry point. More complex assemblies can include multiple modules ( Portable Executable (PE) files), separate resource files, a manifest, etc.

The manifest is generally included in one of the existing PE files in the assembly, although the manifest can also be a standalone PE file.

Modules are PE files, typically DLLs or EXEs. Only one module in an assembly can contain an entry point (either Main, WinMain, or DllMain).

An assembly may also contain multiple modules. This technique can reduce the working set of the application, because the CLR loads only the required modules. In addition, each module can be written in a different language, allowing a mixture of C#, VB.NET, and raw MSIL. Although not common, a single module can also be included in several different assemblies.

Finally, an assembly may contain a set of resources, which can be kept either in standalone files or included in one of the PE files in the assembly.

An assembly is the smallest .NET unit of deployment. Due to the self-describing nature of a manifest, deployment can be as simple as copying the assembly (and in the case of a multifile assembly, all the associated files) into a directory.

This is a vast improvement over traditional COM development in which components, their supporting DLLs, and their configuration information are spread out over multiple directories and the Windows registry.

Generally, assemblies are deployed into the application directory and are not shared. These are called private assemblies. However, assemblies can also be shared between applications; these are called shared assemblies. To share an assembly you need to give it a shared name (also known as a “strong” name) and deploy it in the global assembly cache.

The shared name consists of a name, a public key, and a digital signature. The shared name is included in the assembly manifest and forms the unique identifier for the assembly.

The global assembly cache is a machine-wide storage area that contains assemblies intended for use by multiple applications.

For more information on working with shared assemblies and the global assembly cache, see Section E.1.4 in Appendix E.

The manifest of an application contains a version number for the assembly and a list of all the referenced assemblies with associated version information. Assembly version numbers are divided into four parts and look like this:

<major>.<minor>.<build>.<revision>

This information is used to mitigate versioning problems as assemblies evolve over time.

At runtime, the CLR uses the version information specified in the manifest and a set of versioning policies defined for the machine to determine which versions of each dependent, shared assembly to load.

The default versioning policy for shared assemblies restricts you to the version that your application was built against. By changing a configuration file, the application or an administrator can override this behavior.

Private assemblies have no versioning policy, and the CLR simply loads the newest assemblies found in the application directory.

The unique identifier for a type (known as a TypeRef) consists of a reference to the assembly it was defined in and the fully qualified type name (including any namespaces). For example, this local variable declaration:

System.Xml.XmlReader xr;

is represented in MSIL assembly language as follows:

.assembly extern System.Xml { .ver 1:0:3300:0 ... }
.locals init (class [System.Xml]System.Xml.XmlReader V_0)

In this example, the System.Xml.XmlReader type is scoped to the System.Xmlsharedassembly, which is identified using a shared name and associated version number.

When your application starts, the CLR attempts to resolve all static TypeRefs by locating the correct versions of each dependent assembly (as determined by the versioning policy) and verifying that the types actually exist (ignoring any access modifiers).

When your application attempts to use the type, the CLR verifies that you have the correct level of access and throws runtime exceptions if there is a versioning incompatibility.

The assembly forms a boundary for security permissioning.

The assembly manifest contains hashes for any referenced assemblies (determined at compile time), a list of the minimum set of security permissions the assembly requires in order to function, a list of the optional permissions that it requests, and a list of the permissions that it explicitly refuses (i.e., never wants to receive).

To illustrate how these permissions might be used, imagine an email client similar to Microsoft Outlook, developed using the .NET Framework. It probably requiresthe ability to communicate over the network on ports 110 (POP3), 25 (SMTP), and 143 (IMAP4). It might request the ability to run Java Script functions in a sandbox to allow for full interactivity when presenting HTML emails. Finally, it probably refusesever being granted the ability to write to disk or read the local address book, thus avoiding scripting attacks such as the ILoveYou virus.

Essentially, the assembly declares its security needs and assumptions, but leaves the final decision on permissioning up to the CLR, which enforces local security policy.

At runtime the CLR uses the hashes to determine if a dependent assembly has been tampered with and combines the assembly permission information with local security policy to determine whether to load the assembly and which permissions to grant it.

This mechanism provides fine-grained control over security and is a major advantage of the .NET Framework over traditional Windows applications.

Reflection involves traversing and manipulating an object model that represents an application, including all its compile-time and runtime elements. Consequently, it is important to understand the various logical units of a .NET application and their roles and relationships.

The fundamental units of an application are its types, which contain members and nested types. In addition to types, an application contains one or more modules and one or more assemblies. All these elements are static and are described in metadata produced by the compiler at compile time. The one exception to this rule is elements (such as types, modules, assemblies, etc.) that are created on the fly via Reflection.Emit, which is described in the later section Section 3.10.8.

At runtime, these elements are all contained within an AppDomain. An AppDomain isn’t described with metadata, yet it plays an important role in reflection because it forms the root of the type hierarchy of a .NET application at runtime.

In any given application, the relationship between these units is hierarchical, as depicted by the following diagram:

AppDomain (runtime root of hierarchy)
  Assemblies
    Modules
      Types
        Members
        Nested types

Each of these elements is discussed in the following sections.

At the heart of reflection is System.Type, which is an abstract base class that provides access to the metadata of a type.

You can access the Type class for any instance using GetType, which is a nonvirtual method of System.Object. When you call GetType, the method returns a concrete subtype of System.Type, which can reflect over and manipulate the type.

You can also retrieve a Type class by name (without needing an instance) using the static method GetType on the Type class, as follows:

Type t = Type.GetType("System.Int32");

Finally, C# provides the typeof operator, which returns the Type class for any type known at compile time:

Type t = typeof(System.Int32);

The main difference between these two approaches is that Type.GetType is evaluated at runtime and is more dynamic, binding by name, while the typeof operator is evaluated at compile time, uses a type token, and is slightly faster to call.

Once you have retrieved a Type instance you can navigate the application hierarchy described earlier, accessing the metadata via types that represent members, modules, assemblies, namespaces, AppDomains, and nested types. You can also inspect the metadata and any custom attributes, create new instances of the types, and invoke members.

Here is an example that uses reflection to display the members in three different types:

using System;
using System.Reflection;
class Test {
  static void Main(  ) {
    object o = new Object(  );
    DumpTypeInfo(o.GetType(  ));
    DumpTypeInfo(typeof(int));
    DumpTypeInfo(Type.GetType("System.String"));
  }
  static void DumpTypeInfo(Type t) {
    Console.WriteLine("Type: {0}", t);

    // Retrieve the list of members in the type
    MemberInfo[] miarr = t.GetMembers(  );

    // Print out details on each of them
    foreach (MemberInfo mi in miarr)
      Console.WriteLine("  {0}={1}", mi.MemberType, mi);
  }
}

Reflection can also perform late binding, in which the application dynamically loads, instantiates, and uses a type at runtime. This provides greater flexibility at the expense of invocation overhead.

In this section, we create an example that uses very late binding, dynamically discovers new types at runtime, and uses them.

In the example one or more assemblies are loaded by name (as specified on the command line) and iterated through the types in the assembly, looking for subtypes of the Greeting abstract base class. When one is found, the type is instantiated and its SayHello method invoked, which displays an appropriate greeting.

To perform the runtime discovery of types, we use an abstract base class that’s compiled into an assembly as follows (see the source comment for filename and compilation information):

// Greeting.cs - compile with /t:library
public abstract class Greeting { 
  public abstract void SayHello(  );
}

Compiling this code produces a file named Greeting.dll, which the other parts of the sample can use.

We now create a new assembly containing two concrete subtypes of the abstract type Greeting, as follows (see the source comment for filename and compilation information):

// English.cs - compile with /t:library /r:Greeting.dll
using System;
public class AmericanGreeting : Greeting {
  private string msg = "Hey, dude. Wassup!";
  public override void SayHello(  ) {
    Console.WriteLine(msg);
  }
}
public class BritishGreeting : Greeting {
  private string msg = "Good morning, old chap!";
  public override void SayHello(  ) {
    Console.WriteLine(msg);
  }
}

Compiling the source file English.cs produces a file named English.dll, which the main program can now dynamically reflect over and use.

Now we create the main sample, as follows (see the source comment for filename and compilation information):

// SayHello.cs - compile with /r:Greeting.dll
// Run with SayHello.exe <dllname1> <dllname2> ... <dllnameN>
using System;
using System.Reflection;
class Test {
  static void Main (string[] args) {

    // Iterate over the cmd-line options,
    // trying to load each assembly
    foreach (string s in args) {
      Assembly a = Assembly.LoadFrom(s);
      
      // Pick through all the public type, looking for
      // subtypes of the abstract base class Greeting
      foreach (Type t in a.GetTypes(  ))
        if (t.IsSubclassOf(typeof(Greeting))) {

          // Having found an appropriate subtype, create it
          object o = Activator.CreateInstance(t);

          // Retrieve the SayHello MethodInfo and invoke it
          MethodInfo mi = t.GetMethod("SayHello");
          mi.Invoke(o, null);
        }
    }
  }
}

Running the sample now with SayHello English.dll produces the following output:

Hey, dude. Wassup!
Good morning, old chap!

The interesting aspect of the preceding sample is that it’s completely late-bound; i.e., long after the SayHello program is shipped you can create a new type and have SayHello automatically take advantage of it by simply specifying it on the command line. This is one of the key benefits of late binding via reflection.

In the previous examples, we loaded an assembly by hand and used the System.Activator class to create a new instance based on a type. There are many overrides of the CreateInstance method that provide a wide range of creation options, including the ability to short-circuit the process and create a type directly:

object o = Activator.CreateInstance("Assem1.dll",
                                    "Friendly.Greeting");

Other capabilities of the Activator type include creating types on remote machines, creating types in specific AppDomains (sandboxes), and creating types by invoking a specific constructor (rather than using the default constructor as these examples show).

The preceding example demonstrates the use of reflection, but doesn’t perform any tasks you can’t accomplish using normal C# language constructs. However, reflection can also manipulate types in ways not supported directly in C#, as is demonstrated in this section.

While the CLR enforces access controls on type members (specified using access modifiers such as private and protected), these restrictions don’t apply to reflection. Assuming you have the correct set of permissions, you can use reflection to access and manipulate private data and function members, as this example using the Greeting subtypes from the previous section shows (see the source comment for filename and compilation information):

// InControl.cs - compile with /r:Greeting.dll,English.dll
using System;
using System.Reflection;
class TestReflection {
  // Note: This method requires the ReflectionPermission perm.
  static void ModifyPrivateData(object o, string msg) {

    // Get a FieldInfo type for the private data member
    Type t = o.GetType(  ); 
    FieldInfo fi = t.GetField("msg", BindingFlags.NonPublic|
                                     BindingFlags.Instance);

    // Use the FieldInfo to adjust the data member value
    fi.SetValue(o, msg);
  }
  static void Main(  ) {
    // Create instances of both types
    BritishGreeting bg = new BritishGreeting(  );
    AmericanGreeting ag = new AmericanGreeting(  );

    // Adjust the private data via reflection
    ModifyPrivateData(ag, "Things are not the way they seem");
    ModifyPrivateData(bg, "The runtime is in total control!");
    
    // Display the modified greeting strings
    ag.SayHello(  ); // "Things are not the way they seem"
    bg.SayHello(  ); // "The runtime is in total control!"
  }
}

When run, this sample generates the following output:

Things are not the way they seem
The runtime is in total control!

This demonstrates that the private msg data members in both types are modified via reflection, although there are no public members defined on the types that allow that operation. Note that while this technique can bypass access controls, it still doesn’t violate type safety.

Although this is a somewhat contrived example, the capability can be useful when building utilities such as class browsers and test suite automation tools that need to inspect and interact with a type at a deeper level than its public interface.

The System.Reflection.Emit namespace contains classes that can create entirely new types at runtime. These classes can define a dynamic assembly in memory; define a dynamic module in the assembly; define a new type in the module, including all its members; and emit the MSIL opcodes needed to implement the application logic in the members.

Here is an example that creates and uses a new type called HelloWorld with a member called SayHello:

using System;
using System.Reflection;
using System.Reflection.Emit;
public class Test {
  static void Main(  )  {
    // Create a dynamic assembly in the current AppDomain
    AppDomain ad = AppDomain.CurrentDomain;
    AssemblyName an = new AssemblyName(  );
    an.Name = "DynAssembly";
    AssemblyBuilder ab = 
      ad.DefineDynamicAssembly(an, AssemblyBuilderAccess.Run);
    
    // Create a module in the assembly and a type in the module
    ModuleBuilder modb = ab.DefineDynamicModule("DynModule");
    TypeBuilder tb = modb.DefineType("AgentSmith", 
                                     TypeAttributes.Public);
 
    // Add a SayHello member to the type 
    MethodBuilder mb = tb.DefineMethod("SayHello",        
                                       MethodAttributes.Public,
                                       null, null);
                                        
    // Generate the MSIL for the SayHello Member
    ILGenerator ilg = mb.GetILGenerator(  );
    ilg.EmitWriteLine("Never send a human to do a machine's job.");
    ilg.Emit(OpCodes.Ret);

    // Finalize the type so we can create it
    Type t = tb.CreateType(  );

    // Create an instance of the new type
    object o = Activator.CreateInstance(t);
    
    // Prints "Never send a human to do a machine's job."
    t.GetMethod("SayHello").Invoke(o, null);
  }
}

A common example using Reflection.Emit is the regular expression support in the FCL, which can emit new types that are tuned to search for specific regular expressions, eliminating the overhead of interpreting the regular expression at runtime.

Other uses of Reflection.Emit in the FCL include dynamically generating transparent proxies for remoting and generating types that perform specific XSLT transforms with the minimum runtime overhead.

Decorating an element with a custom attribute is known as specifying the custom attribute and is done by writing the name of the attribute enclosed in brackets ([]) immediately before the element declaration as follows:

[Serializable] public class Foo {...}

In this example, the Foo class is specified as serializable. This information is saved in the metadata for Foo and affects the way the CLR treats an instance of this class.

A useful way to think about custom attributes is that they expand the built-in set of declarative constructs such as public, private, and sealed in the C# language.

In reality, custom attributes are simply types derived from System.Attribute with language constructs for specifying them on an element (see Section 2.16 in Chapter 2).

These language constructs are recognized by the compiler, which emits a small chunk of data into the metadata. This custom data includes a serialized call to the constructor of the custom attribute type (containing the values for the positional parameters) and a collection of property set operations (containing the values for the named parameters).

The compiler also recognizes a small number of pseudo-custom attributes. These are special attributes that have direct representation in metadata and are stored natively (i.e., not as chunks of custom data). This is primarily a runtime performance optimization, although it has some implications for retrieving attributes via reflection, as discussed later.

To understand this, consider the following class with two specified attributes:

[Serializable, Obsolete]
class Foo {...}

When compiled, the metadata for the Foo class looks like this in MSIL:

.class private auto ansi serializable beforefieldinit Foo
       extends [mscorlib]System.Object
{
  .custom instance void 
  [mscorlib]System.ObsoleteAttribute::.ctor(  ) = ( 01 00 00 00 ) 
  ...
}

Compare the different treatment by the compiler of the Obsolete attribute, which is a custom attribute and represented by a .custom directive containing the serialized attribute parameters, to the treatment of the Serializable attribute, which is a pseudo-custom attribute represented directly in the metadata with the serializable token.

At runtime the core CLR services such as serialization and remoting inspect the custom and pseudo-custom attributes to determine how to handle an instance of a type.

In the case of custom attributes, this is done by creating an instance of the attribute (invoking the relevant constructor call and property-set operations), and then performing whatever steps are needed to determine how to handle an instance of the type.

In the case of pseudo-custom attributes, this is done by simply inspecting the metadata directly and determining how to handle an instance of the type. Consequently, handling pseudo-custom attributes is more efficient than handling custom attributes.

Note that none of these steps is initiated until a service or user program actually tries to access the attributes, so there is little runtime overhead unless it is required.

The .NET Framework makes extensive use of attributes for purposes ranging from simple documentation to advanced support for threading, remoting, serialization, and COM interop. These attributes are all defined in the FCL and can be used, extended, and retrieved by your own code.

However, certain attributes are treated specially by the compiler and the runtime. Three attributes considered general enough to be defined in the C# specification are AttributeUsage, Conditional, and Obsolete. Other attributes such as CLSCompliant, Serializable, and NonSerialized are also treated specially.

[AttributeUsage(target-enum
  [, AllowMultiple=[true|false]]?
  [, Inherited=[true|false]]?
] (for classes)

namespace System {
  [Flags]
  public enum AttributeTargets {
    Assembly     = 0x0001,
    Module       = 0x0002,
    Class        = 0x0004,
    Struct       = 0x0008,
    Enum         = 0x0010,
    Constructor  = 0x0020,
    Method       = 0x0040,
    Property     = 0x0080,
    Field        = 0x0100,
    Event        = 0x0200,
    Interface    = 0x0400,
    Parameter    = 0x0800,
    Delegate     = 0x1000,
    ReturnValue  = 0x2000,
    All          = 0x3fff,
  }
}

[Conditional(symbol)] (for methods)

[Obsolete(message[, true | false]] (for all attribute targets)

[Obsolete("Don't try this at home", true)]
class Bar { ... }

[CLSCompliant(true|false)] (for all attribute targets)

[assembly:CLSCompliant(true)]

[CLSCompliant(false)]
public class Bar { 
  public ushort Answer { get {return 42;} } 
}

[Serializable] (for classes, structs, enums, delegates)

[NonSerialized] (for fields)

In addition to using the predefined attributes supplied by the .NET Framework, you can also create your own.

To create a custom attribute:

Consider the following example of a custom attribute, CrossRef-Attribute, which removes the limitation that the CLR metadata contain information about statically linked types but not dynamically linked ones:

// XRef.cs - cross-reference custom attribute
// Compile with: csc /t:library XRef.cs
using System;
[AttributeUsage(AttributeTargets.All, AllowMultiple=true)]
public class CrossRefAttribute : Attribute {
  Type   xref;
  string desc = "";
  public string Description { set { desc=value; } } 
  public CrossRefAttribute(Type xref) { this.xref=xref; }
  public override string ToString(  ) {
    string tmp = (desc.Length>0) ? " ("+desc+")" : "";
    return "CrossRef to "+xref.ToString(  )+tmp;
  }
}

From the attribute user’s perspective, this attribute can be applied to any target multiple times (note the use of the AttributeUsage attribute to control this). CrossRefAttribute takes one mandatory positional parameter (namely the type to cross-reference) and one optional named parameter (the description), and is used as follows:

[CrossRef(typeof(Bar), Description="Foos often hang around Bars")]
class Foo {...}

Essentially, this attribute embeds cross-references to dynamically linked types (with optional descriptions) in the metadata. This information can then be retrieved at runtime by a class browser to present a more complete view of a type’s dependencies.

Retrieving attributes at runtime is done using reflection via one of System.Attribute’s GetCustomAttribute or GetCustomAttributes overloads. This is one of the few circumstances in which the difference between customattributes and pseudo-custom attributes becomes apparent, since pseudo-custom attributes can’t be retrieved with GetCustomAttribute.

Here is an example that uses reflection to determine which attributes are on a specific type:

using System;
[Serializable, Obsolete]
class Test {
  static void Main(  ) {
    Type t = typeof(Test);
    object[] caarr = Attribute.GetCustomAttributes(t);
    Console.WriteLine("{0} has {1} custom attribute(s)",
                      t, caarr.Length);
    foreach (object ca in caarr)
      Console.WriteLine(ca);
  }
}

Although the Test class of the preceding example has two attributes specified, the sample produces the following output:

Test has 1 custom attribute(s)
System.ObsoleteAttribute

This demonstrates how the Serializable attribute (a pseudo-custom attribute) isn’t accessible via reflection, while the Obsolete attribute (a custom attribute) still is.

C# depends on the CLR for many of its runtime services, and garbage collection is no exception.

The CLR includes a high-performing generational mark-and-compact garbage collector (GC)that performs automatic memory management for type instances stored on the managed heap.

The GC is considered to be a tracing garbage collector in that it doesn’t interfere with every access to an object, but rather wakes up intermittently and traces the graph of objects stored on the managed heap to determine which objects can be considered garbage and therefore collected.

The GC generally initiates a garbage collection when a memory allocation occurs, and memory is too low to fulfill the request. This process can also be initiated manually using the System.GC type. Initiating a garbage collection freezes all threads in the process to allow the GC time to examine the managed heap.

The GC begins with the set of object references considered roots and walks the object graph, markingall the objects it touches as reachable. Once this process is complete, all objects that have not been marked are considered garbage.

Objects that are considered garbage and don’t have finalizers are immediately discarded, and the memory is reclaimed. Objects that are considered garbage and do have finalizers are flagged for additional asynchronous processing on a separate thread to invoke their Finalize methods before they can be considered garbage and reclaimed at the next collection.

Objects considered still live are then shifted down to the bottom of the heap (compacted ), hopefully freeing space to allow the memory allocation to succeed.

At this point the memory allocation is attempted again, the threads in the process are unfrozen, and either normal processing continues or an OutOfMemoryException is thrown.

Although this may sound like an inefficient process compared to simply managing memory manually, the GC incorporates various optimization techniques to reduce the time an application is frozen waiting for the GC to complete (known as pause time).

The most important of these optimizations is what makes the GC generational. This techniques takes advantage of the fact that while many objects tend to be allocated and discarded rapidly, certain objects are long-lived and thus don’t need to be traced during every collection.

Basically, the GC divides the managed heap into three generations. Objects that have just been allocated are considered to be in Gen0, objects that have survived one collection cycle are considered to be in Gen1, and all other objects are considered to be in Gen2.

When it performs a collection, the GC initially collects only Gen0objects. If not enough memory is reclaimed to fulfill the request, both Gen0 and Gen1 objects are collected, and if that fails as well, a full collection of Gen0, Gen1, and Gen2 objects is attempted.

Many other optimizations are also used to enhance the performance of automatic memory management, and generally, a GC-based application can be expected to approach the performance of an application that uses manual memory management.

When implementing your own types, you can choose to give them finalizers (via C# destructors), which are methods called asynchronously by the GC once an object is determined to be garbage.

Although this is required in certain cases, generally, there are many good technical reasons to avoid the use of finalizers.

As described in the previous section, objects with finalizers incur significant overhead when they are collected, requiring asynchronous invocation of their Finalize methods and taking two full GC cycles for their memory to be reclaimed.

Other reasons not to use finalizers include:

In summary, finalizers are somewhat like lawyers: while there are cases when you really need them, generally, you don’t want to use them unless absolutely necessary, and if you do use them, you need to be 100% sure you understand what they are doing for you.

If you have to implement a finalizer, follow these guidelines or have a very good reason for not doing so:

It is generally desirable to explicitly call clean-up code once you have determined that an object will no longer be used. Microsoft recommends that you write a method named either Dispose or Close (depending on the semantics of the type) to perform the cleanup required. If you also have a destructor, include a special call to the static SuppressFinalize method on the System.GC type to indicate that the destructor no longer needs to be called. Typically, the real destructoris written to call the Dispose/Close method, as follows:

using System;
public class Worker : IDisposable {
  bool disposed = false;
  int id;
  public Worker(int id) {
    this.id=id;
  }
  // ...
  protected virtual void Dispose(bool disposing) {
    if (!this.disposed) { // don't dispose more than once
      if (disposing) {
        // disposing==true means you're not in the finalizer, so 
        // you can reference other objects here
        Console.WriteLine("#{0}: OK to clean up other objects.", id);
      }
      Console.WriteLine("#{0}: disposing.", id);
      // Perform normal cleanup
    }
    this.disposed = true;
  }
  public void Dispose(  ) {
    Dispose(true); 
    // Mark this object finalized
    GC.SuppressFinalize(this); // no need to destruct this instance 
  }
  ~Worker(  ) {
    Dispose(  false);
    Console.WriteLine("#{0}: destructing.", id);
  }
  public static void Main(  ) {
    // create a worker and call Dispose when we're done.
    using(Worker w1 = new Worker(1)) {
      // ...
    }
    // create a worker that will get cleaned up when the CLR
    // gets around to it.
    Worker w2 = new Worker(2);
  }
}

If you run this code, you will see that Worker 1 is never finalized, since its Dispose( ) method is implicitly called (the using block guarantees this). Worker 2 is finalized and disposed when the CLR gets around to it, but it’s never given a chance to clean up other objects. The disposable pattern gives you a way to close or dispose of any external objects you might be using, such as an I/O stream:

#1: OK to clean up other objects.
#1: disposing.
#2: disposing.
#2: destructing.

The CLR marshaler is a .NET facility that knows about the core types used by COM and the Windows API and provides default translations to CLR types for you. The bool type, for instance, can be translated into a two-byte Windows BOOL type or a four-byte Boolean type. You can override a default translation using the MarshalAs attribute:

using System.Runtime.InteropServices;
static extern int Foo([MarshalAs(UnmanagedType.LPStr)]
                      string s);

In this case, the marshaler was told to use LPStr, so it will always use ANSI characters. Array classes and the StringBuilder class will copy the marshaled value from an external function back to the managed value, as follows:

using System;
using System.Text;
using System.Runtime.InteropServices;
class Test {
  [DllImport("kernel32.dll")]
  static extern int GetWindowsDirectory(StringBuilder sb,
                                        int maxChars);
   static void Main(  ) {
      StringBuilder s = new StringBuilder(256);
      GetWindowsDirectory(s, 256);
      Console.WriteLine(s);
   }
}

Passing a class or struct to a C function requires marking the struct or class with the StructLayout attribute:

using System;
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential)]
struct SystemTime {
   public ushort wYear; 
   public ushort wMonth;
   public ushort wDayOfWeek; 
   public ushort wDay; 
   public ushort wHour; 
   public ushort wMinute; 
   public ushort wSecond; 
   public ushort wMilliseconds; 
}
class Test {
   [DllImport("kernel32.dll")]
   static extern void GetSystemTime(ref SystemTime t);
   static void Main(  ) {
      SystemTime t = new SystemTime(  );
      GetSystemTime(ref t);
      Console.WriteLine(t.wYear);
   }
}

In both C and C#, fields in an object are located at n number of bytes from the address of that object. The difference is that a C# program finds this offset by looking it up using the field name; C field names are compiled directly into offsets. For instance, in C, wDay is just a token to represent whatever is at the address of a SystemTime instance plus 24 bytes.

For access speed and future widening of a datatype, these offsets are usually in multiples of a minimum width, called the pack size. For .NET types, the pack size is usually set at the discretion of the runtime, but by using the StructLayout attribute, field offsets can be controlled. The default pack size when using this attribute is 8 bytes, but it can be set to 1, 2, 4, 8, or 16 bytes (pass Pack=packsize to the StructLayout constructor), and there are also explicit options to control individual field offsets. This lets a .NET type be passed to a C function.

The previous Test example works if SystemTime is a struct and t is a ref parameter, but is actually less efficient:

struct SystemTime {...}
static extern void GetSystemTime(ref SystemTime t);

This is because the marshaler must always create fresh values for external parameters, so the previous method copies t when going in to the function and then copies the marshaled t when coming out of the function. By default, pass-by-value parameters are copied in, C# ref parameters are copied in/out, and C# out parameters are copied out, but there are exceptions for the types that have custom conversions. For instance, array classes and the StringBuilder class require copying when coming out of a function, so they arein/out. It is occasionally useful to override this behavior, with the in and out attributes. For example, if an array should be read-only, the in modifier indicates to copy only the array going into the function, and not the one coming out of it:

static extern void Foo([in] int[] array);

C# can not only call C functions but can also be called by C functions, using callbacks. In C# a delegate type is used in place of a function pointer:

class Test {
   delegate bool CallBack(int hWnd, int lParam);
   [DllImport("user32.dll")]
   static extern int EnumWindows(CallBack hWnd, int lParam);
   static bool PrintWindow(int hWnd, int lParam) {
      Console.WriteLine(hWnd);
      return true;
   }
   static void Main(  ) {
      CallBack e = new CallBack(PrintWindow);
      EnumWindows(e, 0);
   }
}

The FCL provides a set of attributes you can use to mark up your objects with information used by the CLR marshaling services to alter their default marshaling behavior.

This section describes the most common attributes you will need when interoperating with native Win32 DLLs. These attributes all exist in the System.Runtime.InteropServices namespace.

[DllImport (dll-name
  [, EntryPoint=function-name]?
  [, CharSet=charset-enum]?
  [, SetLastError=true|false]?
  [, ExactSpelling=true|false]?
  [, PreserveSig=true|false]?
  [, CallingConvention=callconv-enum]?
)] (for methods)

[StructLayout(layout-enum
  [, Pack=packing-size]?
  [, CharSet=charset-enum]?
  [, Size=absolute-size])?
] (for classes, structs)

[FieldOffset (byte-offset)] (for fields)

[MarshalAs(unmanaged-type
  [, named-parameters])?
] (for fields, parameters, return values)

Bool

LPStr

VBByRefStr

I1

LPWStr

AnsiBStr

U1

LPTStr

TBStr

I2

ByValTStr

VariantBool

U2

IUnknown

FunctionPtr

I4

IDispatch

LPVoid

U4

Struct

AsAny

I8

Interface

RPrecise

U8

SafeArray

LPArray

R4

ByValArray

LPStruct

R8

SysInt

CustomMarshaler

BStr

SysUInt

NativeTypeMax

Error

Currency

[In] (for parameters)

[Out] (for parameters)

Interoperating between COM and C# works through either early or late binding. Early binding allows you to program with types known at compile time, while late binding forces you to program with types via dynamic discovery, using reflection on the C# side and IDispatch on the COM side.

When calling COM programs from C#, early binding works by providing metadata in the form of an assembly for the COM object and its interfaces. TlbImp.exe takes a COM type library and generates the equivalent metadata in an assembly. With the generated assembly, it’s possible to instantiate and call methods on a COM object just as you would on any other C# object.

When calling C# programs from COM, early binding works via a type library. Both TlbExp.exe and RegAsm.exe allow you to generate a COM type library from your assembly. You can then use this type library with tools that support early binding via type libraries such as Visual Basic 6.

When you instantiate a COM object you are actually working with a proxy known as the Runtime Callable Wrapper (RCW). The RCW is responsible for managing the lifetime requirements of the COM object and translating the methods called on it into the appropriate calls on the COM object. When the garbage collector finalizes the RCW, it releases all references to the object it was holding. For situations in which you need to release the COM object without waiting for the garbage collector to finalize the RCW, you can use the static ReleaseComObject method of the System.Runtime.InteropServices.Marshal type.

The following example demonstrates changing the friendly name of the user with MSN Instant Messenger from C# via COM Interop:

// SetFN.cs - compile with /r:Messenger.dll
// Run SetFN.exe <Name> to set the FriendlyName for
//   the currently logged-in user
// Run TlbImp.exe "C:Program FilesMessengermsmsgs.exe"
//   to create Messenger.dll
using Messenger; // COM API for MSN Instant Messenger
public class MyApp {
 public static void Main(string[] args) {
    MsgrObject mo = new MsgrObject(  );
    IMsgrService im = mo.Services.PrimaryService;
    im.FriendlyName = args[0];
    }
}

Just as an RCW proxy wraps a COM object when you access it from C#, code that accesses a C# object as a COM object must do so through a proxy as well. When your C# object is marshaled out to COM, the runtime creates a COM Callable Wrapper (CCW). The CCW follows the same lifetime rules as other COM objects, and as long as it is alive, a CCW maintains a traceable reference to the object it wraps, which keeps the object alive when the garbage collector is run.

The following example shows how you can export both a class and an interface from C# and control the assigned Global Unique Identifiers (GUIDs) and Dispatch IDs (DISPIDs). After compiling IRunInfo and StackSnapshot you can register both using RegAsm.exe.

// IRunInfo.cs
// Compile with:
// csc /t:library IRunInfo.cs
using System;
using System.Runtime.InteropServices;
[GuidAttribute("aa6b10a2-dc4f-4a24-ae5e-90362c2142c1")]
public interface IRunInfo {
  [DispId(1)]
  string GetRunInfo(  );
}

// StackSnapshot.cs
// compile with: csc /t:library /r:IRunInfo.dll StackSnapshot.cs
using System;
using System.Runtime.InteropServices;
using System.Diagnostics;
[GuidAttribute("b72ccf55-88cc-4657-8577-72bd0ff767bc")]
public class StackSnapshot : IRunInfo {
  public StackSnapshot(  ) {
    st = new StackTrace(  );
  }
  [DispId(1)]
  public string GetRunInfo(  ) {
    return st.ToString(  );
  }
  private StackTrace st;
}

When you use a COM object from C#, the RCW makes a COM method look like a normal C# instance method. In COM, methods normally return an HRESULT to indicate success or failure and use an out parameter to return a value. In C#, however, methods normally return their result values and use exceptions to report errors. The RCW handles this by checking the HRESULT returned from the call to a COM method and throwing a C# exception when it finds a failure result. With a success result, the RCW returns the parameter marked as the return value in the COM method signature.

The FCL provides a set of attributes you can use to mark up your objects with information needed by the CLR interop services to expose managed types to the unmanaged world as COM objects.

This section describes the most common attributes you will use for this purpose. These attributes all exist in the System.Runtime.InteropServices namespace.

[ComVisible(true|false)] (for assemblies, classes, structs, enums, interfaces, delegates)

[DispId(dispatch-id)] (for methods, properties, fields)

[ProgId(progid)] (for classes)

[GuidAttribute(guid)] (for assemblies, modules, classes, structs, enums, interfaces, delegates)

[InterfaceType(ComInterfaceType)] (for interfaces)

[ComRegisterFunction] (for methods)