Share via

Naming and referencing shares, directories, files, and metadata

  • Article

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.

Resource names

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).

Share names

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 hyphen/minus (-) character.
  • Every hyphen/minus (-) character must be immediately preceded and followed by a letter or number; consecutive hyphens aren't permitted in share names.
  • All letters in a share name must be lowercase.
  • Share names must be from 3 through 63 characters long.

The following table compares the naming restrictions for Azure Files and Azure Blob storage:

Naming and Referencing Containers, Blobs, and Metadata SMB Share Name Restrictions
• A container name must be a valid DNS name.
• Container names must start with a letter or number, and can contain only letters, numbers, and the hyphen/minus (-) character.
• Every hyphen/minus (-) character must be immediately preceded and followed by a letter or number; consecutive hyphens aren't permitted in container names.
• All letters in a container name must be lowercase.
• Container names must be 3 to 63 characters long.		 • A share name must be no more than 80 characters in length.
• The following characters are illegal in a share name: \ / [ ] : ¦ < > + = ; , * ? "
• Control characters in range 0x00 through 0x1F, inclusive, are illegal in a share name.
• All other Unicode characters are legal.
• Names are case preserving and case insensitive.

Directory and file names

Azure Files enforces the following naming rules for directory and file names:

  • 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 can't 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 aren't allowed: " \ / : | < > * ?
  • Illegal URL path characters aren't allowed. Code points like \uE000, while valid in NTFS filenames, aren't valid Unicode characters. In addition, some ASCII or Unicode characters, like control characters (0x00 to 0x1F), are also not allowed. For rules governing Unicode strings in HTTP/1.1 see RFC 2616, Section 2.2: Basic Rules and RFC 3987.
  • Invalid Unicode characters (referred to as invalid surrogate pairs) are not supported.
  • The following file names aren't 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 (..).
  • Starting with version 2021-12-02, directory and file names support U+FFFE and U+FFFF characters through all operations. These characters are also supported through SMB and REST protocols. List Directory and Files and List Handles operations will need special handling for these characters as mentioned in their respective documentation.

By default, dot (.) characters at the end of directory and file names in request URLs are ignored or left out.

  • For example, if a file named file1... is being created, the dots at the end will be ignored, and a file named file1 will be created. The same applies to directories in the path. If a file creation request includes the path \Dir1\Dir2…\File1 then the file will be created at \Dir1\Dir2\File1.
  • However, starting with version 2022-11-02, the default behavior can be overridden by setting the header x-ms-allow-trailing-dot to true in the URL request.
  • For example, if you want to create a file named file1... and include the trailing dots, the x-ms-allow-trailing-dot should be included in request header and set to be true. The same applies for creating directory names.
  • In case of a file copy request, if you want to include trailing dots in the source file name, the x-ms-source-allow-trailing-dot header must be set to true. For more information, check out the available header options for each individual REST API.

The following table compares the naming restrictions for Azure Files and Azure Blob storage:

Naming and Referencing Containers, Blobs, and Metadata SMB Protocol Name Restrictions
• A blob name must be at least one character long and can't be more than 1,024 characters long.
• Blob names are case-sensitive.
• Reserved URL characters must be properly escaped.
• Blob names can end with a virtual directory delimiter, such as a forward slash (/)
• Illegal URL path characters not allowed: Code points like \uE000, while valid in NTFS filenames, aren't valid Unicode characters. In addition, some ASCII or Unicode characters, like control characters (0x00 to 0x1F), are also not allowed. For rules governing Unicode strings in HTTP/1.1 see RFC 2616, Section 2.2: Basic Rules and RFC 3987.		 • A path name may be no more than 32,760 characters in length.
• Each path name component (file / directory) may be no more than 255 characters in length.
• A path name is composed of one or more path name components separated by the (\) backward slash character.
• Path name is case preserving and case insensitive (two names which differ only in case is not allowed).
• Can't have a directory path that is the same as a file path.
• The following characters are illegal in a component name: \ / : ¦ < > * ? "
• Control characters in range 0x00 through 0x1F, inclusive, are illegal in a share name.

Path names

A path name is composed of one or more path name components (directory or file name) separated by the forward-slash (/) character. All path name 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 path name may be no more than 2,048 characters in length. Individual components in the path can be a maximum of 255 characters in length.
  • A path name is composed of one or more path name components separated by the forward-slash (/) character.
  • The depth of subdirectories in the path can't exceed 250.
  • The same name can't 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 can't exist under the same parent path.

Metadata names

Metadata for a share or file resource is stored as name-value pairs associated with the resource. 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 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:

https://myaccount.file.core.windows.net

For a share, the base URI includes the name of the account and the name of the share:

https://myaccount.file.core.windows.net/myshare

For a directory, the base URI includes the name of the account, the name of the share, and the path of the directory:

https://myaccount.file.core.windows.net/myshare/myparentdir/mydir

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

See also