Sadly, there simply is no mechanism that will give you the flexibility you need, allow you to interoperate with existing legacy code, and allocate and de-allocate handles, memory, and other resources at will without paying a tax.

Since I get this question a lot, I thought I would list here are a number of tools and techniques that you can use in your quest to rid your software of leaks.

Use Coding Standard and Best Practices

Create coding standards and a set of practices for your team that help build clean code to start with. It is much easier to design problems out of the system than it is to find the bug, fix it (without breaking something else), and ship this to your customer. Some of the things you can do are:

Require the use of IDisposable pattern for any objects that themselves hold references to IDisposable objects. Require that the creation of objects that implement IDisposable use the "using" clause around all such instances.

There are a few instances where doing this will bite you. But, if you use delegation, you can usually wrap these calls in a way that allows you to use the "using". Or, you can simply make sure that when it's not used, that it is clearly documented in the code and there is a clear plan for disposal of the object. For example, in the first case I listed above, an object holds a reference to an IDisposable object. In this case, the clear plan it to have the owning object cleanup (dispose) of the owned object(s) during its IDisposable call.

Use the language features (like the new "async" and "await" features in C#, and the new threading items like Task) to help simplify multi-threaded code.

Require everyone who touches, thinks about touching, has and opinion about or otherwise interacts with the code in any way read these items:

1. Threading in C# (free)
2. Effective C#: 50 Specific Ways to Improve Your C#
3. Code Complete

I also recommend Advanced .NET Debugging and Advanced Windows Debugging. However, getting folks to read these books might be hard, as

Test Driven Development

Debug every line of code you write as you write it. I use unit tests, which I write prior to the code to help me step through the various scenarios for each method. I do not trust myself to get Boolean expressions correct. Instead, I step through the code and make sure my assumptions were correct.

If I make assumptions in the code, I write defensive code. I only throw when something goes wrong. I only catch if I know what I am catching, and know what to do with what I caught. Of course, I bend this to perform logging, but then immediately re-throw.

I use asserts for when I am debugging code, and I cannot write defensive code (usually due to time constraints) to protect the function. Ideally, these asserts are "to do's" to go back and add defensive code later when I start getting bug reports in the area.

"Break hard fast"

This is my slogan for development. I learned this through the school of hard knocks. This may not be intuitive to most, but this basically means that when writing compiled code like C#, you want to leverage the compiler type checking and static analysis to get rid of the bulk of you bugs. When that fails, and you make it to runtime, you want your code to fail as close to the time you write the code as you can. And, you want it to be something that blocks you until you fix it. Fixing a bug as you are writing the code allows you to alter the design before the code is in-place, lets you solve the problem while the problem is still in your head, and allows you to quickly give up on poor designs before others become dependent on them.

Detecting Leaks

Basic resource leak detection can many times be done by using Windows Task Manager. Just add the appropriate fields to the Process view. Then perform the scenarios you are concerned about over and over.

You can also use Performance Monitor. Visual Studio provides access to the Performance Monitor data inside Visual Studio to observe process memory, timing, etc. (Access it from the menu View -> Other Windows -> Performance Explorer.)

Additionally, Mark Russinovich's SysInternals tools (now owned by Microsoft), are great for detecting, and sometimes drilling into issues. For example, Process Explorer is an even better version of Task Manager. It allows you to get callstacks (if symbols are setup correctly), create dumps (well, ok, Task Manager does this too), search for paths to find handles to files, look at the guts of a process, etc. There are many tools in the Suite, so you should check them out.

These tools help you to detect the problem. But you will need to go deeper to find the offending code and fix the issue.

Writing Profiling Code

You can write profiling code in your application to take snapshots. You can use tracing, performance monitor APIs, other Windows eventing APIs to track resource usage, or use some combination of the above to monitor your app as it runs. This is of course harder. And, it is much easier to design this into the software when you are first building it, than to add it later.

I recommend designing performance requirements into every API. This does not mean that the developer has to write any code for performance. Many times, the code they write just works and it is fast enough. But, how do you know if it is fast enough? This is where the requirements will help.

The same thing applies to the use of resources. When you create a design, determine what is acceptable or allowed for the process/thread/or object to consume. This works better when you use a holistic view for an entire application than when you are in the details of an API. But, you apply the limits when you are testing the APIs to make sure they comply with the requirements. Note that you may need to specify what can be used for short durations versus long durations. And you will likely need to determine what the right set of durations are.

The Debugger

The debugger is your friend. Whether you prefer the Visual Studio debugger or WndDbg, you can successfully find leaks and get straight to the problem at hand using a debugger. For .NET code, you will need to load and use SOS. (https://madgeek.com/Articles/Leaks/Leaks.en.html#SOSAndWinDbg). This allows you to look at the managed memory, etc. It is something of a "ninja" approach to leaks, but once you learn the skills you need, you will be an ace wherever you work. J

And hey, you are already stepping through every line of code in the debugger as you write it, right? So, while you are there, you can check for leaks and other issues.

Using a Profiler

In Visual Studio Ultimate and above, you can also is the .NET Memory Profiler. I want go into a lot of details here, as there are already a lot of articles on the subject. (See the bottom of this post if you need more to read.)

Of course, there are many partners that provide paid tools (which are many times better than the ones we provide). To name only a few: JetBrains, MicroFocus DevPartner, and RedGate Software.

More Articles on Leaks, Performance, Multi-Threading, etc.

There are lots of articles on performing leak analysis. Many are geared towards specific things. Not all techniques work for all types of problems. So, determining while you are not releasing a handle can be way different than why your memory keeps climbing.

Here are general articles that I found useful:

    https://msdn.microsoft.com/en-us/magazine/cc188781.aspx

    https://msdn.microsoft.com/msdnmag/issues/1100/GCI/default.aspx

    https://msdn.microsoft.com/msdnmag/issues/1200/GCI2/default.aspx

    https://msdn.microsoft.com/msdnmag/issues/01/12/hood

    https://www.codeproject.com/KB/dotnet/Memory_Leak_Detection.aspx

    https://channel9.msdn.com/Shows/Going+Deep/Mads-Torgersen-Inside-C-Async

https://msdn.microsoft.com/en-us/magazine/cc337887.aspx

Hope this helps…

If you have a large solution, you may find that yourself wanting to split your solution into several parts. If your projects are not inter-connected, this works fine. Basically, you just move the various apps into their own solutions. This allows you to load them faster in the Visual Studio.

But, sometimes you just have lots of interrelated projects. If you simply make two copies of the solution and remove half of the projects from one solution, and half from the other, then some of the projects you need when you build will not be in the solution. And, as a result, you will have no Solution Configuration information to tell MSBuild how to build you project.

When this happens, MSBuild uses the "default" configuration and platform to build the project. If this does not match what you are building, then the wrong thing is built. (This makes me sad. L).

The "default configuration" is defined by the set of properties at the top of each project in the first <PropertyGroup />. They appear something like the following:

<PropertyGroup>

    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>

    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>

     ...

</PropertyGroup>

This basically says that if the Configuration is blank, use the "default" of "Debug", and if the Platform is blank, use the "default" of "AnyCPU". Since this is the behavior when the Solution Configuration does not contain information about the project being built, the default "Debug|AnyCPU" gets built. If you are building "Release", you still get "Debug" for any of these projects that are not in the solution.

You can of course change the default to anything you want. So, if you want the default to be "Release", you can simply edit this part of the file and change it to the new value.

<PropertyGroup>

    <Configuration Condition=" '$(Configuration)' == '' ">Release</Configuration>

    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>

     ...

</PropertyGroup>

However, this means that this is the new default (Release) that will be used for all cases where the value is not defined in the Solution Configuration. And, you would have to hand edit your project files over and over again every time you wanted to change what you are building.

A more flexible solution is to instead add the following lines:

<PropertyGroup>

    <!-- Add these two lines -->

    <Configuration Condition=" '$(Configuration)' == '' ">$(DefaultProjectConfiguration)</Configuration>

    <Platform Condition=" '$(Platform)' == '' ">$(DefaultProjectPlatform)</Platform>

    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>

    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>

     ...

</PropertyGroup>

By doing this, you can specify "/p:DefaultProjectConfiguration=Release" on the command line, which will then be used for all projects in the build where there is no "Solution Configuration" information. You can also specify "/p:DefaultProjectPlatform=AnyCPU" to set the default platform. (Note that this is less useful, since certain projects may need to build for a specific platform.)

Note that this does not change the existing behavior when $(DefaultProjectConfiguration) and $(DefaultProjectPlatform) are not supplied. And, you can specify only one of them or both of them on your command line.

This still does not allow you to configure each project individually in the build. But, it does give a lot more flexibility. And, if you really need to set the exact Configuration and Platform for a project, the Solution Configuration is the correct place to do this. But, this means that these types of projects would need to be contained in the Solution being built.

Hope this helps…

The following are rules that helped me when I first started to ride. They were given to me as advice upon buying my first street bike. The BMW dealer spent a great deal of time with me before I got on the road. I have found that (minus one or two duds) all motorcycle dealers seem to really love what they do. And, they are great about spending time with you; and I don't mean in the "used car salesman" kind of way. There must be something about riding that attracts friendly and interesting people.

BMW dealers especially seem to have this nailed. They are a truly special group of folks. They are dedicated to fun and safety. And they know their bikes and their quirks inside and out. It is quite a different experience from the auto dealers.

When I purchased my first street bike in 2000, I had already been riding dirt bikes for years. But this did not prepare me for riding on the road. Not in the least. The salesman, and great friend for years after, gave me these basic lists. As I recall, he started the day I walked into the store. I would stop by on the weekend and admire the bikes, checkout the new models, and plot and plan how to sell this to my wife. J

My youngest son on my first street bike, "Misty" (BMW R1100R)

Each time I would go in, he would talk to me about one of these rules. He always started from the beginning. Conversation would quickly lead him to where we left off. I am sure he did this with all his customers. There was just a gentle and caring way about him. He knew what we came there to get. And he would feed it to us with a lump of safety. By the time I brought my wife to the store, I knew them by heart.

Suggestion for Beginners

Buy something that you can ride. Take your time and learn slowly. Let the lessons sink in. Don't just think you get it; know you get it. If you are thinking of trying something new, try it in an empty parking lot before you try it out on the street. You don't need the biggest fastest bike you can afford. In fact, the Kawasaki Ninja 250 is a great bike to start with. It will give you the same feeling you get when riding bigger bikes, but is a lot safer for beginners. And, it has a high resale value. So, later when you know how to ride, and have some clue of what to look for in a bike, you can trade up.

Rules before Riding

• You have to pay to play.
  • I know this sounds like a sales pitch, but it really means "if you can't afford the safety gear, the maintenance on your bike, etc., don't ride!
• "If you have a $10 head, buy a $10 helmet." Ok, I like this saying, but let me make it clear, buy a high quality helmet that is SNELL approved. The cost a lot. (Suck it up; if you can afford a bike, don't skimp on the helmet.)
  • Personally, I have not found one yet that covers the cost of my head. But I typically pay right around $600.
• Always wear complete protective gear. That is:
  • Motorcycle street pants (designed to save your skin if you fall; not regular jeans)
  • Motorcycle street jacket (designed to save your skin if you fall; not the cool jacket for hanging out)
  • Safety (some jackets have this built-in now)
  • Motorcycle street gloves
  • Motorcycle boots
  • SNELL approved helmet with face shield

    * Never ride in tennis shoes, flip flops, loose fitting shoes, etc.

• Read you bikes manual from cover to cover and understand the material in it. Some of it is just cool. The rest of it is important. If you don't have the manual for you bike, call the manufacturer and ask for one. Most will send you one "no charge".
• Make sure your bike is ready to ride. All maintenance is up to date.
  • Never use tire cleaners on motorcyle tires. Sure they make car tires look sweet. But one drop of that stuff on your tires in a turn is disaster. If you really want to wash them, use water. You can use a small amount (teaspoon) laundry deterdent mixed in a lot of water (1 gallon +), but if you do, make sure you get it all off.
• Perform a preflight checklist everytime you ride. Your bike most likely comes with a checklist in the owners manual. Use it. Some obvious things are:
  • Check the tire pressure
  • Check tires for oil or other resdue
  • Make sure you have enough gas to get where you are going; especially if you are going on the interstate
• Always take foul weather gear with you. If you ignore this rule, and foul weather comes, get off the road and wait for it to clear. And overpass makes a great place to wait out the rain. Just make sure you get your bike and gear clearly off and away from the road.

Here are some of the items I use when riding:

• First Gear Riding Pants
• SHOEI Multitec Helmet
• BMW Airflow 2 Gloves

My current bike "Annabel" is a BMW K1200RS 

Rules for Riding

To be successful, you must incorporate your own riding style, type of bike, etc. with these rules. These rules did not come naturally to me. I spent months learning on slow back roads with no traffic. Build you confidence and know your capabilities before you get into a situation that requires them. When you are applying these rules correctly, the feeling is a very natural and fluid motion. If it does not feel right, it is probably not. Most of these rules were given to me. A few I have learned on my own. If I find more, or recall more in my old age, I will do my best to add them here. I hope these rules help you as much as they have helped me.

1. Everyone in a car, truck, or other type of vehicle wants to kill you. Keep your eye on them and avoid them. Remember that between you and vehicle, you lose every time.
2. Everyone in a car, truck, or other type of vehicle wants to kill you. Keep your eye on them and avoid them. Remember that between you and vehicle, you lose every time.
3. Everyone in a car, truck, or other type of vehicle wants to kill you. Keep your eye on them and avoid them. Remember that between you and vehicle, you lose every time.
4. Always ride below your capability.
5. Between you an another vehicle, the other vehicle wins 100% of the time. Do not get into a situation where you challenge another vehicle.
6. Bikes turn by counter steering. Pressing gently forward on the grip to the side in the direction you want to go will cause the bike to dip (fall over) in that direction. The bike turns by leaning. You accomplish the amount of lean by causing the bike to dip. You cannot steer a bike by you leaning. (There was a great TV episode of one of the myth bustnig type shows on this.) It is a gyroscope, and it will resist you. You must lean the bike by pressing the grips.
7. Keep your head up. This is especially true in the turn where there is a tendency to dip you head.
8. Always be aware with what is going on around you. Track all vehicles in your mind. Use your peripheral vision. When in doubt, look again before proceeding.
9. Imagine a line in front of you that follows the path that you want the bike to follow. Focus your eyes about 50 feet in front at a point on that line. (You will have to look farther ahead if you are going faster and closer to you if you are going slower, but 50 feet is a good starting point.) Follow that point with your eyes and head. If your head turns left, the bike will turn left. If your head turns right, the bike will turn right. Remember rule 6. This will become natural with practice. Remember rule 5.
10. The back brake is to turn on the red light on the back of the bike to warn those following you. It will have little effect at stopping you.
11. Never use the front brake while in a turn. In an emergency you will need to stop turning first, then apply the front brake hard but gradually.
12. Weight balance matters. Shift you weight to the side of the seat where you will be turning. This lowers the center of gravity during the turn and pushes it outward toward that side of the bike. The faster and sharper the turn the farther one general tends to push their weight out. The weight shift does not happen during the turn, but before the turn. When done right, the sharpness of the turn matches the weight shift, and it feels like a ballet, with the bike wanting to be held at exactly that lean.
13. When passing other vehicles on the road, look toward the drivers eyes. If you don't see their eyes, they don't know you are there. If you see their eyes, assume they don't know they are there.
14. When waiting at a red light at an instersection in a turn lane, and you are not the first in line, before proceeding with the turn, stop at the first spot in line. If a car is turning in front of you, and a car coming the other way does not see you and is timing the gap, you lose.
15. Never user headphones or listen to music while riding.
16. Always pay attention. There is a lot think about when riding. (Look at all the rules above.) If you want to admire the view, stop and do that.

Error:
The specified task executable "ResGen.exe" could not be run. The filename or extension is too long

Warning:
The command-line for the "ResGen" task is too long. Command-lines longer than 32000 characters are likely to fail. Try reducing the length of the command-line by breaking down the call to "ResGen" into multiple calls with fewer parameters per call.

As a result, my team responded with an article to help customers work around the issue:

https://blogs.msdn.com/b/visualstudio/archive/2010/02/16/if-your-build-fails-with-msb6002-the-command-line-for-the-resgen-task-is-too-long.aspx

This article provides several different approaches for fixing the issue. One of these involves changing your targets file to override the GenerateResource target.

Approaches to fixing issues for shipped targets

The article above suggests that you can update your Microsoft installed "Common" targets file ("%WinDir%\Microsoft.net\Framework\v4.0.30128\Microsoft.Common.targets") with an updated one. (And notes you should backup prior to doing so.) But, maybe you don't want to change the Microsoft installed file. There are a couple of other options.

1. In MSBuild, the last target of a given name found in the project file wins. That is, we only keep that last one defined, and the rest are thrown out. So, to override this target, all you have to do is place an import (Imports are processed like C++ #include's) at the bottom of your project file so that is last thing in the file, and then override the functionality in the existing GenerateResource target with your own.

   This option is the simplest. But, it only affects the one project that you add the import. You also start to run into problems quickly if you want to locate a target. You can define your own property

2. You can use the new functionality in MSBuild to carefully place a new target file you write into a location known to MSBuild, and we will auto-magically pick it up and add it as an import when we load any project file.

   This option requires the same targets changes, but you have to place the target in the "special" location. Additionally, debugging will be harder. But, once in place, it fixes the problem for all project files in one fell swoop. To deploy this across a group, and build server, you will have to install these targets on each machine individually.

How does option #2 work?

In the Microsoft.Common.targets file, at the very bottom, you will see something that looks like this:

  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\$(MSBuildThisFile)\ImportAfter\*"
          Condition="'$(ImportByWildcardAfterMicrosoftCommonTargets)' == 'true'
          and Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\$(MSBuildThisFile)\ImportAfter')" />

This import basically says, if I find a file in the MSBuild folder in a special location (see below), then I will load it after this file. The special location is defined by the MSBuild properties as follows: (the values are from my box, and could vary on the installation)

So, the final path would be: "C:\Program Files (x86)\MSBuild\4.0\Microsoft.Common.targets\ImportAfter" for this scenario.

Note on paths:

MSBuild uses all environment variables (which are allowed to be XML node names) as properties inside MSBuild. There are some very nice shortcuts that allow you to get to things you might commonly need. An example I used above was the Windows directory, which was the start of the path to the "Microsoft.Common.targets" file. The environment variable is "%WinDir%", and is not case sensitive. There are a few nice features this environment variable provides:

1. It supplies the path to the Windows folder, which may be on another drive. It is prefixed with the appropriate drive letter as needed. On my machine it is "C:\Windows".
2. I can use the environment variable in explorer to quickly get to a known location. So, if you click in the location text box in an explorer windows, and type "%WinDir%" (without the quotes) and press enter, you will be taken to your Windows folder.
3. Since it's an environment variable, it becomes a property in MSBuild, so in MSBuild I can reference this path as $(WinDir).

Some of the other ones I use a lot:

Here is a sample MSBuild file I wrote that uses them:

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="Build">
    <Message Text="AppData == '$(AppData)'" />
    <Message Text="LocalAppData == '$(LocalAppData)'" />
    <Message Text="DevEnvDir == '$(DevEnvDir)'" />
    <Message Text="FrameworkDir == '$(FrameworkDir)'" />
    <Message Text="HomePath == '$(HomePath)'" />
    <Message Text="ProgramFiles == '$(ProgramFiles)'" />
    <Message Text="ProgramW6432 == '$(ProgramW6432)'" />
    <Message Text="TEMP == '$(TEMP)'" />
    <Message Text="WindowsSdkDir == '$(WindowsSdkDir)'" />
  </Target>
</Project>

And here is the output I generated…

Next up…

In the next article, I will show you how I came up with the Batching Solution for RESGEN. Note that the article shown above on the Visual Studio blog has the batching solution in it. The purpose of my article will be to show you how you could have effectively figured this out yourself.

As a result of working at the center of the Visual Studio universe, I am blessed to work with the finest, brightest, fun, and passionate software architects, designers, developers, testers, and program managers on the planet. Yes, really. J

And they have so many incredible ideas and such drive that they continue to give when common mortals would go home and just watch the Stanley Cup (go Vancouver!). When I first got to Microsoft, a great dev lead told me that "we only work half days here, what you do with the other 12 hours is your business."

But, these folks, they just seem to be an endless pool of energy. Even when we know that there is only so much that we can do in a given release, they stay late, fix one more bug, close one more issue. Do they go home then?

Nope. Instead they work on features and ideas that we did not have time to fully flush out and test. The things that we wanted to provide to our customers, but just could not fit into the schedule.

I wanted to cite a couple of instances of this type of work.

First, if you know about MSBuild, then you know what a cool build system we have. But, when a poll was taken quite some time back on the MSBuild Blog, users replied that they wanted an MSBuild debugger. Early in Visual Studio 2010, we realized that there was no way, with all of the features that we needed to push out the door, that we could also build and test the MSBuild debugger. But, Dan, one of the developers of MSBuild, took his off time and wrote a debugger for MSBuild, and integrated it into Visual Studio. Now, if you read our press release, you would never see this feature listed. In fact, the feature is kind of hidden. We had to do this because what we ship has to go through rigorous testing. And while the development work was done, the testing work simply could not be done. So, this feature silently shipped in the product in a "silent" state. If you want to use it, here are some articles from the author that will tell you all about it.

• Debugging MSBuild script with Visual Studio
• Debugging MSBuild script with Visual Studio (2)
• Debugging MSBuild script with Visual Studio (3)

Second, there are so many features that are really just simple things that help you, our customers, with your day to day jobs. And, they make the Visual Studio experience that much better. Well, and this was a team effort, a bunch of the developers and testers throughout Visual Studio go together and built a bunch of power tools for Visual Studio 2010. They are called the Pro Power Tools, and are available from the Extension Manager (a new feature available in the Tools menu of Visual Studio 2010). Check them out.

Thanks for support Visual Studio!

While we could start at the beginning, let's start at the end and work backwards toward a better understanding. And, we can start with our real expectation. We expect that when we write an app that references other assemblies, that those assemblies can be found and are loaded as needed by our code such that we can execute the code in them. That is pretty simple.

Runtime Binding

At runtime, our code is loaded into a process. At this point, all of the static references that we have made are resolved.

Most of this work is handled by the binder in the CLR. The binder (aka Fusion or CLR loader) cracks open the referencing assembly or EXE to obtain its manifest. The manifest contains a list of all the assemblies that are being referenced. For example, a 2.0 entry might have a reference like:

.assembly extern System

{

.publickeytoken = (B7 7A 5C 56 19 34 E0 89 ) // .z\V.4..

.ver 2:0:0:0

}

The entry above is one I pulled out of a random assembly on my disk, and references the System assembly. To get this, I used ILDASM.exe to open the assembly and double-clicked on the manifest.

It specifies the public key token and the specific version that needs to be loaded. The binder uses this information to then locate the assembly and bind to it. (The algorithm for binding is documented here.) Since the manifest explicitly calls out each assembly it references, all that needs to be done is to find it and bind to it. And the binder does this work for us.

But, there are times when you may need to load an assembly on the fly. Dynamic assembly binding can be done through Assembly.Load(…) and Assembly.LoadFrom(…). Suzanne Cook's old blog has a lot of good notes on this. To call them, you need to know the assembly you want. The locating and binding, just like the static case, is handled for you.

The important thing to note at this point is that we already know the assembly that we want to bind to; as it was stored in the assembly's manifest.

Note: If you have built your assembly, and you are having trouble getting the assembly to load, you can use FusLogVw.exe to debug the issue. (FusLogVw docs are here) These are issues with the binder probing for the assembly and not finding it.

Assembly Resolution

So, how do we just know the assembly that we want? Well, obviously this starts with a need for some library or piece of code that we want to run. (Duh!) But, how does the manifest get its list of assemblies?

This answer is that assemblies are resolved at build time through a process called RAR (Resolve Assembly References). And other references such as COM references and the like are resolved through similar mechanisms such as RCR (Resolve COM References). The resolution process takes the name of the library that you requested and finds the reference that you need.

Why does RAR need to do anything? I just told you what I want! To discuss why this is, lets first talk about multi-targeting, and then it should become clear.

Targeting

Targeting is the term we use to describe the fact that your software will run on some specific device or machine. Now, a long time ago, there may have been only one version of a Framework, or one version of DOS, Windows, etc. that you might want to run your application on. And generally, each version of Windows tries to be backwards compatible with the last. So, unless you are using some new feature, you are good to go. But, how do you know? What machines will your software run on? If there is only one target, then "no problem", everything you can code should just work. This was true at the release of .NET v2.0 and Visual Studio 2005.

Note that the targeting problem is to make sure that if you run the software on a target machine, we have:

1. Built the software for that target environment
2. That the code that you are using is available on the target

And, to simplify things, we are not including the architecture (x86, x64, etc.) of the machine that you are targeting for this discussion. We are really only considering the target runtime environment.

Pseudo Multi-Targeting

With the release of Visual Studio 2008 and .NET Framework v3.5, there were suddenly two (2) frameworks that you could choose from. There was the .NET Framework v2.0 and the new .NET Framework v3.5. Note that both of these frameworks actually run on a single CLR (Common Language Runtime); the v2.0 CLR to be specific. The difference between these two frameworks is basically the new set of functionality delivered in v3.5, which included the new LINQ functionality and the Entity Framework. As a result, Visual Studio 2008 introduced a new concept that we now call "pseudo multi-targeting" which allowed you to specify that you wanted to target v2.0 or v3.5.

At compile time, if you had selected to target v2.0 and you attempted to use something that was only available in v3.5, you would get a compiler error. This allowed you to specifically target the 2.0 framework and be sure that you would not load up you app and find that the machine you were running on did not have the required components to run your application.

For assembly resolution, this means that a company might provide two different components in their SDK. One of those components might be for v2.0, and the other might use new features in v3.5, and as a result have a dependency on the v3.5 framework.

Real Multi-Targeting

In Visual Studio 2010, things got quite a bit more complex. With this release, the new .NET Framework v4.0 was release. And with it came a new CLR v4.0. This means that the CLR that the design time environment is running on, may not be the same as the actual runtime environment. This is where "real" multi-targeting kicked in.

With Visual Studio 2010, you can target .NET Framework v2.0. If you build you app and run it, it will always run on a machine that has .NET v2.0 installed on it. If you target v4.0, your app will have the 4.0 CLR reference, and hence will not run on v2.0. But, you will be able to use all the cool new features and changes in .NET v4.0. (for example, the new parallel Task library)

At this point, I think you pretty much get the idea. At build time, the process determines what you are targeting, and takes the reference that you have requested, and looks at the SDKs and components installed on your machine, and it selectively chooses the right assembly to match you target environment. Then, after having figured out all the specific references that you need, we pass those to the compiler, who then makes sure that you don't right code against some feature that won't be available when you go to run your application.

The rules for how we do the actual resolution are very specific, and they are, to be fair, quite complicated. But, with Visual Studio, you don't need to worry about that. When you go to the Add Reference dialog, you select an assembly or project from one of the tabs. We then write down your choice in the project file. When we build the project, we select the references for you based on what is the best selection for your target. If you later change your mind and re-target your application to something else, there is no need to fix up any of the references. You rebuild the project, and we then select the right references for the new target, and voila.

Add Reference

I hear this all the time, that "the Add Reference dialog is a Window to the GAC". It is not. The GAC is a runtime mechanism. However, we will look for items in the GAC for resolution as needed. In the Add Reference dialog, we very specifically show you the Framework assemblies for the target framework, and the matching registered SDK assemblies (as specified in AssemblyFoldersEx).

You can also add what we refer to as a "P2P" or Project to Project reference from the Add Reference dialog. This will get you a reference to another project in your build. We also use this in MSBuild to determine the dependencies so we know what to build first. (And I would not recommend the use of Solution Dependencies. But, that's another article.)

If you literally have an assembly that you can't reference any other way, given to you by another developer for example, then you can put it in your project folder or in a sub-folder. (although I don't recommend the "bin" folder as I blow this directory away all the time, and then you won't have your reference; plus if you put it in source control it's a nightmare) Next, use the Browse button in the Add Reference dialog to add the reference to it. This will use a HintPath to specify where the file is. Since it's not registered on the machine (that is, not part of an SDK and hence registered appropriately in AssemblyFoldersEx), then we really don't have any information to go on regarding multi-targeting. As a result, you are pretty much on your own if things go wrong at runtime. And the warnings and errors you may bet at build time when things really go wrong are confusing at best if you are not sure what you are doing. Don't get me wrong, this should work just fine, it's just not the preferred way of doing things.

Conclusion

I get lots of feedback from customers about issues with referencing. Most of the time the issues I see are related to the fact that we did a poor job, in my mind, of explaining how this all works. As a result, there are a lot of folks out there attempting to force a specific version of a reference, using HintPath, and other such nonsense to get their project to build. In reality, for referencing, "less is more". If you tell us you are targeting a specific framework, and you give us a reference like "System.Drawing", we will find the write "System.Drawing" to match you needs.

And actually, if you tell us you want to reference "System.Drawing, version=4.0.30319, Culture=neutral, PublicKeyToken=b77a5c561934e089" and you are targeting .NET v2.0, we will politely give you a warning, and give you the one that goes with the v2.0 framework. In this case we know that right version because we know all about the frameworks and what assemblies are the ones for specific framework targets. For third party assemblies supplied in SDKs, we only have limited information. But, either you will get an error when you compile your code, or worse, your application will fall over when you try to run it in the target environment.

So, leave the resolution to us. Let Visual Studio use the short name for an assembly. Don't use HintPath unless you have no other way to specify the reference, and realize that your off the beaten path, and you are not protected by multi-targeting.

MSBuild understands enough about solution files to translate them into MSBuild project files. When MSBuild is launch, it checks the extension of the project it has been asked to build. If it sees that the file you are building has the extension ".sln", it runs a conversion on that file to create a ".metaproj" file. This metaproj is really just a translation of the solution file into MSBuild project file format. Note that you normally never see this file, as it is only generated in memory.

If you want to take a look at the gory details inside the metaproj, you can set the environment variable "MSBuildEmitSolution" to "1" and MSBuild will write the file out with the name "{solutionname}.sln.metaproj".

SET MSBuildEmitSolution=1

Once this is set, just run you build as normal to generate the metaproj file.

One thing to note is that since MSBuild is translating the solution file into a project file, there are things that may not be translated correctly. There are also things that simply may not be definable in the MSBuild language. One such beast is the set of solution dependencies. I typically recommend that users steer clear of these, and instead opt for P2P (or project to project) references. But, that is a topic for another article.

 The bits you will see here will most likely revolve around my work here at Microsoft with MSBuild.

 I invite questions. So feel free to reply to this post, and I will do my best to get answers.

Chuck