Jeremy Kuhne's Blog : .NET

Creating a SSCLI C# Template for Visual Studio

jkuhne — Sat, 23 Feb 2008 08:29:00 GMT

In my last post (MSBuild your SSCLI C# projects) I demonstrated how to create an MSBuild targets file for the SSCLI (Rotor). In this post I'll show you how to make it easier to use Visual Studio to develop SSCLI C# projects.

To build successfully in VS you need to do a few things, notably:

Override assembly resolution so the SSCLI assemblies are targeted (the last post shows you how to do this)
Change the startup action for the project to "Start external program" (in the Debug property page for the project)
Enter the path for clix.exe as the startup program
Put the output binary for you application in as the "Command line arguments"

It's a little tedious to set all of this up by hand. Thankfully it ends up it's pretty easy to make a template to do most of the dirty work. With a small additional change to the targets file it makes it completely painless. (Well, with the one major caveat that you can't debug managed SSCLI code with VS.)

The existing templates are in the VS folder under "Common7\IDE\ProjectTemplates". Each of the templates are stored in a zip file- perusing a few of these in addition to looking at the documentation will get you up to speed in no time. As such I'm not going to give a tutorial here, I'm just going to talk briefly about what I did to create my template and share it with you.

I started with the "CSharp\Windows\1033\ConsoleApplication.zip" because I wanted the equivalent of that for SSCLI. I had to make most of the changes to the .vstemplate file and a few changes to the .csproj file to link in my targets. Here is what my .vstemplate file looks like:

<?xml version="1.0" encoding="utf-8"?>

<Name>SSCLI Console Application</Name>

<Description>Console Application for the SSCLI (Rotor) Framework</Description>

<Icon>SSCLIConsole.ico</Icon>

<TemplateID>SSCLI.CSharp.ConsoleApplication</TemplateID>

<ProjectType>CSharp</ProjectType>

<DefaultName>SSCLIConsoleApplication</DefaultName>

</TemplateData>

<ProjectItem ReplaceParameters="true" TargetFileName="Properties\AssemblyInfo.cs">AssemblyInfo.cs</ProjectItem>

<ProjectItem ReplaceParameters="true" OpenInEditor="true">Program.cs</ProjectItem>

</Project>

</TemplateContent>

</VSTemplate>

Not too hard to wrap your head around. In the .csproj I changed the import to

<Import Project="$(MSBuildToolsPath)\SSCLI.CSharp.targets" />

Zipped up with a custom icon (had to try it) I dumped it in my "Documents\Visual Studio 2008\Templates\ProjectTemplates\Visual C#" folder, created a few projects off the template to tweak it out and I was almost done.

The other bit that I've already mentioned was setting the project properties to run "clix". Figuring this bit out isn't too terribly straightforward. VS project settings that don't go into the .csproj go into a ".csproj.user" file that is created alongside your .csproj whenever you change the defaults. Change the defaults to create said file and you'll quickly discover what you need to set in your .targets file to establish your own defaults. (Note that these properties are listed in the Microsoft.Build.Commontypes.xsd, found in the MSBuild directory in your relevant framework directory. Also note that it doesn't contain valid values for the VS properties.)

Here is what I added to SSCLI.CSharp.targets (which should live in your MSBuild directory):

<StartAction>Program</StartAction>

<StartProgram>$(SSCLI_FrameworkPath)\clix.exe</StartProgram>

<StartArguments>$(TargetFileName)</StartArguments>

</PropertyGroup>

That's pretty much it. Now you can relatively easily create SSCLI projects. You don't get managed debugging, as mentioned. You do get the rest of the development enviroment benefits however (intellisense, etc.).

The complete SSCLI.CSharp.targets file can be found here. The template can be found here.

MSBuild your SSCLI C# projects

jkuhne — Wed, 20 Feb 2008 09:21:00 GMT

[ Edit 22 Feb 2008: The complete SSCLI.CSharp.targets file can be found here. ]

In my last post I got SSCLI compiling with the 2008 C++ compiler (SSCLI 2.0 and Visual Studio 2008). (A side note: since it is clearly possible to build SSCLI with the compiler there is no reason you shouldn't be able to get a VS Solution up and running that would build the SSCLI- just a lot of work.) Having done that I thought it would be interesting to see how plausible actually working in VS with SSCLI projects would be.

As a first step, it ends up that there is relatively little you have to do to get a .csproj that will work with SSCLI through MSBuild. The key items are:

Set the Csc.exe path.
Make sure the TargetFrameworkDirectory gets set to the SSCLI output directory.

The way to figure this out is to work backwards from the compiler (csc.exe). Look at what csc's arguments are and look for where arguments get generated for it in the build targets.

Microsoft.CSharp.targets is the file to start looking in. It is included at the end of a .csproj so this is a pretty logical place to start looking. Thankfully the file is short, so it is relatively easy to digest. (The target files are in the Windows\Microsoft.Net\Framework\v0.0 directories. I used 3.5 for this article- the last set of MSBuild targets before this version are in 2.0.50727.)

The <Csc> task in Microsoft.CSharp.Targets has a "ToolPath" argument that takes $(CscToolPath). There is #1! Finding #2 begins with "References" which is set to @(ReferencePath). You won't find much in Microsoft.CSharp.Targets so you need to look to the included Microsoft.Common.Targets.

You can figure out #2 by looking at the generation of @(ReferencePaths). Doing a search will drop you in the ResolveAssemblyReferences target- it's in the comments as an [OUT] -- bingo. In a csproj referenced .NET assemblies are listed under (logically) <Reference> items. These are listed here as an [IN] in the comments - see the connection? (Note: the quick way to look for usage of items is to search for '@(ItemName' -- don't use the closing parenthesis as you'll miss transforms.)

In this target the simple "System" <Reference> is turned into a full @(ReferencePaths) item. If you look at the <ResolveAssemblyReference> task within this target you'll see some promising parameters-- the most promising being SearchPaths="$(AssemblySearchPaths)". Look for the source of $(AsemblySearchPaths) and you'll find a nice detailed comment at the top of Common.Targets:

<!--

The SearchPaths property is set to find assemblies in the following order:

(1) Files from current project - indicated by {CandidateAssemblyFiles}

(2) $(ReferencePath) - the reference path property, which comes from the .USER file.

(3) The hintpath from the referenced item itself, indicated by {HintPathFromItem}.

(4) The directory of MSBuild's "target" runtime from GetFrameworkPath.

The "target" runtime folder is the folder of the runtime that MSBuild is a part of.

(5) Registered assembly folders, indicated by {Registry:*,*,*}

(6) Legacy registered assembly folders, indicated by {AssemblyFolders}

(7) Look in the application's output folder (like bin\debug)

(8) Resolve to the GAC.

(9) Treat the reference's Include as if it were a real file name.

-->

{CandidateAssemblyFiles};

$(ReferencePath);

{HintPathFromItem};

{TargetFrameworkDirectory};

{Registry:$(FrameworkRegistryBase),$(TargetFrameworkVersion),$(AssemblyFoldersSuffix)$(AssemblyFoldersExConditions)};

{AssemblyFolders};

{GAC};

{RawFileName};

$(OutDir)

</AssemblySearchPaths>

{TargetFrameworkDirectory} is key here. If you search for "TargetFrameworkDirectory" you'll find the property shows up in the GetFrameworkPaths and GetReferenceAssemblyPaths targets. It is the one we want. It gets replaced by $(TargetFrameworkDirectory) inside of the <ResolveAssemblyReference> task. You can see this if you use Reflector to look at the task-- but you can probably make that leap without digging further.

That gives us everything we need. We know where all of our framework (SSCLI) assemblies are so we just need to override Common.targets' path building completely for this and inject our overrides into the regular targets. You can do this by creating a new target file that includes the Microsoft.CSharp.targets and use this new file instead in your .csproj. Here's the answer:

<SSCLI_FrameworkPath>$(ROTOR_DIR)\binaries.x86chk.rotor</SSCLI_FrameworkPath>

<CscToolPath>$(SSCLI_FrameworkPath)</CscToolPath>

<TargetFrameworkDirectory>$(SSCLI_FrameworkPath)</TargetFrameworkDirectory>

</PropertyGroup>

<Target

Name="SSCLI_InitialChecks">

<Error

Condition=" '$(ROTOR_DIR)' == '' "

Text="ROTOR_DIR is not set. Please set an environment variable or property to the SSCLI directory. Note that running 'env' in your SSCLI directory will set this."/>

<Error

Condition="!Exists('$(SSCLI_FrameworkPath)')"

Text="SSCLI not found at expected path: '$(SSCLI_FrameworkPath)' Please build SSCLI if necessary." />

</Target>

<!--

Override Microsoft.Common.targets GetFrameworkPaths

-->

<Target

Name="GetFrameworkPaths"

DependsOnTargets="$(GetFrameworkPathsDependsOn)" />

<!--

Override Microsoft.Common.targets GetFrameworkPaths

-->

<Target

Name="GetReferenceAssemblyPaths"

DependsOnTargets="$(GetReferenceAssemblyPathsDependsOn)" />

</Project>

Dump the xml above into a file (say, called "SSCLI.CSharp.targets"), drop it in the same directory as the other target files, and (as already stated) include this file in your csproj instead of Microsoft.CSharp.targets.

Now you can 'msbuild myNiftySscliApp.csproj'. And yes, you can even open said csproj in Visual Studio and do some developin'. (With the sad lack of managed debugging, but, hey-- you get Intellisense and all of the other goodies of the IDE.) In my next posts I'll show you how to grease the wheels as much as you can with the IDE, starting with how to build and run easily, then moving on to making an SSCLI project template.

Tools for Digging Deeper Into .NET

jkuhne — Mon, 18 Feb 2008 06:02:00 GMT

As I’ve been preparing more things to talk about I realized that it would be beneficial to have a list of tools to refer back to in my posts. So here you go--a list of tools I find essential to development in .NET.

The most important tool is Lutz Roeder’s .NET Reflector (http://www.aisto.com/roeder/dotnet/). This powerful tool makes analyzing .NET assemblies easy. If you aren’t using this already you need to start yesterday.

Some of the .NET sources have been released and as such you can now directly debug into .NET. You do need VS 2008 (non-express) for this to work. http://blogs.msdn.com/sburke/archive/2008/01/16/configuring-visual-studio-to-debug-net-framework-source-code.aspx

The Shared Source Common Language Infrastructure (SSCLI) is your friend. You can learn an awful lot about the internals of the CLR by looking at this shared source version. http://research.microsoft.com/sscli/

If you’re running up against a wall debugging in VS, WinDbg can come to your rescue. The Debugging Tools for Windows install quickly and are extremely powerful. http://www.microsoft.com/whdc/devtools/debugging/default.mspx

SOS (Son of Strike) is a .NET debugging extension that is usable in both VS and WinDbg. This comes with the Framework so you’re already good to go. However, there is a cool extension to the extension available (SOSEX): http://www.stevestechspot.com/SOSEXANewDebuggingExtensionForManagedCode.aspx

Process Explorer isn’t specifically .NET related, but it is an essential tool for figuring out what the heck has file/directory X open. Use it to replace Task Manager and find happiness again. http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx

.NET Profiler lets you take a look at the pressure your application is putting on the managed heap. It can be downloaded here: http://www.microsoft.com/downloads/details.aspx?FamilyID=a362781c-3870-43be-8926-862b40aa0cd0&DisplayLang=en Details on usage can be found here: http://msdn2.microsoft.com/en-us/library/ms979205.aspx

Generic Collections IV

jkuhne — Mon, 25 Jul 2005 00:46:00 GMT

Back again, and as promised...

Subclassing Generic Collections

The framework provides three basic collections that are intended for derivation. They are located in System.Collections.ObjectModel:



Collection<T> 
KeyedCollection<TKey, TItem> 
ReadOnlyCollection<T>

They are all intended to provide base implementations of the following interfaces:



IList, IList<T>
ICollection, ICollection<T>
IEnumerable, IEnumerable<T>

Collection<T> stores it's data internally as IList<T> (and also takes IList<T> in one of the constructors). The methods that actually modify the internal IList<T> are virtual (and protected):



ClearItems()
InsertItem()
RemoveItem()
SetItem()

This class is intended for when you wish to handle all modifications done to the collection.

KeyedCollection<TKey, TItem> is an abstract class that derives from Collection<T>. It is meant to store values where the key is imbedded within the value. It overrides the virtual methods from Collection<T> and adds an abstract GetKeyForItem().

ReadOnlyCollection<T> supports the same interfaces as Collection<T> and also stores it's data as an IList<T>. There are no virtual methods and all of the iterface method implementations that would normally modify the stored IList<T> are private and throw if called. (Add(), Clear(), Remove(), etc.) The only time the collection is modified is when it is constructed. (i.e., you pass in an existing IList<T>)

Now all of the other collections are not sealed, so you can derive from any of them. They do not, however, have any methods marked as virtual (other than GetObjectData() and OnSerialization()). Why would you want to override them if you cannot change/intercept their behavior? There are two reasons I've come up with so far:

Attaching utility methods.
Readability.

Lets say you had a path with a number of points. You could create a List<Point> to represent said path. This works, but say you want to create a list of your paths? This turns into List<List<Point>>. Hmm. Not nice. In some cases you might even end up with List<List<List<Point>>>. Ugh. Since List<Point> represents a specific object we could subclass List<T> as follows:

public class Path : List<Point>
{
   // Need a constructor (and you'd likely want one that takes IEnumerable<T>):
   public Path() : base() {};
}

Now we can say List<Path>. Much clearer- the sort of code you'd want to read/maintain. In addition we can add useful utility methods to our new Path class such as IsClosed() or IsValid().

That's about it for subclassing for now. Lets take a look at something I hinted at earlier...

System.Array

Ends up that most of the useful methods in List<T> have static equivalents in System.Array. Very useful. Looking at a previous example we could have had:

public void SumUpMeaningDemo()
{
   int[] magicNumbers = { 7, 13, 1000, 42, 9 };
   int total = 0;

   Array.ForEach<int>(newNumbers, delegate(int number) { total += number; });
}

Since these are static methods you need to specifiy the type of the array and which array you're working on. Other than that things work pretty much the same. Happy days that the framework team added this support.

Wait a Minute...

Those that read ahead may have noticed that only List<T> and Array have methods that utilize the system delegate types. It's true. Before you get too depressed about this, in a future post I'll discuss a project that gives you loads of functionality for all of the generic interface types (IList<T>, IEnumerable<T>, ICollection<T>). It is an amazingly useful package called PowerCollections.

Till then...

Generic Collections III

jkuhne — Sun, 24 Jul 2005 05:29:00 GMT

So far I've gone over the basics of generic collections and moved on to looking at List<T> and Predicate<T>. As mentioned yesterday, this post will deal with subclassing and the other System delegate types.

The "Other" System.Delegates

We've already looked at System.Predicate<T>. Now we can turn our attention to the rest of the System deleagte types:



Action<T>
Comparison<T>
Converter<TInput, TOutput>

As a reminder, here's the signature of Predicate<T>:

   public delegate bool Predicate<T>(T obj);

Now here's Action<T>:

   public delegate void Action<T>(T obj);

The only difference from Predicate<T> is that Action<T> returns a void (nothing). One way to think of this is "just do this". The only place it's used (currently) is with List<T>.ForEach(). (Well, one other place, but that comes later.) For each? Yes, it's pretty much the same. Let's say you have a List<int> that you want to sum up:

public void SumUpMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });
   int total = 0;

   // The traditional way:
   // foreach (int number in magicNumbers)
   // {
   //    total += number;
   // }

   // A new way:
   magicNumbers.ForEach(delegate(int number){ total += number; });
}

The syntax is a little different, but not much visible difference. So what to use then? What's the not-so-visible difference, if any? Well this surprised me, but the List<T>.ForEach() is twice as fast (in this example, done a million times) as using foreach on the List<T>. Why is that? I'm not terribly great at IL (Intermediate Language) so I can't give you the final word on this, but when you do a foreach in code you actually end up with the equivalent of:

// For reference, this is the code in Enumerator<int>.MoveNext():
public bool MoveNext()
{
   if (this.version != this.list._version)
   {
      // throw;
   }
   if (this.index < this.list._size)
   {
      this.current = this.list._items[this.index];)
      this.index++;
      return true;
   }
   this.index = this.list._size + 1;
   this.current = default(int);
   return false;
}

public void SumUpMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });
   int total = 0;

   // What you write:
   // foreach (int number in magicNumbers)
   // {
   //    total += number;
   // }

   // What you get:
   List<int>.Enumerator enumerator = (List<int>.Enumerator)magicNumbers.GetEnumerator();
   try
   {
      while(enumerator.MoveNext())
      {
         int temp = enumerator.Current;
         total += temp;
      }
      finally
      {
         enumerator.Dispose();
      }
   }
}

