Naming restrictions and conventions

Last Update: 11/18/2016

Team Services | TFS 2017 | TFS 2015 | Previous Versions

Most components in Visual Studio Team Services and Visual Studio Team Foundation Server (TFS) must comply with naming restrictions and conventions. Restrictions help guarantee a consistent user experience and provide compatibility with other applications.

Common restrictions include not exceeding the character length for a name, not containing special characters, and maintaining uniqueness of names within an object set.

Computers, accounts, groups, and collections

Common considerations

The length restrictions in this topic are measured by the number of Unicode characters permitted. Surrogate characters are composed of two Unicode characters and these will count as two characters against the length restriction. You can learn more about Unicode and character sets here.

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.

Computer name (on-premises TFS only)

When you install TFS, the computer name where you install TFS is associated with the name of the server.
Both the operating system and Active Directory impose certain restrictions on computer names as described in these articles:

Account name

User accounts identify users in Visual Studio Team Services or TFS. These accounts might correspond to an Active Directory, Azure Active Directory, Windows or other user account types.

You add existing user accounts. You can't create a user account. To add user accounts to a team project, see:

User accounts that you add must conform to the following restrictions.

Restriction type

Restriction

Account name length

  • Must not contain more than 256 Unicode characters

Uniqueness

  • Must not match any other user account added to the team project collection

Reserved group names

  • Must not be named with a $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 (,)

  • Must not include the following Unicode categories: LineSeparator, ParagraphSeparator, Control, Format, OtherNotAssigned

Group name

Groups enable you to apply certain rights or permissions to a group of users.

On-premises TFS groups can consist of Active Directory group accounts, TFS group accounts, Windows user accounts, Windows group accounts, or any mixture of these types. See Manage users or groups in TFS.

Groups that you add must conform to the following restrictions.

Restriction type Restriction
Group account name length
  • Must not contain more than 256 Unicode characters
Uniqueness
  • Project-level group accounts must not match any other group name in the same project
  • Collection-level group accounts must not match any other name of a group account in the team project collection
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 (,)

Team project collections (on-premises TFS only)

A team project collection identifies a group of team projects and the resources that are associated with those projects. It provides an organizing structure that you can use to define and control a group of team projects within an on-premises TFS.

Also, the collection name is part of the connection string used to connect team members to team projects. The default assigned corresponds to DefaultCollection. Manage team project collections provides more information.

Names you assign to team project collections must conform to the following restrictions.

Restriction type Restriction
Length
  • Must not contain more than 64 Unicode characters
Uniqueness
  • Must not be identical to any other collection name in your on-premises TFS deployment.
  • 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
    Learn more about reserved names: File Names, Paths, and Namespaces.

Team project and work item tracking

Team projects

A team project establishes a repository for source code and a place for teams to plan, track progress, and collaborate. The name of the team project is part of the connection string used to connect team members to team projects.

Names you assign to team projects that you create must conform to the following restrictions.

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
  • Must not be one of the hidden segments used for IIS request filtering like App_Browsers, App_code, App_Data, App_GlobalResources, App_LocalResources, App_WebResources, bin, or web.config.
    Learn more about reserved names: File Names, Paths, and Namespaces.

Process and process templates

A process defines the building blocks of the work item tracking system as well as other sub-systems you access through Visual Studio Team Services or the web portal for an on-premises TFS.

Terminology note: Both "process" and "process template" refer to an interdependent set of files used to create a team project. However, the features, rules, and behaviors associated with each differ slightly depending on whether you connect to Visual Studio Team Services or an on-premises TFS.

Choose a process describes the differences among the three default processes available to you.

Processes you define or customize must conform to the following restrictions.

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
  • Must not exceed 2 GB (gigabytes).

Kanban boards

Your Kanban board turns your backlog into an interactive signboard, providing a visual flow of work. As work progresses from idea to completion, you update the items on the board. Each column represents a work stage, and each card represents a user story (blue cards) or a bug (red cards) at that stage of work.

