ShareDirectoryClient class

Creates an instance of DirectoryClient.

new ShareDirectoryClient(url: string, credential?: Credential | TokenCredential, options?: ShareClientOptions)

Parameters

Creates an instance of DirectoryClient.

new ShareDirectoryClient(url: string, pipeline: Pipeline, options?: ShareClientConfig)

Parameters

The name of the directory

string name

Property Value

The full path of the directory

string path

Property Value

The share name corresponding to this directory client

string shareName

Property Value

accountName: string

Property Value

Inherited From StorageClient.accountName

URL string value.

url: string

Property Value

Inherited From StorageClient.url

Creates a new directory under the specified share or parent directory.

See https://learn.microsoft.com/rest/api/storageservices/create-directory

function create(options?: DirectoryCreateOptions): Promise<DirectoryCreateResponse>

Parameters

Returns

Response data for the Directory operation.

Creates a new file or replaces a file under this directory. Note it only initializes the file with no content.

See https://learn.microsoft.com/rest/api/storageservices/create-file

function createFile(fileName: string, size: number, options?: FileCreateOptions): Promise<{ fileClient: ShareFileClient, fileCreateResponse: FileCreateResponse }>

Parameters

Returns

File creation response data and the corresponding file client.

Creates a new directory under the specified share or parent directory if it does not already exists. If the directory already exists, it is not modified.

See https://learn.microsoft.com/rest/api/storageservices/create-directory

function createIfNotExists(options?: DirectoryCreateOptions): Promise<DirectoryCreateIfNotExistsResponse>

Parameters

Returns

Creates a new subdirectory under this directory.

See https://learn.microsoft.com/rest/api/storageservices/create-directory

function createSubdirectory(directoryName: string, options?: DirectoryCreateOptions): Promise<{ directoryClient: ShareDirectoryClient, directoryCreateResponse: DirectoryCreateResponse }>

Parameters

Returns

Directory create response data and the corresponding DirectoryClient instance.

Removes the specified empty directory. Note that the directory must be empty before it can be deleted.

See https://learn.microsoft.com/rest/api/storageservices/delete-directory

function delete(options?: DirectoryDeleteOptions): Promise<DirectoryDeleteResponse>

Parameters

Returns

Response data for the Directory Delete operation.

Removes the specified file under this directory from the storage account. When a file is successfully deleted, it is immediately removed from the storage account's index and is no longer accessible to clients. The file's data is later removed from the service during garbage collection.

Delete File will fail with status code 409 (Conflict) and error code SharingViolation if the file is open on an SMB client.

Delete File is not supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot will fail with 400 (InvalidQueryParameterValue)

See https://learn.microsoft.com/rest/api/storageservices/delete-file2

function deleteFile(fileName: string, options?: FileDeleteOptions): Promise<FileDeleteResponse>

Parameters

Returns

File deletion response data.

Removes the specified empty directory if it exists. Note that the directory must be empty before it can be deleted.

See https://learn.microsoft.com/rest/api/storageservices/delete-directory

function deleteIfExists(options?: DirectoryDeleteOptions): Promise<DirectoryDeleteIfExistsResponse>

Parameters

Returns

Removes the specified empty sub directory under this directory. Note that the directory must be empty before it can be deleted.

See https://learn.microsoft.com/rest/api/storageservices/delete-directory

function deleteSubdirectory(directoryName: string, options?: DirectoryDeleteOptions): Promise<DirectoryDeleteResponse>

Parameters

Returns

Directory deletion response data.

Returns true if the specified directory exists; false otherwise.

NOTE: use this function with care since an existing directory might be deleted by other clients or applications. Vice versa new directories might be added by other clients or applications after this function completes.

function exists(options?: DirectoryExistsOptions): Promise<boolean>

Parameters

Returns

Force close all handles for a directory.

See https://learn.microsoft.com/rest/api/storageservices/force-close-handles

function forceCloseAllHandles(options?: DirectoryForceCloseHandlesSegmentOptions): Promise<CloseHandlesInfo>

Parameters

Returns

Force close a specific handle for a directory.

See https://learn.microsoft.com/rest/api/storageservices/force-close-handles

function forceCloseHandle(handleId: string, options?: DirectoryForceCloseHandlesOptions): Promise<DirectoryForceCloseHandlesResponse>

Parameters

Returns

Creates a ShareDirectoryClient object for a sub directory.

function getDirectoryClient(subDirectoryName: string): ShareDirectoryClient

Parameters

Returns

The ShareDirectoryClient object for the given subdirectory name.

Example usage:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const shareClient = serviceClient.getShareClient(shareName);
const directoryClient = shareClient.getDirectoryClient(directoryName);
await directoryClient.create();

Creates a ShareFileClient object.

function getFileClient(fileName: string): ShareFileClient

Parameters

Returns

A new ShareFileClient object for the given file name.

Example usage:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const content = "Hello World!";
const fileName = `newdirectory${+new Date()}`;
const fileClient = directoryClient.getFileClient(fileName);
await fileClient.create(content.length);
console.log(`Create file ${fileName} successfully`);