There are four different calls in the above code that are marked in bold. Here's the equivalent of what you end up with if you use the List<T>.ForEach():

private void CompilerGeneratedAnonymousDelegateClass()
{
   public int total;

   private void CompilerGeneratedDelegateMethod(int number)
   {
      this.total += number;
   }
}

// For reference, this is the code in List<int>.ForEach():
public void ForEach(Action action)
{
   if (action == null)
   {
      // throw;
   }
   for (int i = 0; i < this._size; ++i)
   {
      action(this._items[i];)
   }
}

public void SumUpMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });
   int total = 0;

   // What you write:
   // int total = 0;
   // magicNumbers.ForEach(delegate(int number){ total += number; });   //    total += number;

   // What you get (plus the compiler generated class above):
   CompilerGeneratedAnonymousDelegateClass tempClass = new CompilerGeneratedAnonymousDelegateClass();
   tempClass.total = 0;
   magicNumbers.ForEach((Action<int> new Action<int>(tempClass.CompilerGeneratedDelegateMethod));
}

There are two calls (in bold, again) and two classes being constructed (the action delegate and the compiler generated class). The easiest way to differentiate the two methods is to look at the size of the resulting code. If you tear into the IL you'll see that in the loop for your .ForEach you have 53 IL bytes and one call. The standard foreach? 174 IL bytes and two calls. We could go further into it, but that should make it more than clear.