You can customize your Kanban boards to match how your team works by adding, removing, or renaming columns and swimlanes. Columns support the flow of work across the board. Swimlanes allow you to manage different classes of work as horizontal lanes on the board.

Column and swimlane names must conform to the following restrictions.

Restriction type Restriction
Length
  • Must not contain more than 256 Unicode characters
Uniqueness
  • Column names must not be the same as any other column name on the Kanban board
  • Swimlane names must not be the same as any other swimlane name on the Kanban board
Special characters
  • Must not contain any Unicode control characters or surrogate characters

Teams

Team names identify a group of individuals or groups that collectively work together as a team in a team project. Team members use this name to connect to the team when working in Visual Studio Team Services or the web portal for TFS.

As such, team names must conform to conventions that allow it to be rendered as part of a valid URL. In addition, each team name must be unique within a single project. However, there aren't any restrictions on using the same team name in different team projects within a team project collection. Add another team or a hierarchy of teams provides more information about working with teams.

Team names must conform to the following restrictions.

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
    Learn more about reserved names: File Names, Paths, and Namespaces.

Work items, work item types and customizations

You use work items to capture information to plan and track your software development projects. With work items, you can describe the work to be done, assign work, track status, and coordinate efforts within your team. Different types of work items -- such as user stories, tasks, bugs, and issues-- track different types of information.

All work item tracking objects are associated with one or more names. Most have friendly display names and all, except work item types and global lists, are associated with reference names. A friendly name is a unique, user-visible identifier for a field. Using friendly names ensure consistency across all team projects and work item types in a project collection. The system uses the reference name internally and you cannot change it after it is defined.

Restrictions are placed on several elements associated with work items, including reference and friendly names, field names, and attachment size

You can modify or add a custom work item type (WIT) to support your team's processes.

Attachments

Files attached to work items must conform to the following restrictions.

Restriction type Restriction

File size

Area Path and Iteration Path

Two work item fields, Area Path and Iteration Path, provide a tree structure hierarchy for grouping work. Area paths group work items by product, functional, or feature area. Iteration paths group work items into sprints, milestones, or time periods in which they’ll be worked on.

These multi-node fields use the backslash (\) characters to denote the hierarchy of nodes within the tree structure.

The names you assign to child nodes to these fields must conform to the following restrictions.

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

    Learn more about reserved names: File Names, Paths, and Namespaces.

Path length

  • Must not contain more than 4000 Unicode characters

Path hierarchy depth

  • Must not be more than 14 levels deep

WIT field names

Each WIT definition contains one or more work item fields. These fields define the information stored for work items based on the WIT. A work item field name uniquely identifies each work item field.

Work item field names that you add must conform to the following restrictions.

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 the team project collection. If you rename a field name, you change it for all work items and WITs defined within all team projects in the collection.

You must define a reference name whenever you add or create a work item field, link type, or category. Each work item field has an associated field reference name. The field reference name uniquely identifies each field and cannot be changed after it's assigned.

All reference names can be up to 70 Unicode characters long.

You can define a reference name by using alphanumeric characters, underscore characters, and hyphen characters. Each reference name must contain at least one period (.), but no period can appear at the start or end of a name. A reference name cannot start with a number or an underscore, and it cannot have multiple consecutive hyphens, such as (--).

Work item field reference names that you add must conform to the following restrictions.

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 within the team project collection
  • 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

Field reference names and portability

The work item type definition language includes the concept of a field reference name. Field reference names can help you to port definitions between Team Foundation project collections and also to allow third party integrations to find and refer to specific fields. These names are globally unique, just as a namespace in the .NET Framework application is globally unique.

Field reference names cannot be renamed. If, for example, you changed the field name "Title" to "Header", the field reference name of that field remains the same. Integrations and internal representations of fields should use the field reference name instead of depending on the field name itself.

The System namespace is used only to define all core system fields that are mandatory for Team Foundation system functions. Team Foundation Server prevents you from creating your own System.X field because it might impede Team Foundation Server functionality.

