Azure file naming and referencing restrictions

All access to Azure storage services takes place through an Azure storage account. The storage account is the highest level of the namespace for accessing each of the fundamental services. It is also the basis for authentication. Each storage account contains the following resources; shares, directories and files.

Storage account structure is as follows:

• A Storage account can contain zero or more Azure File shares.
• A Share contains properties, metadata, and zero or more files or directories.
• A Directory contains properties, and zero or more files or directories.
• A File is any single entity comprising binary data, properties, and metadata.

The naming conventions for these resources, together with pathnames and metadata, are important and must be followed.

This article is provided for information only. It identifies the required naming conventions, and is drawn from Microsoft's own article, Naming and Referencing Shares, Directories, Files, and Metadata.  

Naming and referencing

The following paragraphs describe naming and referencing requirements for:

• Resource names
• Share names
• Directory and File names
• Pathnames
• Metadata names
• Resource URI syntax

Resource names

The URI (Universal Resource Identifier) to reference a resource (share, directory or file) must be unique. Within a given storage account, every share must have a unique name. Every file within a given share or directory must also have a unique name within that share or directory.

If you attempt to create a share, directory, or file with a name that violates naming rules, the request will fail with status code 400 (Bad Request).

Share names

The rules for Azure File service share names are more restrictive than what is prescribed by the SMB (Server Message Block) protocol for SMB share names, so that the Blob and File services can share similar naming conventions for containers and shares. The naming restrictions for shares are as follows:

• A share name must be a valid DNS name.
• Share names must start with a letter or number, and can contain only letters, numbers, and the dash (-) character.
• Every dash (-) character must be immediately preceded and followed by a letter or number; consecutive dashes are not permitted in share names.
• All letters in a share name must be lowercase.
• Share names must be from 3 through 63 characters long.

Directory and File names

The Azure File service naming rules for directory and file names are as follows:

• Directory and file names are case-preserving and case-insensitive.
• Directory and file component names must be no more than 255 characters in length.
• Directory names cannot end with the forward slash character (/). If provided, it will be automatically removed.
• File names must not end with the forward slash character (/).
• Reserved URL characters must be properly escaped.
• The following characters are not allowed: " \ / : | < > * ?
• Illegal URL path characters not allowed. Code points like \uE000, while valid in NTFS filenames, are not valid Unicode characters. In addition, some ASCII or Unicode characters, like control characters (0x00 to 0x1F, \u0081, etc.), are also not allowed. For rules governing Unicode strings in HTTP/1.1 see RFC 2616, Section 2.2: Basic Rules and RFC 3987.
• The following file names are not allowed: LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, PRN, AUX, NUL, CON, CLOCK$, dot character (.), and two dot characters (..).

Pathnames

A pathname comprises one or more pathname components (directory or file name) separated by the forward-slash (/) character. All pathname components other than the last component denote directories. The last component denotes a directory or a file. The following naming rules apply:

• A pathname may be no more than 1,024 characters in length.
• A pathname is composed of one or more pathname components separated by the forward-slash (/) character.
• The depth of subdirectories in the path cannot exceed 250.
• The same name cannot be used for a file and a directory that share the same parent directory. For example, a file and a directory that are each named "data" cannot exist under the same parent path.

Metadata names

Metadata (data that provides information about other data) for a share or file resource is stored as name-value pairs associated with the resource. Directories do not have metadata. Metadata names must adhere to the naming rules for C# identifiers.

Note that metadata names preserve the case with which they were created, but are case-insensitive when set or read. If two or more metadata headers with the same name are submitted for a resource, the Azure File service returns status code 400 (Bad Request).

Resource URI syntax

Each resource (share, directory or file) within a storage account has a corresponding base identifier (URI), which refers to the resource itself. The following table identifies the syntax and gives one or more examples.