C# Frequently Asked Questions

How to use LINQ methods to compare objects of custom types

CSharpFAQ — Wed, 25 Mar 2009 20:23:00 GMT

LINQ provides a convenient syntax and many useful methods for operating with collections of objects. However, to be correctly processed by LINQ comparison methods such as Distinct or Intersect, a type must satisfy certain requirements.

Let’s take a look at the Distinct method, which returns all distinct objects from a collection.

List<int> numbers = new List<int> { 1, 1, 2, 3 };

var distinctNumbers = numbers.Distinct();

foreach (var number in distinctNumbers)

Console.WriteLine(number);

The output is:

But what if you want to use the Distinct method for a collection of objects of your own type? For example, like this:

class Number

{

public int Digital { get; set; }

public String Textual { get; set; }

}

class Program

{

static void Main(string[] args)

{

List<Number> numbers = new List<Number> {

new Number { Digital = 1, Textual = "one" },

new Number { Digital = 1, Textual = "one" } ,

new Number { Digital = 2, Textual = "two" } ,

new Number { Digital = 3, Textual = "three" } ,

};

var distinctNumbers = numbers.Distinct();

foreach (var number in distinctNumbers)

Console.WriteLine(number.Digital);

}

The code compiles, but the output is different:

Why did that happen? The answer is in the LINQ implementation details. To be correctly processed by the Distinct method, a type must implement the IEquatable<T> interface and provide its own Equals and GetHashCode methods.

So, the Number class from the previous example should actually look like this:

class Number: IEquatable<Number>

{

public int Digital { get; set; }

public String Textual { get; set; }

public bool Equals(Number other)

{

// Check whether the compared object is null.

if (Object.ReferenceEquals(other, null)) return false;

// Check whether the compared object references the same data.

if (Object.ReferenceEquals(this, other)) return true;

// Check whether the objects’ properties are equal.

return Digital.Equals(other.Digital) &&

Textual.Equals(other.Textual);

}

// If Equals returns true for a pair of objects,

// GetHashCode must return the same value for these objects.

public override int GetHashCode()

{

// Get the hash code for the Textual field if it is not null.

int hashTextual = Textual == null ? 0 : Textual.GetHashCode();

// Get the hash code for the Digital field.

int hashDigital = Digital.GetHashCode();

// Calculate the hash code for the object.

return hashDigital ^ hashTextual;

}

But what if you cannot modify the type? What if it was provided by a library and you have no way of implementing the IEquatable<T> interface in this type? The answer is to create your own equality comparer and pass it as a parameter to the Distinct method.

The equality comparer must implement the IEqualityComparer<T> interface and, again, provide GetHashCode and Equals methods.

Here is how the equality comparer for the original Number class might look:

class NumberComparer : IEqualityComparer<Number>

{

public bool Equals(Number x, Number y)

{

if (Object.ReferenceEquals(x, y)) return true;

if (Object.ReferenceEquals(x, null) ||

Object.ReferenceEquals(y, null))

return false;

return x.Digital == y.Digital && x.Textual == y.Textual;

}

public int GetHashCode(Number number)

{

if (Object.ReferenceEquals(number, null)) return 0;

int hashTextual = number.Textual == null

? 0 : number.Textual.GetHashCode();

int hashDigital = number.Digital.GetHashCode();

return hashTextual ^ hashDigital;

}

And don’t forget to pass the comparer to the Distinct method:

var distinctNumbers = numbers.Distinct(new NumberComparer());

Of course, these rules don't just apply to the Distinct method. For example, the same is true for the Contains, Except, Intersect, and Union methods. In general, if you see that a LINQ method has an overload that accepts the IEqualityComparer<T> parameter, it probably means that to use it for your own data types you need to either implement IEquatable<T> in your class or create your own equality comparer.

[author: Alexandra Rusina, Programming Writer]

Does the “LINQ to Objects” provider have built-in performance optimization?

CSharpFAQ — Tue, 27 Jan 2009 00:36:00 GMT

Let’s start with the basics and maybe repeat some information that many of you already know. One of the most important concepts in LINQ performance and optimization is, of course, deferred execution. It simply means that when you declare a variable and assign it a query expression, that expression is not executed immediately.

// Query is not executed.

var query = from item in storage select item;

The variable query now stores the command, and the query execution is deferred until you request the actual data from the query. This usually happens either within a foreach loop or when you call an aggregate method such as Min, Max, and Average, or when you cache the query results using the ToList or ToArray methods.

// foreach loop.

foreach (var item in query)

Console.WriteLine(item);

// Count method.

int total = query.Count();

// ToArray method.

var cachedQuery = query.ToArray();

Now let’s look at what else is happening behind the scenes. Does any compiler-level optimization happen during the query execution? The answer is yes. However, there is a catch. From now on we will talk only about queries for IEnumerable and IEnumerable<T> collections that use the “LINQ to Objects” LINQ provider. For other LINQ providers, including LINQ to SQL and LINQ to XML, different optimization rules might apply.

Note: It is often believed that because of deferred execution it takes longer to execute a query for the first time. However, in the case of LINQ to Objects queries, there is no difference between the first execution and subsequent ones. With other LINQ providers the rules might be different (for example, there might be some caching going on), but you need to refer to the particular provider's documentation for details.

The LINQ to Objects queries are optimized in the following cases:

· Some method calls are optimized if the data source implements a necessary interface. The following table lists these optimizations.

LINQ method	Optimization
Cast	If the data source already implements IEnumerable<T> for the given T, when the sequence of data is returned without a cast.
Contains	If the data source implements the ICollection or ICollection<T> interface, the corresponding method of the interface is used.
Count
ElementAt	If the data source implements the IList or IList<T> interface, the interface’s Count method and indexing operations are used.
ElementAtOrDefault
First
FirstOrDefault
Last
LastOrDefault
Single
SingleOrDefault

· If there is a sequence of one or more Where operators immediately followed by a sequence of one or more Select operators, the query creates a single IEnumerable or IEnumerable<T> object and generates no intermediate ones.
Consider the following query:

var query = from item in storage

where item.Category = "Food"

where item.Price < 100

select item;

In this case, only one IEnumerable object is be generated for the query.

· If you query an array or a list, the enumerator from the IEnumerable or IEnumerable<T> interface is not used in foreach loops. Instead, a simple for loop over the length of the array or list is created behind the scenes, and the elements are accessed directly.

Furthermore, the where operators are implemented as simple if statements, so no intermediate enumerators or enumerable is created.

Once again, other LINQ providers might have their own optimization rules. But the above rules should give you some idea about how LINQ to Objects works.

[author: Alexandra Rusina, Programming Writer]

How do I send out simple debug messages to help with my debugging?

CSharpFAQ — Mon, 09 Oct 2006 23:19:00 GMT

Visual Studio offers tons of useful debugging features and allows you to step through your code line-by-line. However, there are times when you don’t want to step through your application, but want to make it output simple text strings with variable values, etc.

Enter the System.Diagnostics.Debug class and its Write* methods. By using the Debug class, you can output messages similarly to the way the Win32 API function OutputDebugString. However, the beauty of the Debug class is that when you build your application using the default Release configuration in Visual Studio, no code lines are generated for your Debug.Write* class. This means there’s no performance penalty for using the Debug class in release code.

To use the Debug class, simply add the “using System.Diagnostics;” statement to your C# code file, and call Debug.Write:

Debug.Write("Hello, Debugger!");

In addition to Write, you have the possibility to call WriteIf, WriteLine and WriteLineIf. For example:

bool @this = true;
bool that = false;
Debug.WriteLineIf(@this || that, "A conditional Hello!");

When you are debugging your application under the Visual Studio debugger, all the messages that are sent out by your Write method calls end up in the Output window (View / Output menu command or Ctrl+W,O on the keyboard). However, if you are running your application outside the debugger (say, by starting it from Windows Explorer), you can still view the messages using tools like DebugView from Sysinternals.

Remember, if you build your application using the default Release configuration, even DebugView won’t show your messages because the Debug.Write* calls are eliminated altogether. You can also control code generation by defining the DEBUG conditional directive.

Tip: The .NET debugging/tracing architecture also allows you to redirect debugging messages to different destinations, such as text files. See the help topic “Trace Listeners” for more information.

[author: Jani Järvinen, C# MVP]

How do I calculate a MD5 hash from a string?

CSharpFAQ — Mon, 09 Oct 2006 23:15:00 GMT

It is a common practice to store passwords in databases using a hash. MD5 (defined in RFC 1321) is a common hash algorithm, and using it from C# is easy.

Here’s an implementation of a method that converts a string to an MD5 hash, which is a 32-character string of hexadecimal numbers.

public string CalculateMD5Hash(string input)
{
    // step 1, calculate MD5 hash from input
    MD5 md5 = System.Security.Cryptography.MD5.Create();
    byte[] inputBytes = System.Text.Encoding.ASCII.GetBytes(input);
    byte[] hash = md5.ComputeHash(inputBytes);
 
    // step 2, convert byte array to hex string
    StringBuilder sb = new StringBuilder();
    for (int i = 0; i < hash.Length; i++)
    {
        sb.Append(hash[i].ToString("X2"));
    }
    return sb.ToString();
}

An example call:

string hash = CalculateMD5Hash("abcdefghijklmnopqrstuvwxyz");

…returns a string like this:

C3FCD3D76192E4007DFB496CCA67E13B

To make the hex string use lower-case letters instead of upper-case, replace the single line inside the for loop with this line:

sb.Append(hash[i].ToString("x2"));

The difference is the ToString method parameter.

[author: Jani Järvinen, C# MVP]

How do I play default Windows sounds?

CSharpFAQ — Tue, 28 Mar 2006 02:03:00 GMT

Sometimes, you might want to make your application a bit more audible. If you are using .NET 2.0, you can utilize the new System.Media namespace and its SystemSound and SystemSounds classes.

The SystemSounds class contains five static properties that you can use to retrieve instances of the SystemSound class. This class in turn contains the Play() method, which you can use to play the wave file associated with the sound in Windows Control Panel. Note that the user can also disable all sounds altogether, which would mean that no sound can be heard through the computer speakers.

To play for example the classical beep sound, you could use the following code:

System.Media.SystemSounds.Beep.Play();

Similarly, you could play the “Question” sound with this code:

System.Media.SystemSounds.Question.Play();

The System.Media namespace is defined in System.dll, so there are no new DLLs you would need to add to your project’s references to use the above code.

[author: Jani Järvinen, C# MVP]

How can I easily log a message to a file for debugging purposes?

CSharpFAQ — Tue, 28 Mar 2006 01:59:00 GMT

Often, you need a way to monitor your applications once they are running on the server or even at the customer site -- away from your Visual Studio debugger. In those situations, it is often helpful to have a simple routine that you can use to log messages to a text file for later analysis.

Here’s a simple routine that has helped me a lot for example when writing server applications without an user interface:

using System.IO;
        
public string GetTempPath()
{
    string path = System.Environment.GetEnvironmentVariable("TEMP");
    if (!path.EndsWith("\\")) path += "\\";
    return path;
}

public void LogMessageToFile(string msg)
{
    System.IO.StreamWriter sw = System.IO.File.AppendText(
        GetTempPath() + "My Log File.txt");
    try
    {
        string logLine = System.String.Format(
            "{0:G}: {1}.", System.DateTime.Now, msg);
        sw.WriteLine(logLine);
    }
    finally
    {
        sw.Close();
    }
}

With this simple method, all you need to do is to pass in a string like this:

LogMessageToFile("Hello, World");

The current date and time are automatically inserted to the log file along with your message.

[author: Jani Järvinen, C# MVP]

How can I speed up hashtable lookups with struct object as keys?

CSharpFAQ — Tue, 21 Mar 2006 01:54:00 GMT

When you have struct objects as the key in a hashtable, the lookup operation of the hashtable performs miserably. This can be attributes to the GetHashCode() function which is used internally to do the lookup.

If a struct contains only simple value types (int, short, etc.), the algorithm which computes the GetHashCode creates hashes which fall into mostly the same bucket.

Example, lets say, the hashtable creates 10 buckets. Then, most probably, all the keys are being put into the same bucket. Hence when a lookup is performed, the .NET runtime has to traverse through this entire bucket to get the value.

BUCKET1 - Value1, Value2, Value3,...,valuen
BUCKET2 - (empty)
BUCKET3 - (empty)
BUCKET4 - (empty)
BUCKET5 - (empty)
BUCKET6 - (empty)
BUCKET7 - (empty)
BUCKET8 - (empty)
BUCKET9 - (empty)
BUCKET10- (empty)

Hence, instead of the lookup operation being O(1), it becomes O(n) on an average case.

To overcome this drawback, consider overriding the GetHashCode() function and making the life easier for the .NET Runtime.

An example would be to create a string by merging all your value types in the struct and joining them by using a special character as a demarcator.

Since your struct is a lookup criteria, it is sure that all the struct values will be different, and hence the string generated is guaranteed unique.

Now the string generated has a method(GetHashCode()), since it is derived from System.Object (like all other objects). Just return the output of this API. A code example will help to understand better.

struct
{
	int a;
	short b;
	public struct(int _a, short _b)
	{
		a = _a;
		b = _b;
	}
	public override int GetHashCode()
	{
		string hash = a.ToString() + ":" b.ToString();
		return hash.GetHashCode();
	}
}

Since you are generating hashcode explicitly which is guaranteed to be unique, it will boost the performance of your lookup.

Reference: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemobjectclassgethashcodetopic.asp

[author: Vipul Patel, C# MVP]

Where can I find design and coding guidelines for .NET?

CSharpFAQ — Mon, 21 Feb 2005 18:30:00 GMT

tipu_77 asked "What are microsoft suggested naming conventions in C#?"

The .NET Framework Team collects their recommendations at their

GotDotNet community site.

which points to a fairly comprehensive MSDN page

Design Guidelines for Class Library Developers.

which includes the section Naming Guidelines

[Author: SantoshZ]

What does the /target: command line option do in the C# compiler?

CSharpFAQ — Sun, 05 Dec 2004 04:33:00 GMT

All the /target: options except module create .NET assemblies. Depending on the option, the compiler adds metadata for the operating system to use when loading the portable executable (PE) file and for the runtime to use in executing the contained assembly or module.

module creates a module. The metadata in the PE does not include a manifest. Module/s + manifest make an assembly - the smallest unit of deployment. Without the metadata in the manifest, there is little the runtime can do with a module.

library creates an assembly without an entry point, by setting the EntryPointToken of the PE's CLR header to 0. If you look at the IL, it does not contain the .entrypoint clause. The runtime cannot start an application if the assembly does not have an entry point.

exe creates an assembly with an entry point, but sets the Subsystem field of the PE header to 3 (Image runs in the Windows character subsystem - see the _IMAGE_OPTIONAL_HEADER structure in winnt.h). If you ILDASM the PE, you will see this as .subsystem 0x0003. The OS launches this as a console app.

winexe sets the Subsystem field to 2. (Image runs in the Windows GUI subsystem). The OS launches this as a GUI app.

[Author: SantoshZ]
See also:
Chapter 3 of Inside Microsoft .NET IL assembler (Serge Lidin, Microsoft Press)
Metadata and the PE File Structure at MSDN
An In-Depth Look into the Win32 Portable Executable File Format - Part 1 and Part 2 (Matt Pietrek, MSDN Magazine)

What is the difference between const and static readonly?

CSharpFAQ — Fri, 03 Dec 2004 22:13:00 GMT

The difference is that the value of a static readonly field is set at run time, and can thus be modified by the containing class, whereas the value of a const field is set to a compile time constant.

In the static readonly case, the containing class is allowed to modify it only

in the variable declaration (through a variable initializer)
in the static constructor (instance constructors, if it's not static)

static readonly is typically used if the type of the field is not allowed in a const declaration, or when the value is not known at compile time.

Instance readonly fields are also allowed.

Remember that for reference types, in both cases (static and instance) the readonly modifier only prevents you from assigning a new reference to the field. It specifically does not make immutable the object pointed to by the reference.

class Program

{

public static readonly Test test = new Test();

static void Main(string[] args)

{

test.Name = "Program";

test = new Test(); // Error: A static readonly field cannot be assigned to (except in a static constructor or a variable initializer)

}

class Test

{

public string Name;

}

On the other hand, if Test were a value type, then assignment to test.Name would be an error.

How do I create a constant that is an array?

CSharpFAQ — Fri, 03 Dec 2004 17:33:00 GMT

Strictly speaking you can't, since const can only be applied to a field or local whose value is known at compile time.

In both the lines below, the right-hand is not a constant expression (not in C#).

const int [] constIntArray = newint [] {2, 3, 4};
 // error CS0133: The expression being assigned to 'constIntArray' must be constant
const int [] constIntArrayAnother = {2, 3, 4};
 // error CS0623: Array initializers can only be used in a variable or field
 //               initializer. Try using a new expression instead.

However, there are some workarounds, depending on what it is you want to achieve.

If want a proper .NET array (System.Array) that cannot be reassigned, then static readonly will do for you.

static readonly int [] constIntArray = new int[] {1, 2, 3};

The constIntArray field will be initialized before it its first use.

If, on the other hand, you really need a const set of values (say as an argument to an attribute constructor), then - if you can limit yourself to integral types - an enum would serve you well.

For example:

[Flags]
public enum Role
{
	Administrator = 1,
	BackupOperator = 2,
	// etc. 
}

public class RoleAttribute : Attribute
{
	public RoleAttribute()
	{
		CreateRole = DefaultRole;
	}

	public RoleAttribute(Role role)
	{
		CreateRole = role;
	}

	public Role CreateRole
	{
		get { return this.createRole; }
		set { this.createRole = value; }
	}

	private Role createRole = 0;
	public const Role DefaultRole = Role.Administrator
	 | Role.BackupOperator;
}

[RoleAttribute(RoleAttribute.DefaultRole)]
public class DatabaseAccount
{
	//.............. 
}

RoleAttribute, instead of taking an array, would only take a single argument of flags (appropriately or-ed). If the underlying type of the Role enum is long or ulong, that gives you 64 different Roles.

[Author: SantoshZ]

How do I get and set Environment variables?

CSharpFAQ — Thu, 02 Dec 2004 14:01:00 GMT

Use the System.Environment class.
Specifically the GetEnvironmentVariable and SetEnvironmentVariable methods.

Admitedly, this is not a question specific to C#, but it is one I have seen enough C# programmers ask, and the ability to set environment variables is new to the Whidbey release, as is the EnvironmentVariableTarget enumeration which lets you separately specify process, machine, and user.

Brad Abrams blogged on this way back at the start of this year, and followed up with a solution for pre-Whidbey users.

[Author: SantoshZ]

Is it possible to output the command-line used to build a project in Visual Studio?

CSharpFAQ — Tue, 30 Nov 2004 22:54:00 GMT

Now that Whidbey has been out in Beta for more than a few months, it seems worth revisiting some frequently asked questions which have different (better?) answers now.

In Everett (v7.1) the answer used to be No.

However, in Whidbey (v8.0), the answer is Yes (and No).

For the yes part of the answer, after building, go to the Output Window, select "Show Output from: Build", and about half way down you will see a section like this:


Target "Compile" in project "ConsoleApplication1.csproj" 
Task "Csc" 
Csc.exe /noconfig /warn:4 /define:DEBUG;TRACE /debug+ /optimize- /out:obj\Debug\ConsoleApplication1.exe /reference:C:\WINDOWS\Microsoft.NET\Framework\v2.0.31125\System.Data.dll, C:\WINDOWS.0\Microsoft.NET\Framework\v2.0.31125\System.XML.dll, C:\WINDOWS\Microsoft.NET\Framework\v2.0.31125\System.dll /target:exe /win32icon:App.ico AssemblyInfo.cs Class1.cs 
The task is invoking the IDE's in-process compiler to perform the equivalent of the above command-line.

Now for the no part of the answer. The project system does not actually execute this command line as part of the build process. As the output says, the IDE directly calls its own in-process compiler to perform the equivalent. However, in all cases, you should get the same results using the command line suggested in the output window. If you don't, you could be looking at a bug.

Note: before you cut and paste the build output to the command line, remember to add the path to CSC.EXE

[Author: SantoshZ]

Preprocess Win32 Messages through Windows Forms

CSharpFAQ — Wed, 20 Oct 2004 20:59:00 GMT

In the unmanaged world, it was quite common to intercept Win32 messages as they were plucked off the message queue. In that rare case in which you wish to do so from a managed Windows Forms application, your first step is to build a helper class which implements the IMessageFilter interface. The sole method, PreFilterMessage(), allows you to get at the underlying message ID, as well as the raw WPARAM and LPARAM data. By way of a simple example:

public class MyMessageFilter : IMessageFilter 
{
  public bool PreFilterMessage(ref Message m) 
  {
    // Intercept the left mouse button down message.
    if (m.Msg == 513) 
    {
      MessageBox.Show("WM_LBUTTONDOWN is: " + m.Msg);
      return true;
    }
    return false;
  }
}

At this point you must register your helper class with the Application type:

public class mainForm : System.Windows.Forms.Form
{
  private MyMessageFilter msgFliter = new MyMessageFilter();

  public mainForm()
  {
    // Register message filter.
    Application.AddMessageFilter(msgFliter);		
  }
…
}

At this point, your custom filter will be automatically consulted before the message makes its way to the registered event hander. Removing the filter can be accomplished using the (aptly named) static Application.RemoveMessageFilter() method.

Tip from Andrew Troelsen
Posted by: Duncan Mackenzie, MSDN
This post applies to Visual C# .NET 2002/2003

Be Mindful of the References / 'using' / Manifest Relationship

CSharpFAQ — Wed, 20 Oct 2004 20:58:00 GMT

Given that the .NET platform encourages binary reuse of types, it is commonplace to set references to external assemblies using the Visual Studio .NET Add Reference dialog box. Many programmers (especially those of the C(++) ilk) fear that adding unnecessary external references can result in a bit of 'code bloat'. Nothing could be further from the truth. When you add assembly references or make use of the 'using' keyword, csc.exe will ignore any assembly which you have not actually made use of in your code. Thus, if you were to set a reference to System.Data.dll and System.Windows.Forms.dll but only authored the following code:

using System;
using System.Data;  // Ignored. 
using System.Windows.Forms; // Ignored. 

public class MyClass
{
  public static void Main()
  {
    Console.WriteLine("Hi there.");
  }
}

the compiler would only reference the mandatory mscorlib.dll.

As you may be aware, when you open up a .NET assembly using ildasm.exe, the MANIFEST icon may be double clicked to open a window describing the binary under investigation. At the very top, you will see a list of each external assembly the current assembly was compiled against (provided that it was actually used):

.assembly extern mscorlib
{ … }

Bottom line? Don't waist your time stripping out unused 'using' statements or assembly references from your application. The C# compiler will do so for you automatically.

Tip from Andrew Troelsen
Posted by: Duncan Mackenzie, MSDN
This post applies to Visual C# .NET 2002/2003/2005