Naming and Referencing Shares, Directories, Files, and Metadata
Updated: February 26, 2015
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 comprised of binary data, properties, and metadata.
The URI to reference a 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).
The rules for File service share names are more restrictive than what is prescribed by the SMB 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.
For those interested, the below table shows a comparison of the naming restrictions for the SMB protocol as well as for the Blob service today:
|Naming and Referencing Containers, Blobs, and Metadata||SMB Share Name Restrictions|
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 may optionally end with the forward slash character (/).
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 (
\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 (..).
For those interested, the below table shows a comparison of the naming restrictions for the SMB protocol as well as the Blob service today:
|Naming and Referencing Containers, Blobs, and Metadata||SMB Protocol Name Restrictions|
A pathname is composed of one or more pathname components (directory or file name) separated by the forward-slash (/) character. All pathname components other than the last path name component denote directories. The last path name 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
datacannot exist under the same parent path.
Metadata 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).
Each resource has a corresponding base URI, which refers to the resource itself. For the storage account, the base URI includes the name of the account only:
For a share, the base URI includes the name of the account and the name of the share:
For a directory, the base URI includes the name of the account, the name of the share, and the path of the directory:
For a file, the base URI includes the name of the account, name of the share, and the path of the file:
https://myaccount.file.core.windows.net/myshare/myfile https://myaccount.file.core.windows.net/myshare/mydir/myfile https://myaccount.file.core.windows.net/myshare/myparentdir/mydir/myfile
ConceptsFile Service Concepts