Naming Restrictions in Team Foundation

  • Article

Many components in Visual Studio Team Foundation Server (TFS) have certain naming restrictions. These restrictions help guarantee a consistent user experience and provide compatibility with other programs. These restrictions might include length, special characters, uniqueness, or other attributes.

This topic contains the following subsections:

Common Considerations

Restrictions for Team Foundation Server Group Account Names

Restrictions for Computer Names

Restrictions for Team Project Collection Names

Restrictions for Team Project Names

Restrictions for Team Names

Restrictions for Work Items

Restrictions for Work Item Customizations

Restrictions for Process Templates

Restrictions for Team Foundation Build

Restrictions for Version Control

See Also

Common Considerations

The length restrictions in this topic are measured by the number of Unicode characters permitted. For more information about Unicode, see "About Unicode and Character Sets" (https://go.microsoft.com/fwlink/?LinkId=76837). Surrogate characters are composed of two Unicode characters and these will count as two characters against the length restriction.

As with other operating system files, ASCII control characters (ASCII 1-31) and surrogate combinations are also not allowed. For general information about the operating system restrictions applied to file names, see "Naming Files, Paths, and Namespaces" ().

Restrictions for Team Foundation Server Group Account Names

Team Foundation group accounts enable you to apply certain rights or permissions to a group of users. This Team Foundation group can consist of Windows user accounts, Windows group accounts, Active Directory group accounts, Team Foundation group accounts, or any mixture of these types. For more information about managing users with groups, see Users, groups, and permissions in Team Foundation Server deployments and Configuring Users, Groups, and Permissions. If you want examples of how to add a new member to groups used in TFS, SharePoint Products, and SQL Server Reporting Services, see Add Users to Team Projects. If you want to know more about how to check the permissions for your account, see Change permission levels.

When a Team Foundation group account is created or changed, it must meet certain Team Foundation Server restrictions. The following table describes these restrictions.

Restriction Type

Restriction

Group account name length

  • Must not contain more than 256 Unicode characters

Uniqueness (collection-level group accounts)

  • Must not match any other name of a group account in the team project collection

Uniqueness (project-level group accounts)

  • Must not match any other group name in the same project

Reserved group names

  • Must not be named $NAMESPACE at either the project or the server level

Special character restrictions

  • Must not include the following printable characters: "/ \ [ ] : | < > + = ; ? *

  • Must not include nonprintable characters in the ASCII value range of 1-31

  • Must not end in a period (.)

  • Must not include commas (,)

Note

You do not create user accounts in Team Foundation Server.

Restrictions for Computer Names

During the TFS installation process, the computer name is associated with the name of the server.

Both the operating system and Active Directory impose certain restrictions on computer names. For more information about renaming a computer, see "Rename a Computer" (https://go.microsoft.com/fwlink/?LinkId=76839). For more information about Active Directory, see "Windows Server 2003 Active Directory" (https://go.microsoft.com/fwlink/?LinkId=47541).

Restrictions for Names of Team Project Collections

The name of a team project collection identifies a grouping of team projects and the resources that are associated with those projects. A team project collection is an organizing structure that you can use to define and control a group of team projects within TFS. Team members will use the name of the team project collection when they connect to team projects in TFS. For more information, see Organizing Your Server with Team Project Collections.

The following table describes the restrictions for names of collections.

Restriction Type

Restriction

Length

  • Must not contain more than 64 Unicode characters

Uniqueness

  • Must not be identical to any other collection name in your deployment of Team Foundation Server.

  • If your deployment includes SharePoint Products or SQL Server Reporting Services, must not be identical to the name and full path of an existing SharePoint site, report server, or Reporting Services Web site.

Special characters

  • Must not contain any Unicode control characters or surrogate characters.

  • Must not contain the following printable characters: / : \ ~ & % ; @ ' " ? < > | # $ * } { , + = [ ]

  • Must not contain an ellipsis (…) or a double period (..)

  • Must not start with an underscore (_)

  • Must not start or end with a period (.)

Reserved names

  • Must not be a system-reserved name such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, AUX, Web, or WEB

    For more information about reserved names, see this page on the Microsoft Web site: File Names, Paths, and Namespaces.

Restrictions for Project Names

The project names in TFS identify a collection of work items, documents, reports, team builds, and a version control tree that make up a particular project in TFS. Team members will use this project name to connect to the project in TFS.

The following table describes the restrictions for project names.

Restriction Type

Restriction

Length

  • Must not contain more than 64 Unicode characters

Uniqueness

Must not be identical to any other name in the team project collection, the SharePoint Web application that supports the collection, or the instance of SQL Server Reporting Services that supports the collection

Special characters

  • Must not contain any Unicode control characters or surrogate characters

  • Must not contain the following printable characters: / : \ ~ & % ; @ ' " ? < > | # $ * } { , + = [ ]

  • Must not contain an ellipsis (…) or a double period (..)

  • Must not start with an underscore (_)

  • Must not start or end with a period (.)

Reserved names

  • Must not be a system-reserved name such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, or AUX

  • For more information about reserved names, see "Naming Files, Paths, and Namespaces" .

Restrictions for Team Names

The Team names in TFS identify a group of individuals or groups that collectively work together as a team in a project in TFS. Team members will use this name to connect to the team in Team Web Access. The team name must be a name that can be rendered as part of a valid URL. In addition, each team name must be unique within a single project, but there is no restriction barring using the same team name in different projects within a team project collection. For more information about working in teams in TFS, see Collaborate (dig deeper).

The following table describes the restrictions for team names.

Restriction Type

Restriction

Length

  • Must not contain more than 64 Unicode characters

Uniqueness

Must not be identical to any other name in the project

Special characters

  • Must not contain any Unicode control characters or surrogate characters

  • Must not contain the following printable characters: / : \ ~ & % ; @ ' " ? < > | # $ * } { , + = [ ]

  • Must not contain an ellipsis (…) or a double period (..)

  • Must not start with an underscore (_)

  • Must not start or end with a period (.)

Reserved names

  • Must not be a system-reserved name such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, or AUX

  • For more information about reserved names, see Naming Files, Paths, and Namespaces.

Restrictions for Work Items

Microsoft Visual Studio Application Lifecycle Management tracks the progress on a project by using items such as bugs, requirements, tasks, and risks. These items are referred to generically as work items. This section describes restrictions on the data stored in the work items.

Restrictions for Work Item Attachments

Files can be attached to work items. The following table describes the restrictions on work item attachments.

Restriction Type

Restriction

File size

  • By default, the work item file attachment size limit is 4,096 kilobytes. This value can be changed by the Team Foundation Administrator. The maximum size that can be set by the Administrator is 2 gigabytes.

  • Default size: 4,096 kilobytes

  • Maximum size: 2 gigabytes

Restrictions for Work Item Areas and Iterations

Work items contain a field for Project Area and a field for Project Iteration. They are used to organize and display work items into logical groupings.

The Project Area and Project Iteration are paths made up of multiple node items separated by backslash (\) characters. Nodes are defined by the Team Foundation Server administrator to reflect the project areas and project cycle. The following table describes the restrictions on nodes and paths.

Restriction Type

Restriction

Node length

  • Must not contain more than 255 characters

Special characters for nodes

  • Must not contain Unicode control characters

  • Must not contain any one of the following characters: \ / $ ? * : " & > < # % |

  • Must not contain characters prohibited by the local file system. For more information about Windows character restrictions, see Naming Files, Paths, and Namespaces.

Reserved names

  • Must not consist only of a period (.) or two periods (..)

  • Must not be a system-reserved name such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, or AUX

  • For more information about reserved names, see Naming Files, Paths, and Namespaces.

Path length

  • Must not contain more than 4000 Unicode characters

Path hierarchy depth

  • Must not be more than 14 levels deep

Restrictions for Work Item Customizations

Team Foundation Server tracks the progress on a project by using items such as bugs, requirements, tasks, and risks. These items are referred to generically as work items.

Administrators of team projects can decide to change work item type definitions either at the project level or in a process template. For more information about how to customize work item types, see Customize Project Tracking Data, Forms, Workflow, and Other Objects. This section describes restrictions you will encounter when you customize work items and their associated elements.

Restrictions for Work Item Field Names

Each work item type contains one or more work item fields. These fields define the information stored in a work item type. A work item field name uniquely identifies each work item field.

The following table describes the restrictions for work item field names.

Restriction Type

Restriction

Length

Must not contain more than 128 Unicode characters

Special characters

  • Must not contain leading or trailing spaces

  • Must not contain two or more consecutive spaces

  • Must not contain periods (.)

  • Must not contain opening or closing square brackets ([ ])

Scope

  • Work item field names are scoped to an entire deployment of TFS. If a field name is changed, the change will be reflected in all projects and the work item types that contain that work item field.

Restrictions for Work Item Field Reference Names

Each work item field has an associated field reference name. The field reference name uniquely identifies each field and cannot be changed after it is assigned. The following table describes the restrictions applied to field reference names.

Restriction Type

Restriction

Length

  • Must not contain more than 70 Unicode characters

Special characters

  • Must not contain hyphens (-)

  • Must contain at least one period (.)

  • Must not start or end with a period (.)

  • Must not start with a number

  • Must not start with an underscore (_)

Uniqueness

  • Must not be identical to any other field reference name in Team Foundation Server

  • Must not be identical to any other field reference name after those names are processed by the computer to replace all periods (.) with underscores (_)

    For example, the field reference names My._Field and My_.Field would both be processed by the computer to be the same name: My__Field

Restrictions for Work Item Field Help Text

As an option, you can associate help text with work item fields by using the <HELPTEXT> tag. The system displays this text at run time to help users know what to enter into the field. For more information about work item field help text, see Define the Help Text for a Work Item Field.

The following table describes the restrictions for work item field help text.

Restriction Type

Restriction

Length

  • Must not contain more than 255 Unicode characters

Scope

Unlike the field name and field type, field Help text is scoped to a specific work item type in a specific team project.

Restrictions for Global Lists

A global list is a set of list item values that is stored and used globally by all Team Foundation servers in a Team Foundation Server implementation. As you define work item types, you may find that some work item fields share the same set of possible values. Global lists enable you to define these values one time and share them among multiple work item types. For more information, see Define Global Lists.

A global list (GLOBALLIST) contains one or more list items (LISTITEM elements).

The following table describes the restrictions on list items.

Restriction Type

Restriction

Length

  • Must not contain more than 254 Unicode characters

  • Must not be empty

Special characters

  • Must not contain leading or trailing white space

  • Must not contain two consecutive spaces

  • Must not contain backslash (\) characters

Scope

  • Since global lists are available among all projects, they must not contain elements defined at the project level, such as project-specific group account definitions.

The following table describes restrictions that apply to a global list.

Restriction Type

Restriction

Number of items

The global list must not be empty. It must contain at least one LISTITEM element.

Uniqueness

  • The global list name must not be identical to any other global list name in Team Foundation Server.

Restrictions for Process Templates

A process template is a set of default work items, work item queries, product templates, reports, security groups, and guidance that influences the structure of a project in Team Foundation. Team Foundation Server includes two default process templates that encompass two different styles for managing the software cycle. These templates can be customized to reflect the unique needs of your organization. For more information, see Customize Process Templates.

The following table describes restrictions on the process templates.

Restriction Type

Restriction

Process template name length

Must not contain more than 256 Unicode characters.

Process template name uniqueness

  • Must be unique across the Team Foundation server.

  • If you upload a template with the same name as an existing template, the existing template will be overwritten.

Process template file size

The process template file size must not exceed 2 GB (gigabytes).

Restrictions for Team Foundation Build

Team Foundation Build lets you manage all the aspects of the build process on a single computer. By using Team Foundation Build, you can synchronize the sources, compile the application, run associated unit tests, perform code analysis, release builds on a file server, and publish build reports.

Build Computer Restrictions

Team Foundation Build is a separate installation from the Team Foundation Server application tier, data tier, or Visual Studio client. You may designate a separate computer. Otherwise, you can install the build side-by-side on the client computer or on the servers.

The following table describes restrictions for the build computer.

Restriction Type

Restriction

Disk space

Must contain sufficient space for the build (insufficient space will lead to failed builds).

Build directory

Must be a local path (for example, C:\builddirectory).

Drop location directory

Must be a UNC path (for example, \\server\share).

Drop location permissions

Each generated build is put in a new directory in the drop folder.

  • The Team Foundation Server Service account (for example, Domain\TFSSERVICE) must have Full Control permission access to the UNC drop location.

  • The UNC drop location must be a shared folder.

Team Foundation Build Service account

If you change the TFS Service account after the initial installation, you must make sure that the following conditions are true.

  • The account is a member of the Build Services group.

  • The account has read/write permissions to the temporary folders and the ASP.NET temporary folder.

  • The account has Full Control permission to the build directory and drop location.

Firewall issues

If the build computer is firewall enabled, make sure that the program tfsbuildservice is in the exceptions list.

Build Type Names

Team Foundation Build uses build types to configure the conditions under which a single solution or a set of solutions in a team project will be built. To conduct a build, you must either create a new build type or use an existing build type. For more information about build types, see Define Your Build Process.

The following table describes the restrictions on build type names.

Restriction Type

Restriction

Uniqueness

Must not be the same as any other build type name in the project

Special characters

  • Must not contain the following printable character: $

Build Quality Names

The build quality lets you attach a quality level or completion state to a completed build. Team Foundation Build also lets you create new values for the build quality type. For more information, see Create a Build Definition. For a list of the default build quality values, see Rate the Quality of a Completed Build.

The following table describes the restrictions on build quality names.

Restriction Type

Restriction

Length

Must not contain more than 256 Unicode characters

Uniqueness

Must not be the same as any other Build Quality name in the Team Foundation Build computer

Restrictions for Version Control

Team Foundation version control provides a central repository for files and the commands that are required to manage those files across a team. It also provides customizable check-in policies, branching, merging, shelving, and many other features.

Version Control Paths

The following table describes restrictions on a version control path.

Restriction Type

Restriction

Server source control folder path length

  • Must not contain more than 259 Unicode characters for a single folder or file name.

  • Must not contain more than 388 Unicode characters for a directory.

  • Must not contain more than 399 Unicode characters for a combined directory and file name.

Local folder path length

  • Must not contain more than 248 Unicode characters for a directory.

  • Must not contain more than 260 Unicode characters for a combined directory and file name.

See also: Optimize Your Workspaces.

Adding Files into Version Control

The version control system stores many different types of files. For more information about how to add existing Visual Studio projects or solutions into version control, see Set Up Your Dev Machine and Start Using Version Control.

The following table describes the restrictions applied to files and folders to be added to version control.

Restriction Type

Restriction

File extensions

  • Must not contain the following printable characters: / \ : * ? " < > | ;

Folders

  • Must not be empty

  • Must not contain files that have pending changes

  • Must not reside outside the mapped directory for the active workspace

File names

  • Must not begin with a $

  • Must not contain the following printable characters: / \ : * ? " < > | ;

Label Names

In Team Foundation version control, a label is a name applied to a specific set of revisions. You can attach labels to a set of unrelated files in version control. This lets you retrieve the files or act upon them as a group. The following table describes the restrictions put on label names.

Restriction Type

Restriction

Length

Must not contain more than 64 Unicode characters

Special characters

  • Cannot end with a space ( ) or period (.)

  • Must not contain the following printable characters: " / : < > \ | * ? @ ;

Shelvesets

Shelvesets enable you to set aside temporarily a batch of pending changes and then, as an option, remove the pending changes from your workspace. Later, you can restore the changes in a shelveset to your workspace or put them into another user's workspace.

The following table describes restrictions on shelveset names.

Restriction Type

Restriction

Length

Must not contain more than 64 Unicode characters

Special characters

  • Must not contain the following printable characters: " / : < > \ | * ? ;

Workspace Names

A workspace is a client-side copy of the files and folders in Team Foundation version control. When you create multiple workspaces, you can have different versions of the same version control folder on a client computer. For more information about workspaces, see Manage Your Workspaces. The following table describes restrictions on workspace names.

Restriction Type

Restriction

Length

Must not contain more than 64 Unicode characters

Special characters

  • Cannot end with a space ( )

  • Must not contain the following printable characters: " / : < > \ | * ? ;

See Also

Tasks

Create a Build Definition

Rate the Quality of a Completed Build

Concepts

Customize Project Tracking Data, Forms, Workflow, and Other Objects

Define the Help Text for a Work Item Field

Define Global Lists

Customize Process Templates

Define Your Build Process

Manage Your Workspaces