The Microsoft namespace is used to define work item tracking fields. These fields are defined in a work item type definition of the TFS process templates. TFS does not prevent you from creating your own Microsoft.X field. However, this practice is strongly discouraged because it might impede Team Foundation Server TFS functionality or the ability for the Configure Features wizard to successfully update a team project after a TFS upgrade.

Customers and partners can create their own field namespaces for custom work item types.

For descriptions of system fields and fields defined in the default process templates, see Index of work item fields.

Examples of field reference names

The following examples show valid field reference names, in various namespaces. Customers and partners can also define their own namespaces to support their custom work item types.

System namespace examples Microsoft namespace examples Other namespace examples

System.Id
System.Title
System.CreatedBy
System.CreatedDate
System.ChangedBy
System.ChangedDate
System.State
System.Reason

Microsoft.VSTS.Build.FoundIn
Microsoft.VSTS.Common.Activity
Microsoft.VSTS.Common.Discipline
Microsoft.VSTS.Common.Priority
Microsoft.VSTS.CMMI.TaskType
Microsoft.VSTS.TCM.AutomationStatus
Microsoft.VSTS.TCM.TestSuiteType

The fictitious company Fabrikam Fiber might define the following custom work item fields:

   FabrikamFiber.Common.Severity
   FabrikamFiber.Common.Phase
   FabrikamFiber.RiskManagement.RiskType
   FabrikamFiber.RiskManagement.Resolution

The fictitious software company Contoso Corporation might define the following work item fields:

   Contoso.Common.BusinessPriority
   Contoso.Bug.FoundInPhase
   Contoso.Bug.FixInPhase

Field help text

You can specify help text for a WIT field by using the HELPTEXT element. The system displays this text at run time to help users know what to enter into the field. Help text is scoped to a specific WIT in a specific team project. Apply a rule to a work item field provides information on adding help text.

Help text that you add must conform to the following restrictions.

Restriction type Restriction

Length

  • Must not contain more than 255 Unicode characters

Global lists (on-premises TFS only)

A global list is a set of list item values that you can use globally across all team project collections within an instance of an on-premises TFS. As you define WITs, you may find that some work item fields share the same set of allowed or suggested values. Global lists enable you to define these values one time and share them across multiple WITs and team projects. See Define global lists for details.

A global list, defined using the GLOBALLIST element contains one or more list items, specified using the LISTITEM element.

LISTITEM names must conform to the following restrictions.

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.

Global lists must conform to the following restrictions.

Restriction type Restriction
Number of items
  • Can't be empty. The global list must contain at least one LISTITEM element.

Uniqueness

  • The global list name must not be identical to any other global list name within the team project collection.

Team Foundation Build (on-premises TFS only)

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

Team Foundation Build is a separate installation from the TFS 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.

Your on-premises build computer must conform to the following restrictions.

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 types

Build types 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.

Build type names must conform to the following restrictions.

Restriction type Restriction

Uniqueness

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

Special characters

  • Must not contain the following printable character: $

Build quality

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. See Rate the quality of a completed build for a list of the default build quality values.

Build quality names must conform to the following restrictions.

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

Team Foundation version control

Version control names

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

Version control paths must conform to the following restrictions. See also Optimize your workspace.

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.

Version control files

The version control system stores many different types of files. Set up Team Foundation version control on your dev machine provides details on how to add existing Visual Studio projects or solutions.

Files and folders you add to Team Foundation version control must conform to the following restrictions.

Restriction type Restriction

Files and folders

  • Names must not contain the following printable characters: \ / : * ? " < > | ;
  • Folders 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: \ / : * ? " < > | ;

Version control labels

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.

Shelveset names must conform to the following restrictions.

Restriction type Restriction

Length

  • Must not contain more than 64 Unicode characters

Special characters

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

Workspaces

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. Create and work with workspaces provides more details.

Workspace names must conform to the following restrictions.

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: \ / " : < > | * ? ;