Ugh, sorry about all that. That took way more 'splaining than I expected at first. But I couldn't leave an open-ended question now, could I? ;)

Ok, where was I? Oh yes, the last two types. Here is the signature of Comparison<T>:

   public delegate int Comparison<T>(T x, T y);

Its used (no suprises here) on the Sort<T>() call. The one thing you need to know that isn't obvious is that your method must return the following:

x < y (return less than zero)
x == y (return zero)
x > y (return greater than zero)

And now the last delegate type. Here is the signature of Converter<T, U>:

   public delegate TOutput Converter<TInput, TOutput>(TInput i);

Its used with the ConvertAll<TOutput>() call. In the case of List<T>, this method returns a new List<TOutput>. There is nothing to say that TInput and TOutput can't be the same type. This could be useful for doing something like uppercasing a List<string>. (Why not use ForEach? Just like foreach you're working on a copy.) Here's the line of code to upper case a List<string>:

   myStringList = myStringList.ConvertAll<string>(delegate(string item) { return item.ToUpper(); };

That gets us through the System delegate types. That leads us to subclassing. And me running out of time (sorry, disassembling the foreach example took longer than I expected). So, until next time...

Generic Collections II

jkuhne — Sat, 23 Jul 2005 03:55:00 GMT

In yesterday's post I went over the very basics of generic collections in the 2.0 .Net framework. Today I pick up where I left off with...

Predicate<T>

System.Predicate<T> is a generic delegate that is used to specify a search condition method to pass to the generic collections. It simply takes an object of type <T> and returns a true or false if that object meets a condition that the method expects. The definition is quite simple:

   public delegate bool Predicate<T>(T obj);

Here's another (perhaps easier) way to explain it: When you use the List<T>.Find() method, it needs to know what you wish to find. It accomplishes this by taking a Predicate<T> parameter that it then calls with each element in the collection to essentially ask "Is this it? No? Is this it? ..." Here's how List<T>.Find() actually looks in code:

public T Find(Predicate<T> match)
{
   if (match == null)
   {
      // throw here...
   }

   // Iterate through the collection and return the first object that passes the specified predicate.
   for (int i = 0; i < this._size; ++i)
   {
      if (match(this._items[i]))
      {
         return this._items[i];
      }
   }

   // Nothing found, return the default object for this type.
   return default(T);
}

Pretty simple actually. The one thing you may not have encountered here is default(T). This is a new construct with generics that returns null for reference types, zero for numeric value types, and structs with their fields initialized appropriately to null or zero. The equivalent in C++ is to simply use T(). (note: null in C++ is nullptr)

Let's take a look at a sample of Predicate<T> in action:

// Our method that we'll use as a predicate.
static public bool IsMeaningOfLife(int number)
{
   return number == 42;
}

// Elsewhere …

public void FindMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });

   // Create the predicate delegate
   System.Predicate<int> findMeaning = IsMeaningOfLife;

   // Does the meaning of life exist in my magic numbers?
   if (magicNumbers.Exists(findMeaning))
   {
      // This will be hit!
      Console.WriteLine("I've found my purpose!");
   }
}