// Upload file range
await fileClient.uploadRange(content, 0, content.length);
console.log(`Upload file range "${content}" to ${fileName} successfully`);

Returns all system properties for the specified directory, and can also be used to check the existence of a directory. The data returned does not include the files in the directory or any subdirectories.

See https://learn.microsoft.com/rest/api/storageservices/get-directory-properties

function getProperties(options?: DirectoryGetPropertiesOptions): Promise<DirectoryGetPropertiesResponse>

Parameters

Returns

Response data for the Directory Get Properties operation.

Returns an async iterable iterator to list all the files and directories under the specified account.

.byPage() returns an async iterable iterator to list the files and directories in pages.

Example using for await syntax:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let i = 1;
for await (const item of directoryClient.listFilesAndDirectories()) {
  if (item.kind === "directory") {
    console.log(`${i} - directory\t: ${item.name}`);
  } else {
    console.log(`${i} - file\t: ${item.name}`);
  }
  i++;
}

Example using iter.next():

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let i = 1;
const iter = directoryClient.listFilesAndDirectories();
let { value, done } = await iter.next();
while (!done) {
  if (value.kind === "directory") {
    console.log(`${i} - directory\t: ${value.name}`);
  } else {
    console.log(`${i} - file\t: ${value.name}`);
  }
  ({ value, done } = await iter.next());
  i++;
}

Example using byPage():

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let i = 1;
for await (const response of directoryClient
  .listFilesAndDirectories()
  .byPage({ maxPageSize: 20 })) {
  console.log(`Page ${i++}:`);
  for (const item of response.segment.directoryItems) {
    console.log(`\tdirectory: ${item.name}`);
  }
  for (const item of response.segment.fileItems) {
    console.log(`\tfile: ${item.name}`);
  }
}

Example using paging with a marker:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let iterator = directoryClient.listFilesAndDirectories().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

for await (const item of response.segment.directoryItems) {
  console.log(`\tdirectory: ${item.name}`);
}

for await (const item of response.segment.fileItems) {
  console.log(`\tfile: ${item.name}`);
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken
iterator = directoryClient
  .listFilesAndDirectories()
  .byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

for await (const item of response.segment.directoryItems) {
  console.log(`\tdirectory: ${item.name}`);
}

for await (const item of response.segment.fileItems) {
  console.log(`\tfile: ${item.name}`);
}

function listFilesAndDirectories(options?: DirectoryListFilesAndDirectoriesOptions): PagedAsyncIterableIterator<({ kind: "file" } & FileItem) | ({ kind: "directory" } & DirectoryItem), DirectoryListFilesAndDirectoriesSegmentResponse, PageSettings>

Parameters

Returns

An asyncIterableIterator that supports paging.

Returns an async iterable iterator to list all the handles. under the specified account.

.byPage() returns an async iterable iterator to list the handles in pages.

Example using for await syntax:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

for await (const handle of directoryClient.listHandles()) {
  console.log(`Handle: ${handle.handleId}`);
}

Example using iter.next():

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const handleIter = directoryClient.listHandles();
let { value, done } = await handleIter.next();
while (!done) {
  console.log(`Handle: ${value.handleId}`);
  ({ value, done } = await handleIter.next());
}

Example using byPage():

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let i = 1;
for await (const response of directoryClient.listHandles().byPage({ maxPageSize: 20 })) {
  console.log(`Page ${i++}:`);
  for (const handle of response.handleList || []) {
    console.log(`\thandle: ${handle.handleId}`);
  }
}

Example using paging with a marker:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

let iterator = directoryClient.listHandles().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

for await (const handle of response.handleList || []) {
  console.log(`\thandle: ${handle.handleId}`);
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken
iterator = directoryClient.listHandles().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

for await (const handle of response.handleList || []) {
  console.log(`\thandle: ${handle.handleId}`);
}

function listHandles(options?: DirectoryListHandlesOptions): PagedAsyncIterableIterator<HandleItem, DirectoryListHandlesResponse, PageSettings>

Parameters

Returns

Renames a directory. This API only supports renaming a directory in the same share.

function rename(destinationPath: string, options?: DirectoryRenameOptions): Promise<{ destinationDirectoryClient: ShareDirectoryClient, directoryRenameResponse: DirectoryRenameResponse }>

Parameters

Returns

Response data for the file renaming operation.

Example usage:

import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential,
);

const shareName = "<share name>";
const directoryName = "<directory name>";
const destinationPath = "<destination path>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

await directoryClient.rename(destinationPath);

Updates user defined metadata for the specified directory.

See https://learn.microsoft.com/rest/api/storageservices/set-directory-metadata

function setMetadata(metadata?: Metadata, options?: DirectorySetMetadataOptions): Promise<DirectorySetMetadataResponse>

Parameters

Returns

Response data for the Directory Set Metadata operation.

Sets properties on the directory.

See https://learn.microsoft.com/rest/api/storageservices/set-directory-properties

function setProperties(properties?: DirectoryProperties): Promise<DirectorySetPropertiesResponse>

Parameters

Returns