VSTS | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013
Most components in Visual Studio Team Services (VSTS) and 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. For details, see About Unicode and Character Sets.
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:
- Rename the Computer
- Rename a Computer that Hosts a Stand-Alone Instance of SQL Server
- Windows Server Active Directory
Account name
User accounts identify users in VSTS 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:
- VSTS: Add team members
- On-premises TFS: Add users to team projects
User accounts that you add must conform to the following restrictions.
|
Restriction type |
Restriction |
|---|---|
|
Account name length |
|
|
Uniqueness |
|
|
Reserved group names |
|
|
Special character restrictions |
|
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 |
|
| Uniqueness |
|
| Reserved group names |
|
| Special character restrictions |
|
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 |
|
| Uniqueness |
|
| Special characters |
|
| Reserved names |
|
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 |
|
| Uniqueness |
|
| Special characters |
|
| Reserved names |
|
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 VSTS or the web portal for an on-premises TFS.
Note
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 VSTS 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 |
|
| Process template name uniqueness |
|
| Process template file size |
|
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 |
|
| Uniqueness |
|
| Special 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 VSTS 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 |
|
| Uniqueness |
|
| Special characters |
|
| Reserved names |
|
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 |
|
|
Special characters for nodes |
|
|
Reserved names |
|
|
Path length |
|
|
Path hierarchy depth |
|
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 |
|
| Special characters |
|
| Scope |
|
Field, link type, and category reference names
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 |
|
| Special characters |
|
| Uniqueness |
|
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 |
Microsoft.VSTS.Build.FoundIn |
The fictitious company Fabrikam Fiber might define the following custom work item fields: FabrikamFiber.Common.Severity The fictitious software company Contoso Corporation might define the following work item fields: Contoso.Common.BusinessPriority |
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 |
|
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 |
|
| Special characters |
|
|
Scope |
|
Global lists must conform to the following restrictions.
| Restriction type | Restriction |
|---|---|
| Number of items |
|
|
Uniqueness |
|
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.
|
|
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.
|
|
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 |
|
|
Special characters |
|
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 |
|
|
Local folder path length |
|
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 |
|
| File names |
|
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 |
|
|
Special 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 |
|
|
Special 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 |
|
|
Special characters |
|
Wiki page title naming conventions
Each wiki page corresponds to a file within the wiki git repo.
Names you assign to a wiki page title must conform to the following restrictions.
| Restriction type | Restriction |
|---|---|
| File name | The fully qualified page path should not exceed 235 characters. |
| Uniqueness | Page titles are case sensitive and must be unique within the wiki hierarchy. |
| Special characters |
|
| File size | Must not exceed the maximum of 15 MB |
| Attachment file size | Must not exceed the maximum of 10 MB |