Naming restrictions and conventions

  • Article

TFS 2017 | TFS 2015 | TFS 2013

Most components in Azure DevOps must follow 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.

Note

For limits on the number of items you can define, see Work tracking, process, and project limits.

General considerations

The length restrictions in this article are measured by the number of Unicode characters permitted. Surrogate characters are composed of two Unicode characters, which 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.

Azure Artifacts

Universal packages must conform to the following restrictions.

Restriction type

Restriction

Package name

  • Must be lowercase.
  • Must start and end with letters or numbers.
  • Must only contain letters, numbers, and non-consecutive dashes, underscore, or periods.

Package version

  • Must be lowercase without build metadata.

Azure Boards

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. To learn more, see Azure Boards documentation.

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

There are restrictions on several elements that are associated with work items, including reference and friendly names, field names, and attachment size.

Area and iteration paths

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 for addressing those work items.

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

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 File Names, Paths, and Namespaces.

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.

Path length

  • Must not contain more than 4,000 Unicode characters

Path hierarchy depth

  • Must be fewer than 14 levels deep

Attachments

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

Restriction type

Restriction

File size

Board column and swimlane names

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.

Customize your Kanban boards 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

Field names

Each work item type contains one or more work item fields. These fields define the information stored for work items based on the work item type. Each work item field has an associated field reference name. The field reference name uniquely identifies each field and can't be changed after it's assigned. For more information about out-of-box work item fields, see Work item field index.

Work item field names must conform to the following restrictions.

Restriction type

Restriction

Length

  • Must not contain more than 128 Unicode characters

Special characters

  • Field names must contain at least one alphabetic character
  • Must not contain any one of the following characters: .,;':~/*|?"&%$!+=()[]{}<>-`
  • Must not contain leading or trailing spaces
  • Must not contain two or more consecutive spaces

Scope

  • Must be unique within the organization or project collection Work item field names are scoped to the project collection. If you rename a field name, you change it for all work items and WITs defined within all projects in the collection.

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. You're prevented from creating your own System.X field because it might impede functionality.

The Microsoft namespace is used to define work item tracking fields. These fields are defined in a work item type definition of the process templates. You're not prevented from creating your own Microsoft.X field. However, we discourage creating your own field because it might impede functionality or the ability for the Configure Features wizard to successfully update a project after an 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.FixInPhas

Field help text

The system displays help text at run time to help users know what to enter into the field. Help text is scoped to a specific work item type in a specific project.

For the Inheritance process, you specify help text for a field through the Edit field dialog, Definition tab, Description. See Add a custom field to a work item type. For the On-premises XML process, you specify help text by using the HELPTEXT element. See Add or modify a field to track work.

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

A global list is a set of list item values that you can use globally across all 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 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

  • Can't be empty. The global list must contain at least one LISTITEM element.

Define a reference name whenever you add or create a link type or category. All reference names can be up to 70 Unicode characters long.

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 must not start with a number or an underscore, and it can't have multiple consecutive hyphens, such as (--).

Restriction type

Restriction

Length

  • Must not contain more than 70 Unicode characters

Uniqueness

  • Must not be identical to any other field reference name within the project collection
  • Must not be identical to any other field reference name after those names get 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

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 numberMust not start with an underscore (_)

Tags (work items)

Work item tags correspond to one or two keyword phrases that support your needs to filter work tracking tools such as backlogs, boards, and queries or define queries. To learn more, see Add work item tags to categorize and filter lists and boards

Tag names must conform to the following restrictions.

Restriction type

Restriction

Length

  • Must not contain more than 400 characters, cannot be null or empty

Special characters

  • Must not contain separator characters: , or ;
  • Must not contain Unicode control or format characters, such as a line feed, paragraph separator, carriage return, or other mismatched surrogate 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.

Azure Pipelines

Azure pipeline definitions must conform to the following restrictions. To learn more, see Azure Pipelines documentation.

Restriction type

Restriction

Job name

  • Must only contain alphanumeric characters and '_'
  • Must not start with a number
  • Must have a unique name
  • Must not contain keywords, for example: "deployment"

Stage name

  • Must only contain alphanumeric characters and '_'
  • Must not start with a number
  • Must not contain keywords, for example: "deployment"

Expressions

  • Must start with a-Z or _AND, followed by a-Z, 0-9, or _

Azure Repos (Git)

Each Azure DevOps project can contain multiple Git repos. The names you assign to Git repos must conform to the following restrictions. To learn more, see Azure Repos Git documentation.For more information on naming restrictions for other Git items such as branches and tags, see git check-ref-format.

Important

Although you can include spaces within repo names, we don't recommend that you do so.

Restriction type

Restriction

Length

  • Must not contain more than 64 Unicode characters

Uniqueness

  • Must not be identical to any other Git repo name in the project

