what's the best way, using the TFS API, to add a label to a file?

Question

I'd like to add a label to a set of files using the TFS API. My code looks like this:

VersionControlLabel label = new VersionControlLabel(this.vcServer, this.label,
                this.vcServer.AuthenticatedUser, this.labelScopeDirectory, this.labelComment);

            List<LabelItemSpec> labelSpecs = new List<LabelItemSpec>();

            // iterate files and versions 
            foreach (var fileAndVersion in this.filesAndVersions)
            {
                VersionSpec vs = null;
                Item i = null;
                // i have no idea why the itemspec is needed instead of the item and version... 
                ItemSpec iSpec = new ItemSpec("{0}/{1}".FormatString(this.source, fileAndVersion.Key), RecursionType.None);
                GetItemAndVersionSpec(fileAndVersion.Key, fileAndVersion.Value, out vs, out i);
                labelSpecs.Add(new LabelItemSpec(iSpec, vs, false));
            }

            this.vcServer.CreateLabel(label, labelSpecs.ToArray(), LabelChildOption.Merge);

(there are some extension methods in there... this is all largely lifted from this blog post)

The thing that concerns me is things like this in the MSDN docs:

This enumeration supports the .NET Framework infrastructure 
and is not intended to be used directly from your code. 

So MSDN is telling me not to use that enumeration (LabelChildOption), which is afaik the only way to create a label and add it to a file.

Is there a better way? Is this sort of a "grey" area in the TFS API?

Answer 1

// i have no idea why the itemspec is needed instead of the item and version...

ItemSpec contains a RecursionType. If you know in advance you're going to be labeling all children of a folder (either 1-level, or with full recursion into all subfolders), you can use an ItemSpec to greatly condense the size of the LabelItemSpec[] that will be passed to & from the server.

Is this sort of a "grey" area in the TFS API?

Not grey, just poorly documented. Labels are kind of an afterthought in TFS; they play no role in the "Microsoft way" of managing a SDLC, and so you won't find them mentioned in the guidance at all. From what I can tell, they're mostly there for feature completeness (aka competitive analysis). They are also handy for several complex one-off database manipulations that would otherwise not be possible from the client API.

Read Buck Hodges' explanation in the "community content" section below the MSDN article -- that's the important part. Replace is generally closer to what people want than Merge, but if you're certain you're creating a brand new label then it doesn't matter.