VersionControlServer.CreateLabel Method
Creates or updates a label. A label designates a collection of specific versions of files and folders. For example, the label Beta 1 may refer to the files server.cs, client.cs, and om.cs as they were on March 3, and the file server.cs as it was on March 5. When you applying a label, it allows you to get the versions of the files with that label. This procedure is commonly used to ensure that you can reproduce a build. Every label has a scope, and its name must be unique within that scope. Most commonly, a label is scoped by the team project. This means that within a given team project, there can be only one label called Beta 1. However, you can choose to set the scope of a label to a lower level in the folder hierarchy. If Beta 1 is scoped at $/CmdLine/shell, then there can be no other label called Beta 1 in $/CmdLine/shell or any folder below it; however, $/CmdLine/parser may use the same label.
Namespace: Microsoft.TeamFoundation.VersionControl.Client
Assembly: Microsoft.TeamFoundation.VersionControl.Client (in Microsoft.TeamFoundation.VersionControl.Client.dll)
Syntax
'Declaration
Public Function CreateLabel ( _
label As VersionControlLabel, _
itemSpecs As LabelItemSpec(), _
options As LabelChildOption _
) As LabelResult()
'Usage
Dim instance As VersionControlServer
Dim label As VersionControlLabel
Dim itemSpecs As LabelItemSpec()
Dim options As LabelChildOption
Dim returnValue As LabelResult()
returnValue = instance.CreateLabel(label, _
itemSpecs, options)
public LabelResult[] CreateLabel(
VersionControlLabel label,
LabelItemSpec[] itemSpecs,
LabelChildOption options
)
public:
array<LabelResult^>^ CreateLabel(
VersionControlLabel^ label,
array<LabelItemSpec^>^ itemSpecs,
LabelChildOption options
)
public function CreateLabel(
label : VersionControlLabel,
itemSpecs : LabelItemSpec[],
options : LabelChildOption
) : LabelResult[]
Parameters
label
Type: Microsoft.TeamFoundation.VersionControl.Client.VersionControlLabelA VersionControlLabel object defining which label to create or update. When creating a new label, you should create a VersionControlLabel object yourself and pass it to this method. When updating an existing label, you may create the VersionControlLabel object yourself and match the name, scope and owner to an existing label, or you may pass a VersionControlLabel object received from the QueryLabels method (set the includeItems parameter to false, so that you can retrieve only the metadata from QueryLabels and pass on only the metadata into CreateLabel). The VersionControlLabel object is tagged with the VersionControlServer on which the label exists; this must match the VersionControlServer on which you are calling this method.
The label name may be up to 64 characters long. The owner name must be a valid identity on the server. The scope must be a valid server item. The comment may be up to 2048 characters long. If an owner name is not specified, the calling user's identity is assumed. If a scope is not specified, the system defaults to the lowest-level folder that is a common parent to all the specified items.
itemSpecs
Type: array<Microsoft.TeamFoundation.VersionControl.Client.LabelItemSpec[]The items that you want to add to the label. If a label already exists, the existing items will still be part of the label and you will add new items to the existing label. (To remove items from an existing label, use UnlabelItem.) For each item, you must specify the following.
itemSpec.item: The string that designates a Team Foundation Server file or folder. The string can be given as a Team Foundation Server path ($/CmdLine) or a file path (C:\code\cmdline).
itemSpec.recursionType: None, OneLevel, or Full. In general, you should not use None for a folder. If you label a folder non-recursively, only that item will be in the label and none of its children. If you label a file recursively, all files that match that filename under that folder will be labeled, so you could recursively label $/CmdLine/*.cs.
versionSpec: Indicates the version of the item to be labeled.
exclude. This Boolean variable is used if, for instance, you want to recursively label $/CmdLine and everything below it except for $/CmdLine/docs. Rather than listing everything below $/CmdLine, you can (in one function call) add all of $/CmdLine and exclude all of $/CmdLine/docs, both recursively. exclude is used only to prevent items from being added to a label; to remove items from an existing label, use the UnlabelItem method.
options
Type: Microsoft.TeamFoundation.VersionControl.Client.LabelChildOptionIf a label with an identical name already exists on the server, and the scope specified by the provided VersionControlLabel object conflicts with the scope of one or more existing labels on the server, the LabelChildOption parameter determines how to resolve those conflicts. If two labels named "Beta" already exist in scopes $/Project1 and $/Project2, and a CreateLabel command is issued for a label named "Beta" with scope $/, there are three ways to resolve the conflict:
LabelChildOption.Fail: Abort the operation. An exception will be thrown from the server to the client that describes the reason for the failure.
LabelChildOption.Merge: The existing labels named "Beta" with scopes $/Project1 and $/Project2 are deleted and a new label named "Beta" with scope $/ is created in its place. The contents of the old labels as well as those items specified by this CreateLabel call are merged together into the single label.
LabelChildOption.Replace: The existing labels named "Beta" with scopes $/Project1 and $/Project2 are deleted and a new label named "Beta" with scope $/ is created in its place. The contents of the old labels are discarded. The new label will only contain those items specified by this CreateLabel call.
Return Value
Type: array<Microsoft.TeamFoundation.VersionControl.Client.LabelResult[]
Each returned LabelResult object gives a label name (a string), a scope (which may not match the scope you specified, if you have been merged into a parent label), and a status that indicates that the label was created (LabelResultStatus.Created) or updated (LabelResultStatus.Updated). Any returned failures are reported as NonFatalError events.
Remarks
If an itemSpec does not match anything, a failure will be reported.
.NET Framework Security
- Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.