Special characters

  • Must not contain any Unicode control characters or surrogate characters
  • Must not contain the following printable characters: / : \ ~ &amp; % ; @ &#39; &quot; ? &lt; &gt; | # $ * } { , + = [ ]
  • Must not start with an underscore (_)
  • Must not start or end with a period (.)

Azure Repos (TFVC)

Team Foundation version control (TFVC) 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. To learn more, see Azure Repos TFVC documentation

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

In the web portal and REST API, certain operations have a more restrictive path length than Visual Studio and TF.exe clients. These operations include Edit, Rename, and Delete, and occur because the web portal/REST uses a randomly generated workspace for concurrency when pending the changes.

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

Web portal and REST-specific length restrictions

  • Must not contain more than 215 Unicode characters for a combined project name, directory, and file name

TFVC 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 be outside the mapped directory for the active workspace

Files names

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

TFVC Labels

In Team Foundation version control (TFVC), 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, which 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

  • Can't end with a space ( ) or period (.)
  • Must not contain the following printable characters: \ / " : < > * ? @ | ;

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

TFVC workspaces

A workspace is a client-side copy of the files and folders in Team Foundation version control (TFVC). 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

  • Must not end with a space ( )
  • Must not contain the following printable characters: \ / " : < > | * ? ;

Computer names

The computer name where you install Azure DevOps 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:

Process and process templates

A process defines the building blocks of the work item tracking system and other subsystems that you have access to after connecting to a project.

Note

Terminology note: Both "process" and "process template" refer to an interdependent set of files used to create a project. 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

Length

  • Must not contain more than 256 Unicode characters

Uniqueness

  • Must be unique across Azure DevOps
  • If you upload a template with the same name as an existing template, the existing template is overwritten

Process template file size

  • Must not exceed 2 GB (gigabytes)

Project collections

A project collection identifies a group of 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 projects defined for an Azure DevOps Server.

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

Names you assign to 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 deployment
  • If your deployment includes SharePoint Products or SQL Server Reporting Services, they can't be identical to the name and full path of an existing SharePoint site, report server, or Reporting Services website

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 File Names, Paths, and Namespaces

Special characters

  • Must not contain any Unicode control characters or surrogate characters.
  • Must not contain the following printable characters: / : \ ~ &amp; % ; @ &#39; &quot; ? &lt; &gt; | # $ * } { , + = [ ]
  • Must not contain an ellipsis (…) or a double period (..)
  • Must not start with an underscore (_)
  • Must not start or end with a period (.)

Project names

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

Names you assign to 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 project collection, the SharePoint Web application that supports the collection, or the instance of SQL Server Reporting Services that supports the collection

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, SERVER, SignalR, DefaultCollection, or Web
  • 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_Themes, App_WebResources, bin, or web.config. For more information about reserved names, see Naming Files, Paths, and Namespaces.

Special characters

  • Must not contain any Unicode control characters or surrogate characters
  • Must not contain the following printable characters: / : \ ~ &amp; % ; @ &#39; &quot; ? &lt; &gt; | # $ * } { , + = [ ]
  • Must not start with an underscore (_)
  • Must not start or end with a period (.)

Security groups

Azure DevOps security groups enable you to apply certain rights or permissions to a group of users.

On-premises groups may consist of Active Directory group accounts, Azure DevOps security groups , Windows user accounts, Windows group accounts, or any mixture of these types. For more information, see Add AD/Azure AD users or groups to a built-in security group.

Security groups that you add must conform to the following restrictions.

Restriction type

Restriction

Security 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 project collection

Reserved group names

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

Special characters

  • Must not include the following printable characters: "/ \ [ ] : | < > + = ; ? *
  • Must not include non-printable characters in the ASCII value range of 1-31
  • Must not end in a period (.)
  • Must not include commas (,)

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

Team Foundation Build is a separate installation from the TFS application tier, data tier, or Visual Studio client. You may choose 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 leads 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 project are 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 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 names

Team names identify a group of individuals or groups that collectively work together as a team in a project. Team members use this name to connect to the team or to query against members defined for a team.

As such, team names must conform to conventions that allow them to be rendered as part of a valid URL. Each team name must be unique within a single project. However, there aren't any restrictions on using the same team name in different projects within a 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

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 File Names, Paths, and Namespaces.

Special characters

  • Must not contain any Unicode control characters or surrogate characters
  • Must not contain the following printable characters: / : \ ~ &amp; % ; @ &#39; &quot; ? &lt; &gt; | # $ * } { , + = [ ]
  • Must not contain an ellipsis (…) or a double period (..)
  • Must not start with an underscore (_)
  • Must not start or end with a period (.)

User account names

User accounts identify people added to a project or project collection. User accounts might correspond to entries within Active Directory, Azure Active Directory, Windows server group.

User accounts that you add to an organization or collection must conform to the following restrictions. To add user accounts to a project, see Add users to a project or team.

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 project collection

Reserved group names

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

Special characters

  • Must not include the following printable characters: "/ \ [ ] : | < > + = ; ? *
  • Must not include non-printable 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

Wiki page and file names

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.