Intro to Solution Binding in TFS, plus bonus FAQ

Solution Explorer isn't working the way I expect.  How do I fix it?  In TFS, the answer is usually quite simple, because TFS uses workspaces to do most of the dirty work.  So if you're familiar with our workspace model, a quick behind-the-scenes tour of solution binding should equip you to solve most problems yourself.  (If not, start here). 

You may have heard the best practice "always use the Add To SCC / Open From SCC features the first time you work with a solution."  The reason is that these features handle all the extra work needed to make sure Solution Explorer, your source control provider, and the integration between the two is initialized and talking to each other happily.  Let's take a high-level peek inside Add To SCC, which must perform 3 main tasks:

1. See if the root of the project / solution is mapped
   • If so, do nothing
   • If not, prompt the user for a new mapping
2. Pend Adds on all child projects & files as necessary
3. Record the mapping into the *.sln and *proj files.  Such entries in the sln/proj files are known as "bindings".  They are what tell Solution Explorer to activate its Source Code Control Integration (SCCI) features: special status glyphs, adding Checkin/Checkout to the context menu, etc.

Immediately, we can see why using Source Control Explorer or the tf.exe command line to add your solution won't turn on SCCI -- you skipped step 3, and possibly step 1 as well.  So how do you fix it?  The answer lies in the mysterious Bind dialog.*  (File -> Source Control -> Change Source Control)

I'm actually stealing an image from VSS here.  In VSS and many other source control providers, this is where you configure your local <-> server mappings, control which projects are online vs offline, and otherwise manipulate bindings.  In case VSS users are wondering -- yes, VSS does have its own "working folders" but they are too fragile for this purpose. 

TFS, on the other hand, does use its internal mapping scheme (workspaces) for this task.  As a result, all buttons are disabled except Bind/Unbind and Refresh.  The "advanced bind dialog" (what you get when clicking a single row, then clicking the "..." that appears underneath Server Binding) is also gone.  When you click Bind, TFS will ask your current workspace what the server name of the sln/proj file is, then blindly write that into the bindings.  Depending on whether those files actually exist on the server, it may or may not come up Valid.  If not, you can't fix it from here.  It's all controlled by the workspace. 

I know, tight coupling with a totally separate dialog doesn't sound good.  But trust me, it makes life easier.  As we'll see in the Q&A section, virtually all problems can be solved by the same advice: fix your workspace and rebind.  So if you understand workspaces, you're set.  Meanwhile, fixing VSS bindings requires you to grok weird Visual Studio-specific concepts like "unified binding root."  See Alin's awesome explanations:
https://alinconstantin.members.winisp.net/webdocs/scc/Bindings.htm
https://alinconstantin.members.winisp.net/webdocs/scc/VSNetVC6.htm

Let's summarize what we've learned so far by mimicking the Add To SCC feature on our own.

1. Bring up the Workspaces dialog.  Type 'tf workspace <wsname>' or use the dropdown in Source Control Explorer.  Verify that all the projects you're trying to add can be mapped onto a server path.  If not, add an additional mapping.
2. Pend adds on your files.  'tf add <solutiondir> /r' will do it, as will the Add dialog in SCE.
3. Bring up the Bind dialog.*  Highlight all rows and click Bind.  If you did steps 1-2 correctly, they should all light up as 'Valid'.

(VSS users take note: at this point you need to save & Checkin.  The files are only pending Add, not committed to source control yet).

We're now equipped to answer some common questions.

Q: I added all my code to TFS. When I opened one of my solutions from disk, Solution Explorer didn't show any SCCI / I got an error. How do I fix it?
A: Bring up the Bind dialog.  If there are any old bindings there (e.g. to a previous source control system), use the Unbind button to remove them.  Once everything is unbound, highlight all rows and click Bind.

Q: I moved my solution to a different location on disk, now SCCI doesn't work. Why?
A: You should've used the Workspace dialog to move the folder(s) for you.  Tf.exe and Source Control Explorer won't work until you fix your workspace.  Do so and SCCI will be happy too.

Q: I want to add a new project, but Add Project To Source Control is not an option on the context menu! What gives?
A: Chances are that project file already has bindings of some sort.  Bring up the Bind dialog.  Unbind + Bind should fix it.

Q: There's an extra mapping in my workspace that I don't remember adding. Where did it come from?
A: If you ran the Add To SCC wizard, and one of the projects wasn't mapped in the current workspace, then you probably got a dialog like this one:

What you may not have realized is that your choice resulted in a new mapping from the specified local folder to the server path you chose. 

If you used Open From SCC, we will actually add missing workspace mappings automatically.

That's all for now.  Next time, some limitations of this model.

*Two caveats.  First of all: no, you aren't blind, it's really the "Change Source Control" dialog, but nobody calls it that.  Sorry.  Second, since we're starting from scratch here, make sure you have the correct SCC plugin selected in Tools -> Options -> Source Control.