Exists(), as you may well imagine, simply returns true if the delegate passes on any of the items in the collection. Not too shabby, but this gets even better with...

Anonymous Delegates

Anonymous delegates are a C# (sorry C++) compiler feature that allows you to write code blocks in place of a delegate parameter. The compiler will automatically create the proper type of delegate for you. Simply replace the delegate parameter with:

delegate (optional arguments) { ...code... }

If we redo the previous example using anonymous delegates we get the following:

public void AnonymousFindMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });

   // Does the meaning of life exist in my magic numbers?
   if (magicNumbers.Exists(delegate(int number){ return number == 42; }))
   {
      // This will be hit!
      Console.WriteLine("I've found my purpose!");
   }
}

This, my friends, is where the generic collections start to really show their power. And it gets even better. (No, really!) Ends up you can transparently create a delegate out of an existing variable instance:

public void AnonymousFindMeaningDemo2(int meaning)
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });

   // Does the meaning of life exist in my magic numbers?
   if (magicNumbers.Exists(meaning.Equals))
   {
      // This will be hit (IF the method was sent one of the numbers in the collection)!
      Console.WriteLine("I've found my purpose!");
   }
}

Ok, this is somewhat contrived to fit the existing example, but you can hopefully see where this could be really useful. (Have I mentioned that I love this stuff? This just rocks.)

(Links to more details on anonymous delegates can be found in yesterday's post.)

Now, sadly, C++ doesn't support anonymous delegates, but I'll share a cool thing that I just haven't been able to do in C# (yet). For your predicate argument you can take advantage of the System::Predicate constructor that takes an object and a method pointer. Try this on: (gcnew System::Predicate<int^>(42, &int::Equals))

Hopefully this has been useful so far, but there is more... In my next post I'll discuss subclassing and the other System delegate types. Stay tuned and feel free to send me your feedback...

Generic Collections I

jkuhne — Fri, 22 Jul 2005 07:19:00 GMT

In one of my first posts I briefly mentioned that I would discuss a bit about what I've learned about using the new generic collections. I've been putting it off a bit because I knew it would be a bit lengthy, but I really feel this is important so I'm going to push myself to start making the effort. ;) Here's what I plan to cover (in relation to generic collections):

Advantages of generic collections
Predicates & other System delegate types
Anonymous delegates
Subclassing generic collections
Other resources (including Power Collections)

I'm not going to go over generics. If you want details on generics here are a few links:

I also won't go over anonymous delegates in detail. You can find some useful information here:

Introduction

Generic collections are the generic equivalents (I like to think of them as replacements) for the System.Collections classes. They are found in the System.Collections.Generic space.

Generic collections have a number of advantages over the old collections. Chief among them are:

They are type safe.
Better performance. (no boxing/unboxing!)
Richer functionality through System defined delegate types.

To top it off they are quite compatible with the old collections and methods that use them. Both ArrayList and List<T> support IList, ICollection, IEnumerable, and ICloneable for example. If existing methods use the old interfaces for parameters there is nothing extra you have to do to start using the generic collections. (Hey, look! A great reason to take the interface (IList) as a parameter instead of the collection class (ArrayList).) Converting is easy beyond this as the old collections take ICollection or IDictionary as a constructor parameter.

Here's a quick overview of how the new collections map to old ones (from: Generics in the .NET Framework Class Library (C# Programmers Reference))

Generic Class or Interface	Description	Corresponding Non-Generic Type
Collection<T> ICollection<T>	Provides the base class for a generic collection.	CollectionBase ICollection
Comparer<T> IComparer<T> IComparable<T>	Compares two objects of the same generic type for equivalence and for sorting.	Comparer IComparer IComparable
Dictionary<K, V> IDictionary<K,V>	Represents a collection of key/value pairs that are organized based on the key.	Hashtable IDictionary
Dictionary<K, V>.KeyCollection	Represents the collection of keys in a Dictionary<K, V>.	None.
Dictionary<K, V>.ValueCollection	Represents the collection of values in a Dictionary<K, V>.	None.
IEnumerable<T> IEnumerator<T>	Represents a collection that can be iterated using foreach.	IEnumerable IEnumerator
KeyedCollection<T, U>	Represents a keyed collection.	KeyedCollection
LinkedList<T>	Represents a doubly linked list.	None.
LinkedListNode<T>	Represents a node in a LinkedList<T>.	None.
List<T> IList<T>	Implements the IList<T> interface using an array whose size is dynamically increased as required.	ArrayList IList
Queue<T>	Represents a first-in, first-out collection of objects.	Queue
ReadOnlyCollection<T>	Provides the base class for a generic read-only collection.	ReadOnlyCollectionBase
SortedList<K, V>	Represents a collection of key/value pairs that are sorted by key based on the associated IComparer<T> implementation.	SortedList
Stack<T>	Represents a simple last-in-first-out (LIFO) collection of objects.	Stack

First Look at a Generic Collection Class

The best place to start is to look at the workhorse of the generic collection family, the generic List class, or List<T>. List<T> is meant to replace the functionality of ArrayList. It is a simple ordered collection of objects of type <T>. You can think of it as a wrapped array because that's precisely what it is--internally data is stored as private T[] _items;

As with any array, appending is usually fast (unless the array is being resized) and insertion gets proportionally slower as the number of elements grows. I've already mentioned that it supports IList, ICollection, and IEnumerable. It also supports the generic equivalents IList<T>, ICollection<T>, and IEnumerable<T>.

Lets take a look at some simple usage of List<T>, shall we? (Finally, some code!)

// Creating a List<T> (Also has constructors that take a collection or specify the initial size)
List<int> myNumbers = new List<int>();

// Adding a value
myNumbers.Add(42);

// Adding a range of values
myNumbers.AddRange(new int[]{1,2,3});

// Inserting a value
myNumbers.Insert(myNumbers.Count - 3, 0);

// Iterating
foreach (int number in myNumbers)
{
   // Output is 42, 0, 1, 2, 3
   Console.WriteLine(number.ToString());
}

The code above should be pretty self explanatory. Here is a summary of the functionality that is available to you in List<T>:

Add or insert objects of collections of type T
Removal
- Remove, RemoveAt, RemoveRange, RemoveAll
Sorting
- Sort (Comparison<T>)
- Reverse
Conversion
- ConvertAll (Converter<T,U>)
- CopyTo(T[])
Searching (Predicate<T>)
- Exists
- Find, FindAll, FindLast
- FindIndex, FindLastIndex, IndexOf, LastIndexOf
- TrueForAll
Iterating
- ForEach (Action<T>)

In bold you will see that I've called out the System delegate types. They are the key to unlocking super rich functionality within these classes. This makes a nice transition to my next blog entry where I'll start by taking a look at Predicate<T> and then this discussion will get really interesting. :)